Developer Guide

SSO-Integration in wenigen Schritten.

Klare Schritte für schnelle Integrationen – ohne Abstriche bei Sicherheit und Standards.

Was du brauchst

  • Client Registrierter OIDC-Client mit Redirect-URIs.
  • Scopes openid plus optionale Claims.
  • Callback Endpoint für den Authorization-Code.

1) Discovery & Endpoints

Discovery liefert Endpunkte und JWKS für die Signaturprüfung. 

GET /.well-known/openid-configuration
GET /.well-known/jwks.json

2) Authorization Request

Der Client startet den Login mit response_type=code und einem sicheren state/nonce. 

/oidc/authorize?client_id=...&redirect_uri=...
&response_type=code&scope=openid%20profile%20email
&state=...&nonce=...

3) Token Exchange

Der Code wird am Token-Endpoint gegen id_token und access_token getauscht. 

POST /oidc/token
grant_type=authorization_code
code=...&client_id=...&redirect_uri=...

4) UserInfo & Session

Die Benutzerinfos kommen über den UserInfo-Endpoint mit dem Access Token. 

GET /oidc/userinfo
Authorization: Bearer <access_token>

5) Token-Validierung

Prüfe id_token Signatur und Claims gegen JWKS, validiere aud, iss, exp und nonce. 

kid aus JWT-Header lesen
JWKS-Key laden
Signatur + Claims validieren

Callback-Handling

Tausche den Code serverseitig, validiere state und baue die Session auf. 

if (state mismatch) -> 400
tokens = exchange(code)
user = userinfo(access_token)
session.login(user)

Integration in 4 Schritten

1
Discovery

Endpoints und JWKS automatisch laden.

2
Authorize

Login mit state/nonce starten.

3
Token

Code gegen Tokens tauschen.

4
UserInfo

Claims basierend auf Scopes holen.

Code Discovery (Beispiel) 
https://sso.eurip.com/.well-known/openid-configuration
Code JWKS (Beispiel) 
https://sso.eurip.com/.well-known/jwks.json
Code Token Exchange (curl) 
https://sso.eurip.com/oidc/token
Code UserInfo (curl) 
https://sso.eurip.com/oidc/userinfo

lib-php-eurip-sso (optional)

Für Symfony-Apps steht das Bundle lib-php-eurip-sso zur Verfügung. Es kapselt OIDC-Config und Token-Handling. 

// composer.json
{
  "repositories": {
    "lib-php-eurip-sso": { "type": "path", "url": "../lib-php-eurip-sso" }
  },
  "require": { "jostkleigrewe/lib-php-eurip-sso": "dev-develop" }
}

Best Practices

  • State Immer serverseitig validieren.
  • Nonce Schützt vor Replay-Angriffen.
  • JWKS Signaturen immer prüfen.
Detaillierte Schritt-für-Schritt-Doku folgt in unserem Developer Portal.
Code Symfony‑Beispiel (verkürzt) 
// CallbackController (vereinfacht)
if ($state !== $session->get('oidc_state')) {
    throw new BadRequestHttpException('Invalid state');
}

$tokens = $http->request('POST', $tokenEndpoint, [
    'body' => [
        'grant_type' => 'authorization_code',
        'code' => $code,
        'client_id' => $clientId,
        'redirect_uri' => $redirectUri,
    ],
])->toArray();

$userInfo = $http->request('GET', $userInfoEndpoint, [
    'headers' => ['Authorization' => 'Bearer ' . $tokens['access_token']],
])->toArray();

// userSessionLogin($userInfo['sub'], $userInfo['email']);
Code Konfiguration (Beispiel) 
OIDC_ISSUER=https://sso.eurip.com
OIDC_CLIENT_ID=your-app
OIDC_REDIRECT_URI=https://app.example.com/auth/callback

Häufige Fehlerfälle

  • Redirect-URI stimmt nicht exakt mit dem Client überein.
  • State/Nonce fehlt oder wird nicht geprüft.
  • Token-Signatur wird nicht gegen JWKS validiert.
  • Scopes enthalten kein openid.

Integrations‑Checkliste

Bereich Beschreibung Status
Discovery Endpunkte dynamisch laden. Empfohlen
JWKS Prüfung Signaturen verifizieren. Pflicht
State/Nonce CSRF/Replay-Schutz. Pflicht
Scope-Minimierung Nur notwendige Daten anfordern. Best Practice

FAQ zur Integration

Die Redirect‑URI muss exakt mit der Client‑Konfiguration übereinstimmen.

Ja. Signatur + Claims sind Pflicht, sonst ist die Identität nicht vertrauenswürdig.

Eine kleine Toleranz (z.B. 60s) für iat/exp einbauen.

Bereit für die Anbindung?

Starte mit dem Developer Guide oder prüfe die SSO‑Details.

Developer Guide SSO erklärt