Grundlage des "Zentralen Logins"  (ZL oder DGK-Login) sind OAUTH 2.0 und OpenID Connect.

Die Anleitung dient der Veranschaulichung des Ablaufs. 

Konkrete Werte für URLs, ClientID und ClientSecret werden von der DGK zur Verfügung gestellt und sind nicht Bestandteil dieser Anleitung.

Zur Verbesserung des Verständnisses sind unter "3. Anmerkungen, Beispiele, Weblinks" weiterführende Informationen in [] angeführt.

Hinweis:

Die weiterführenden Informationen führen zu Websites Dritter. Websites Dritter liegen außerhalb der Verantwortung der DGK. Sollten Sie diesen folgen, so haben diese ihre eigenen Datenschutzrichtlinien. Für diese Richtlinien übernimmt die Deutsche Gesellschaft für Kardiologie, Herz- und Kreislaufforschung e.V. - German Cardiac Society weder Verantwortung noch Haftung.

1. Logischer Ablauf für die Kommunikation

  • Client fragt den .well-known-Configuration-Endpoint ab für die speziellen Endpoints.
  • Client fragt den Authorization-Endpoint ab mit dem PKCE-Authorisierungs-Flow und leitet den Benutzer im Browser zu besagtem Endpoint, in dem der Benutzer seine Login-Daten eingibt.
  • Benutzer meldet sich am zentralen Login an. Der ZL leitet den Browser zurück zum Client.
  • Der Client fragt mit den erhaltenen Daten im Hintergrund den Token-Endpoint ab und erhält das ID- und das Access-Token.
  • Der Client kann mit dem Access-Token, sofern notwendig, die API im Benutzerkontext abfragen.
  • Der Client kann dem ID-Token u.a. die, für den ZL eindeutige, ID des Benutzers entnehmen und damit in seiner lokalen Datenbank den entsprechenden Eintrag finden, sofern vorhanden. Im Folgenden wird diese Account-ID genannt.

2. Technischer Ablauf

2.1 .well-known/openid-configuration

Zuerst erfolgt eine GET-Abfrage auf .well-known. Eine Beschreibung mit Beispiel lässt sich unter [1] nachlesen. Relevant aus der Antwort sind hier die folgenden vier Felder:

  • authorization_endpoint
  • token_endpoint
  • issuer
  • userinfo_endpoint

2.2 authorization_endpoint

Es wird das PKCE Verfahren [2] verwendet. Hier wird der Browser zur Login-Maske des ZL geleitet. Bei der GET Anfrage an den authorization_endpoint werden dabei folgende Parameter mitgegeben:

  • client_id: Ihre individuelle ClientId wie von der DGK erhalten
  • redirect_uri: Die RedirectUri zu Ihrer Webseite nach erfolgreichem Login. Hier müssen die Rückgabewerte (siehe weiter unten) entgegengenommen und verarbeitet werden. Der exakte String so wie Sie ihn mit der DGK abgesprochen haben muss angegeben werden, es sind keine Wildcards erlaubt. Bei Bedarf können Sie die Eintragung von mehreren URLs anfragen, z.B. für individuelle URLs für den Live-, Test- und Entwicklungsbetrieb.
  • response_type: „code"
  • scope: Es werden die scopes aus der .well-known Antwort unterstützt. Beispiel: „openid profile api1 roles Zugriffsberechtigungen". Scope openid ist notwendig, damit auch ein ID-Token erhalten werden kann nach dem OpenId Connect Verfahren.
  • nonce: Ein zufälliger String, welcher gemerkt werden muss. Dient der Sicherheit.
  • state: Ein zufälliger String, welcher gemerkt werden muss. Dient der Sicherheit.
  • code_challenge: SHA256 gehashter Wert des code_verifier (Erläuterung folgt).
  • code_challenge_method: „S256"
  • x-client-SKU: „ID_NETSTANDARD1_4"
  • x-client-ver: „5.2.0.0"

2.3 Erläuterung Code Challenge

Wie in [2] erläutert, nutzt das PKCE Verfahren zusätzliche Code-Parameter, um die Sicherheit gegenüber Malware, welche den Authorization-Flow abfängt, zu erhöhen.
Zuerst wird ein code_verifier zufällig erstellt und lokal gespeichert. Dieser wird mit SHA256 gehashed und in dem Parameter code_challenge an den authorization_endpoint mitgegeben.
Wenn später der token_endpoint angefragt wird, um ID Token und Access Token zu erhalten, wird u.a. der gemerkte code_verifier mitgesendet, welcher der Beispiel-Malware nicht bekannt sein kann.

2.4 Verarbeitung Antwort authorization_endpoint und Anfrage token_endpoint

Nach erfolgreichem Login wird der Browser des Benutzers mit einem GET weitergeleitet an die redirect_uri aus der Anfrage. Die URL enthält die folgenden Parameter:

  • code: Wird bei Anfrage eines Tokens benötigt, also merken.
  • scope: Welche scopes aus der Anfrage sind erfüllt worden.
  • state: Entspricht dem „state" Parameter aus der Anfrage. Kann genutzt werden, um die Anfrage mit der Antwort zusammenzuführen.

Zum jetzigen Zeitpunkt weiß die Clientanwendung, dass sich der Benutzer erfolgreich am ZL authentifiziert hat. Um die eigentlichen Tokens zu erhalten, müssen jetzt noch im Hintergrund über einen HttpClient mit einem POST Request diese Tokens erfragt werden.

2.5 Abfrage der Tokens

Für den Request wird im Header der Parameter "Content-Type" auf den Wert "application/x-www-form-urlencoded" gesetzt.
Bei der POST Anfrage an den token_endpoint werden dabei folgende Parameter mitgegeben:

  • code: Entspricht dem erhaltenen „code" Parameter aus der Antwort
  • grant_type: „authorization_code"
  • redirect_uri: Dieselbe redirect_uri wie aus der ersten Anfrage
  • client_id: Ihre individuelle ClientID wie von der DGK erhalten
  • client_secret: Ihr individuelles ClientSecret wie von der DGK erhalten
  • state: Entspricht dem erhaltenen „state" Parameter aus der Antwort
  • code_verifier: Der code_verifier, den Sie sich vor der ersten Anfrage gemerkt hatten.

Die Antwort enthält u.a. die beiden Werte „id_token" und „access_token".
Das access_token wird benötigt, wenn die API abgefragt werden soll. Es wird als sogenanntes Bearer-Token im HTTP-Authorization-Header übergeben. Der Wert dieses Headers ist das Wort „Bearer", gefolgt von einem Leerzeichen und dem access_token.
Neben der Abfrage der API im Benutzerkontext (die API weiß also, welcher Benutzer mit Ihrem Client die Abfrage stellt), kann mittels dieser Authorisierung auch vom ZL der userinfo_endpoint abgefragt werden, so wie er aus der .wellknown Abfrage zurückgegeben wurde.
Das id_token ist ein JWT-Token, dessen genauere Struktur unter [3] nachgelesen werden kann. Relevant ist hier, dass der Payload (= der Bereich zwischen den beiden Punkten) Base64 encodiert unter anderem die folgenden Werte enthält:

  • sub: Die AccountID, mit der der Benutzer eindeutig in Relation zum ZL identifiziert ist.
  • iss: Identifiziert den Herausgeber (Issuer) der AccountID, also unseren ZL. Entspricht dem issuer aus der .wellknown Antwort.
  • aud: Ihre ClientID.
  • nonce: Das ursprüngliche generierte Nonce.

Nur wenn aud, iss und nonce korrekt sind, entspricht die Antwort der Anfrage und die AccountID aus sub kann sicher dem Benutzer zugeordnet werden.

Die Webseite aus [4] kann genutzt werden, um sich als Entwickler anzuschauen, was in dem id_token enthalten ist. Je nach Anfrage können hier auch zusätzliche Informationen, wie z.B. der Name des Benutzers enthalten sein.

Eine einfachere Implementierung bei Verwendung von IdentityServer finden Sie unter [5].

3. Anmerkungen, Beispiele, Weblinks

Diese Links führen zu Informationen Dritter. Folgen Sie diesen Links, so verlassen Sie den Bereich der DGK.

[1]: https://help.akana.com/content/current/cm/api_oauth/oauth_discovery/m_oauth_getOpenIdConnectWellknownConfiguration.htm

[2]: https://medium.com/identity-beyond-borders/what-the-heck-is-pkce-40662e801a76

[3]: https://darutk.medium.com/understanding-id-token-5f83f50fa02e

[4]: https://jwt.io/

[5]: https://identityserver4.readthedocs.io/en/latest/


Dienstleister, die das Login einbinden wollen, erhalten alle notwendigen Informationen.

Links unter 3 führen zu Inhalten Dritter mit eigenen Datenschutzrichtlinien. Die DGK übernimmt für Inhalte Dritter keine Verantwortung und Haftung.

Verwandte Artikel