Terminologie

Erläuterungen zur verwendeten Terminologie analog sind zentral für alle Flows hier abgelegt.

Vorbedingungen

• Registrierung des App-Link/Universal-Link für das Frontend auf dem Gerät des Nutzers (auf redirect Adresse des Fachdienst) - oder einreichen über Web.
• Registrierung des App-Link/Universal-Link für das Authenticator-Modul des IDP auf dem Gerät des Nutzers (auf Adresse des IDP) - oder anfragen über Web.
• Aktueller Signaturschlüssel des Federation Master ist bekannt und vertrauenswürdig bei IDP und Fachdienst eingebracht worden.

Flow - OIDC

Flow Diagramm

Textuelle Beschreibung der Aktivitäten je Transaktion sowie in den Übergängen

Schnittstellenbeschreibung

(0) Vorbedingung - Abruf der Schlüssel des Federation Master

Dazu wird das selbst signierte Entity Statement des Federation Master abgerufen und gegen den vorher bekanntgemachten Signaturschlüssel des Federation Master geprüft.

Response auf GET an die Adresse "http://master0815.de/.well-known/openid-federation"

HTTP 200 mit Content-Type: application/entity-statement+jwt

Folgende Werte müssen im Header des selbst signierten Entity Statement des Federation Master auftauchen:

Folgende Werte müssen im Body des selbst signierten Entity Statement des Federation Master enthalten sein:

IDP Liste

Wir folgen der Idee des „IdP Choosers“ - Hier wird vom Nutzer eines Telematik Services erwartet, dass dieser die Institution kennt, welche seine Identität herausgibt. Bei einem Versicherten wäre dies z.B. seine Krankenkasse (bei einem Arzt die zuständige Ärztekammer, usw.).

Jede Kasse wird als eigener IDP mit eigenen Endpunkten und Entity Statements geführt. Ein Dienstleister kann dahinter aber denselben Dienst stehen haben und die Kassen als Mandanten pflegen. Damit bleibt es auch möglich für die Kasse bei fehlender Installation auf einer eigenen Infoseite zu ihren Apps zu verweisen. Kassen geben die Freigabe für ihren Eintrag in der Föderation frei.

Die Liste der Kassen wird aus der Föderation generiert und am Federation Master zum Abruf bereitgestellt. Die Integrität der Liste wird mittels Signatur über einen Schlüssel aus dessen Keyset sichergestellt.

(0 a) Das Anwendungsfrontend fragt die Liste aller IDPs ab, oder der Autorisierungsserver lässt diese Liste selbst im Frontend anzeigen (Webview)

Die Kommunikation zwischen Anwendungsfrontend und Fachdienst ist anwendungsspezifisch und wird hier nicht weiter spezifiziert.

(0 b) Der Autorisierungsserver antwortet dem Anwendungsfrontend mit der Liste aller IDPs

Der Authorization-Server antwortet dem Anwendungsfrontend mit der Liste aller IDPs oder der Authorization-Server lässt diese Liste selbst im Frontend anzeigen. 

Diese Liste wird als JWS formatiert und mittels eines Schlüssels des Federation Master signiert. 

Das Frontend lässt den Nutzer die Wahl seines IDP (seiner Kasse) treffen oder diese Auswahl erfolgt über eine Webseite des Fachdienstes.

Die notwendigen Informationen können aus den Entity Statements gelesen werden. Das signierte JWS der IDP-Liste hat folgende Inhalte

"IDP 4711"

URI

Folgende Werte müssen im Header der vom Federation Master signierten IDP-Liste auftauchen:

(1)  Authorization Request von Anwendungsfrontend zum Authentication Endpunkt (Auth EP) des Autorisierungsserver des Fachdienstes

Das Anwendungsfrontend sendet ein HTTP-GET an den AS des Fachdienstes.

Die folgenden GET-Parameter werden im query string verwendet:

"eRezeptApp"

VSCHAR 

code

(1 a) Falls der Autorisierungsserver des Fachdienstes das Entity Statement  des IDP noch nicht kennt, lädt er dies herunter

Request:

HTTP-GET 

Adresse: "https://idp4711.de/.well-known/openid-federation"

(1 b) Der IDP sendet sein Entity Statement zurück

Der Autorisierungsserver verifiziert die Signatur des Entity Statement gegen einen Schlüssel aus dem Entity Statement des Federation Master über diesen issuer Validation trust chain.

Response:

HTTP 200 mit Content-Type: application/entity-statement+jwt

Folgende Werte müssen im Header des selbst signierten Entity Statement des sektoralen IDP auftauchen:

Folgende Werte müssen im Body selbst signierten Entity Statement des sektoralen IDP-Dienstes enthalten sein:

1645484401

1645570800

 {
    "ar": ["none"],
    "par": ["self_signed_tls_client_auth"]
}

signed_jwks

Ablageort für weitere Schlüssel des IDP etwa die zur Signatur seiner Token . Wenn eine signed_jwks_uri im Entity Statement angegeben ist müssen auch diese Schlüssel importiert werden

Folgende Werte müssen im Header des selbst signierten KeySet des sektoralen IDP auftauchen:

Folgende Werte müssen im Body enthalten sein:

(1 c) Der Autorisierungsserver des Fachdienstes ruft das Entity Statement zum IDP beim Federation Master ab

Request:

HTTP-GET 

Adresse: "http://master0815.de/federation_fetch_endpoint"

HTTPS GET Request an den federation_fetch_endpoint aus dem Entity Statement des Federation Master mit dem folgenden Parameter:

(1 d) Der Federation Master sendet sein Entity Statement über den angefragten sektoralen IDP zurück

Response:

HTTP 200 mit Content-Type: application/entity-statement+jwt

Folgende Werte müssen im Header des Entity Statement des Federation Master über den sektoralen IDP enthalten sein:

Folgende Werte müssen im Body des Entity Statement des Federation Master über den sektoralen IDP enthalten sein:

Als Ergebnis des Schritts (1-d) kennt der Authorization-Server des Fachdienstes die öffentlichen Schlüssel des IDP für Verschlüsselung und Signatur..

(2) Der Autorisierungsserver des Fachdienstes sendet ein (Pushed) Authorization Request an den Authentication Endpunkt (Auth EP) des sektoralen IDP

Der innere Flows startet mit dem Pushed Authorization-Request (RFC9126) des Fachdienst an den sektoralen IDP.  Als client_assertion wird self_signed_tls_client_auth verwendet (siehe OIDC Standard OpenID Connect Core 1.0 (section-9)).

Anmerkung: Dies passiert als Folge des Authorization-Request des Anwendungsfrontends.

HTTP-POST

Der Authorization Request des Fachdienst zum sektoralen IDP enthält die folgenden Parameter:

VSCHAR 

code

Ein sektoraler Identity Provider welcher den Identitäten für Versicherte verwaltet MUSS mindestens die folgenden Scopes und Claims unterstützen:

Die angefragten "scopes" werden so mit Werten belegt, wie sie zum Abfragezeitpunkt beim sektoralen IDP (bzw. dessen Quellsystem) vorliegen. Die über den "scope" urn:telematik:email angefragte Adresse ist vor der Verwendung durch den Fachdienst zu verifizieren. Eine Verifikation durch den IDP ist nicht vorgesehen, da diese ohnehin nur eine begrenzte zeitliche Gültigkeit haben kann.

(2 a) Falls der IDP das Entity Statement des Autorisierungsserver des Fachdienst noch nicht kennt, lädt er dies herunter.

Request:

HTTP-GET 

Adresse: "https://Fachdienst007.de/.well-known/openid-federation"

(2 b) Der Autorisierungsserver des Fachdienst sendet sein Entity Statement zurück und der IDP registriert ihn als Client (Automatic Registration)

Der IDP verifiziert die Signatur des Entity Statement über einen Dienst gegen einen Schlüssel aus dem Entity Statement des Federation Master gemäß den Standards:

• OpenID Connect Federation 1.0 (section-10.1) 
• OpenID Connect Federation 1.0 (section-8.2)

Response:

HTTP 200 mit Content-Type: application/entity-statement+jwt

Folgende Claims müssen im Header des selbst signierten Entity Statement des Fachdienstes auftauchen:

Folgende Body-Claims müssen im selbst signierten Entity Statement des Fachdienstes enthalten sein:

1645484401

1645570800

signed_jwks

Ablageort für weitere Schlüssel des Fachdienstes etwa die zur TLS Client Schlüssel und Zertifikate (x5c, use = sig) oder für die Verschlüsselung der ID_Token (use = "enc").

Wenn eine signed_jwks_uri im Entity Statement angegeben ist müssen auch diese Schlüssel importiert werden.

Folgende Werte müssen im Header des selbst signierten KeySet des Fachdienstes auftauchen:

Folgende Werte müssen im Body enthalten sein:

(2 c) Abruf des Entity Statement zum Fachdienst beim Federation Master

Request:

HTTP-GET 

Adresse: "http://master0815.de/federation_fetch_endpoint"

HTTPS GET Request an den federation_fetch_endpoint aus dem Entity Statement des Federation Master mit dem folgenden Parameter:

(2 d) Der Federation Master sendet sein Entity Statement über den Fachdienst zurück

Response:

HTTP 200 mit Content-Type: application/entity-statement+jwt

Folgende Werte müssen im Header zum Entity Statement des Federation Master über den Fachdienst enthalten sein:

Folgende Werte müssen im Body des Entity Statement des Federation Master über den Fachdienst enthalten sein:

Als Ergebnis des Schritts (2-d) kennt der IDP die öffentlichen Schlüssel des Fachdienstes für Verschlüsselung und Signatur.

(3) Der PAR-Endpunkt (PAR EP) des sektoralen IDP antwortet dem AS des Fachdienst mit einer Request URI

Zuvor verifiziert der IDP das TLS CLientzertifikat gegen einen Schlüssel aus dem Entity Statement des Fachdienstes.
Response:

HTTP 201 mit Content-Type: application/json

Diese URI wird als redirect an das Anwendungsfrontend gesendet um über das Authenticator Modul den IDP zu erreichen

(4) Der Authorization Server des Fachdienst antwortet dem Frontend mit einem redirect und seiner Request URI

HTTP-302,

Mit mindestens den folgenden HTTP-Header Elementen:

• Location

Die Location setzt sich zusammen aus:

<target_url><authorization request des Authorization Server zum sektoralem IDP>

Die target_url entspricht dabei der Adresse des Authorization-Endpunkt des sektoralen IDP entsprechend dem Entity Statement welche auf dem Gerät auf das Authenticator Modul weitergeleitet wird.

Der Request des Fachdienst AS zum sektoralen IDP enthält dabei die folgenden Parameter:

URL

(5) Das Anwendungsfrontend sendet den Authentication Request an die URI des IDP und leitet ihn somit an das Authenticator Modul weiter

Das Anwendungsfrontend sendet ein HTTP-GET an den Authorization-Endpunkt des sektoralen IDP.

Die GET-Parameter entsprechen dem Request des Fachdienstes aus Schritt 4:

Das Authenticator Modul des sektoralen IDP fängt diesen Request dadurch das er diese Adresse für App2App Kommunikation im Betriebssystem registriert hat.

(6) Das Authenticator Modul leitet den Authentication Request an den IDP weiter. (proprietär)

Die Schritte zur Nutzer-Authentifizierung und zur Erstellung des AUTHORIZATION_CODE durch den IDP sind anwendungsspezifisch und werden hier nicht weiter spezifiziert.

(7) Der Authorization-Endpunkt des sektoralen IDP antwortet dem Authenticator Modul mit einem Redirect zum Fachdienst. (proprietär)

Beispielsweise

HTTP-302,

Mit mindestens den folgenden HTTP-Header Elementen:

• Location

Die Location setzt sich zusammen aus:

<uri_Fachdienst_AS>?code=<AUTHORIZATION_CODE_IDP>&state=<state_Fachdienst>

VSCHAR

(8) Das Authenticator Modul des IDP ruft über einen App-Link bzw. Universal-Link entsprechend der Redirect-URL das Anwendungsfrontend auf und übergibt den "AUTHORIZATION_CODE"

Der App-Link bzw. Universal-Link Aufruf des Authenticator Modul ist  anwendungsspezifisch und wird hier nicht weiter spezifiziert.

Das  Anwendungsfrontend fängt diesen Request dadurch das er diese Adresse für App2App Kommunikation im Betriebssystem registriert hat.

(9) Das Anwendungsfrontend leitet den "AUTHORIZATION_CODE" an den Autorisierungsserver des Fachdienstes

HTTP-POST (Content-Type: application/x-www-form-urlencoded) nach uri_Fachdienst_AS

Der Request des enthält dabei die folgenden Parameter:

VSCHAR

(10) Der Autorisierungsserver reicht den "AUTHORIZATION_CODE" und  den "Code_Verifier"  beim Token-Endpunkt des IDP ein.

HTTP POST mit Content-Type: application/x-www-form-urlencoded

Die folgenden Parameter werden im payload verwendet: 

(11) Der Autorisierungsserver erhält vom Token-Endpunkt des IDP einen ID_TOKEN und ACCESS_TOKEN mit den gewünschten Claims, der mit dem öffentlichen Schlüssel aus der Registrierung verschlüsselt ist.

Der Autorisierungsserver des Fachdienstes entschlüsselt den ID_TOKEN und verifiziert anschließend dessen Signatur. Damit endet der innere Flow.

HTTP-200

• Content-Type=application/json
• Cache-Control=no-store
• Pragma=no-cache

Die JSON-Struktur sieht so aus:

{

"access_token": <ACCESS_TOKEN>, 

"id_token": <ID_TOKEN>,

"token_type": "Bearer",

"expires_in": 300, (Gültigkeit des ACCESS_TOKEN in Sekunden, RFC6749 section 4.2.2)

}

Der ACCESS_TOKEN wird ignoriert. Hier stellen wir keine Anforderungen.

Der Encryption Header-Claims des ID_TOKEN sieht dabei wie folgt aus:

Signature Header-Claims des ID_TOKEN sind genau die folgenden:

Die Body-Claims für den ID_TOKEN des sektoralen IDP sind beispielsweise die folgenden:

(12) Der Autorisierungsserver des Fachdienst erstellt ein AUTHORIZATION_CODE und sendet diesen an das Anwendungsfrontend zum Einreichen beim Token Endpunkt. 

Beispielsweise

HTTP-302,

Mit mindestens den folgenden HTTP-Header Elementen:

• Location

Die Location setzt sich zusammen aus:

<https://Fachdienst007.de/Token>?code=<authorization code AS>&state=<state Frontend>

VSCHAR

(13) Anwendungsfrontend übergibt dem Autorisierungsserver den AUTHORIZATION_CODE sowie den Code_Verifier

HTTP POST mit Content-Type: application/x-www-form-urlencoded

Die folgenden Parameter werden im payload verwendet:

(14) Anwendungsfrontend erhält ACCESS_TOKEN und REFRESH_TOKEN mit den notwendigen Daten vom Autorisierungsserver des Fachdienst 

HTTP-200

• Content-Type=application/json
• Cache-Control=no-store
• Pragma=no-cache

Die JSON-Struktur sieht so aus:

{

"access_token": <ACCESS_TOKEN>, 

"refresh_token": <REFRESH_TOKEN>,

"token_type": "Bearer",

"scope": "e-rezept", 

"expires_in": 300, (Gültigkeit des ACCESS_TOKEN in Sekunden, RFC6749 section 4.2.2)

}

(15) Das Anwendungsfrontend greift auf die Fachdienst API zu und übergibt dabei das ACCESS_TOKEN

Die Kommunikation zwischen Anwendungsfrontend und Fachdienst ist anwendungsspezifisch und wird hier nicht weiter spezifiziert.