OIDC - OpenID Connect

Startseite > OIDC - OpenID Connect

• OIDC - OpenID Connect
  • Einleitung
  • Technische Voraussetzungen
    • Was wird grundlegend benötigt?
    • Discovery Konfiguration bedenken
  • Kommunikation via PKCE Flow
    • Authorization Endpoint
    • Token Endpoint
    • UserInfo Endpoint
  • Anbindung des Relying Party Clients
    • Beispiel einer Client-Registrierung
      • Authentifizierungsverfahren des Clients
      • Audience und Resource Server

Einleitung

Diese Seite beschreibt die OIDC-Anbindung an den Shibboleth OpenId Provider der Technischen Universität Dresden auf Basis des eingesetzten OIDC-Plugins. Ziel ist die Registrierung eines OIDC Relying Party Clients, der die Nutzerauthentifizierung über den OP der Technischen Universität Dresden vornimmt.

Technische Voraussetzungen

Was wird grundlegend benötigt?

Für eine OIDC-Anbindung werden mindestens folgende Informationen und Komponenten benötigt:

1. Eine eindeutige client_id + secret - wird vom ZIH vorgegeben
2. Mindestens eine feste redirect_uri des Dienstes - wird von der Anwendung (RP) vorgegeben
3. Ein OIDC-fähiger Client, der den authorization_code Flow unterstützt
4. Der Scope openid
5. Ein zwischen RP und OP abgestimmtes Client-Authentifizierungsverfahren - z.B. client_secret_basic
6. Eine Festlegung, welche Claims bzw. Attribute vom RP tatsächlich benötigt werden - Anwendungsdokumentation konsolidieren

Discovery Konfiguration bedenken

Damit ein OIDC Client mit unserem OP kommunizieren kann, sollte mindestens ein Blick in die Discovery geworfen werden, um die darin definierten Flows zu unterstützen.

Kommunikation via PKCE Flow

Vorgang	Beschreibung
1	Nutzer:in wählt Anmelden in Anwendung (RP) aus
2	RP initiiert eine Weiterleitung mit client_id zum OP
3	Weiterleitung zum OP zur Nutzerauthentifizierung am Authentication Endpoint. client_id + redirect_uri muss registriert sein!
4	Standard Login Workflow am OP/IdP
5	Nach erfolgter Nutzer-Legitimation, Übergabe des auth_code an Nutzer:in (Webbrowser) mit Weiterleitung zur redirect_uri
6	Übergabe des auth_code an redirect_uri der RP
7	Einlösen des auth_code der RP am OP in Verbindung der client_id + secret über den Token Endpoint
8	OP generiert für RP einen access_token für weitere Daten/Ressourcen und einen id_token als Identitätskennung
9	Abfrage des OP mittels access_token für weitere Nutzerdaten über UserInfo Endpoint

Vorgang 1-6 findet im Frontchannel statt. Diese Übertragung ist ähnlich zur SAML Kommunikation und beinhaltet die sicherheitsbedenkliche Komponente: Webbrowser. Daten im Webbrowser können bei einen kompromittierten Rechner mitgeschnitten werden. Die SAML Assertion sollte daher zusätzlich verschlüsselt sein. Vorgang 7-9 findet im Backchannel statt, sodass sensible Daten über einen eigenen Kanal verlaufen, der nicht mitgeschnitten werden kann.

Die hier relevanten und bekannten Endpoints wären:

Endpoint	URL
Authorization	https://idp.tu-dresden.de/idp/profile/oidc/authorize
Token	https://idp.tu-dresden.de/idp/profile/oidc/token
UserInfo	https://idp.tu-dresden.de/idp/profile/oidc/userinfo

Authorization Endpoint

Der Authorization Endpoint startet die browserbasierte Anmeldung der Nutzer:innen. Der Dienst leitet den Browser mit einer OIDC Authentication Request an diesen Endpunkt weiter. Im Standardfall werden dabei mindestens client_id, redirect_uri, response_type=code, scope=openid und ein state übertragen.

Bei der Verwendung von PKCE kommen zwei weitere Parameter hinzu:

• code_challenge: SHA-256-Hash eines zufällig erzeugten code_verifier
• code_challenge_method: S256

Der code_verifier wird erst im nächsten Schritt am Token Endpoint mitgeschickt. Damit kann ein abgefangener Authorization Code nicht eingelöst werden — nur der ursprüngliche Client kennt den Verifier.

Token Endpoint

Der Token Endpoint wird serverseitig vom Client (RP) angesprochen. Dort tauscht der Client den zuvor erhaltenen Authorization Code gegen Tokens aus. An diesem Endpunkt erfolgt auch die Client-Authentifizierung, zum Beispiel per client_secret_basic oder private_key_jwt. Bei PKCE-Flow wird zusätzlich der code_verifier übertragen.

UserInfo Endpoint

Der UserInfo Endpoint liefert Claims zur authentifizierten Person auf Basis eines gültigen Access Tokens. Welche Claims dort tatsächlich erscheinen, hängt sowohl von den angeforderten Scopes als auch von der für den Client freigegebenen Attributmenge ab.

Anbindung des Relying Party Clients

Für die Anbindung Ihrer RP an unseren OP folgen Sie bitte den Schritten unter: Anbindungsprozess. Die hier zusätzlich erwähnten Informationen dienen lediglich dem besseren Verständnis.

Eine Registrierung via Dynamic Client Registration (DCR) wird nicht unterstützt. Die Angaben des folgenden Client Beispiel müssen manuell und administrativ erfolgen.

Beispiel einer Client-Registrierung

Die lokal gepflegte Client-Information entspricht strukturell einem OIDC-Client-Metadatensatz. Ein vereinfachtes Beispiel ist:

{
  "client_id": "example_client",
  "client_secret": "example-secret",
  "client_name": "Example Application",
  "redirect_uris": [
    "https://example.com/callback"
  ],
  "response_types": [
    "code"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "scope": "openid",
  "token_endpoint_auth_method": "client_secret_basic",
  "access_token_type": "jwt"
}

• "access_token_type"-Angabe ist optional

Die client_id und das client_secret werden nach Abschluss der Registrierung mitgeteilt. Alle weiteren Informationen müssen bei der Antragsstellung bekannt sein, da diese im Nachgang abgefragt werden.

Authentifizierungsverfahren des Clients

Es muss definiert sein, wie die Relying Party sich am OP beim Token Endpoint authentifiziert. Der OP unterstützt folgende Verfahren, nach Sicherheitsniveau aufsteigend:

1. client_secret_post - Secret wird als POST-Parameter übertragen. Für Debug, nicht in Produktion verwenden, da Secret in den Server-Logs erscheinen kann
2. client_secret_basic - Secret wird per HTTP Basic Auth im Header übertragen (gängiger Standard)
3. client_secret_jwt - Client signiert ein JWT mit dem gemeinsamen Secret. OP prüft die Signatur. Das Secret selbst wird nicht übertragen (symmetrisches Verfahren)
4. private_key_jwt - Client signiert ein JWT mit seinem private Key. OP prüft mit dem registrierten Public Key. Kein geteiltes Secret notwendig (asymmetrisches Verfahren)

Die Herausgabe des Access Token kann nur mittels authorization_code erfolgen, da kein anderer Grant Type unterstützt wird.

Audience und Resource Server

Für reines OIDC-Login werden in der Regel nur Token und UserInfo Endpoint benötigt. Sobald ein Dienst jedoch JWT Access Tokens gegenüber einer eigenen API oder einem Resource Server auswerten will, muss auch das Thema audience berücksichtigt werden.

Das ist insbesondere dann relevant, wenn:

1. der Client JWT Access Tokens erwartet access_token_type
2. ein Backend oder API-Gateway das Claim aud prüft
3. ein Access Token nicht nur zum UserInfo-Aufruf, sondern für eigene geschützte APIs verwendet werden soll

Je nach Anwendungsfall muss dafür auf OP-Seite eine gesonderte Profil- oder Bean-Konfiguration vorhanden sein, wie etwa eine explizite Audience-Unterstützung im Token-Profil. Diese Anforderung sollte daher frühzeitig im Anbindungsprozess benannt werden.