GitHub-Projekt

Eine Referenzimplementierung des IDP-Dienstes sowie ein IDP-Server-Dockerimage, Testsuiten und Codebeispiel liegen im github-Projekt. Über die rbel-logs gelangt man zu beispielhaften Requests und Responses für Authentifizierungsabläufe mit HBA bzw. eGK.

• README →  https://github.com/gematik/ref-idp-server#readme
• IDP-Server als Docker-Image → https://github.com/gematik/ref-idp-server#idp-server-as-docker-image
• rbel-logs → https://github.com/gematik/ref-idp-server#tokenflow-sites
  • HBA (Primärsysteme) → https://gematik.github.io/ref-idp-server/tokenFlowPs.html - Beschreibt den Kompletten Authentisierungsprozess vom Initialen Request bis zum erhalt der Token bei Verwendung eines Heilberufsausweis 
  • eGK (Versichertensysteme, z.B. E-Rezept-App) →  https://gematik.github.io/ref-idp-server/tokenFlowEgk.html - Beschreibt den Kompletten Authentisierungsprozess vom Initialen Request bis zum erhalt der Token bei Verwendung einer elektronischen Gesundheitskarte

Anforderungen aus gematik-Spezifikationen an den Fachdienst

Die Spezifikationsdokumente, in denen die relevanten Anforderungen formuliert sind, finden sich im Fachportal der gematik. Über die Suchfunktion im Portal gelangt man durch Suche nach dem relevanten Spezifikationsdokument zur aktuellen Version der gesuchten Spezifikation.

Konkret gilt für den Fachdienst Kapitel 5.1 "Registrierung des Fachdienstes beim IDP-Dienst" aus gemSpec_IDP_FD (Spezifikation Identity Provider – Nutzungsspezifikation für Fachdienste) wobei beim Zugriff auf den IDP-Dienst in seiner Rolle als Identity Provider anstelle der ACCESS-TOKEN die ID-TOKEN verwendet werden.

Dies deckt die folgenden Anforderungen ab

Im präferierten Fall in dem der Authorization Server selbst den Request an den IDP-Dienst parametrisiert und auch mit dem Authorization Code das ID_Token abruft gelten für den Fachdienst selbst zusätzlich folgende Anforderungen aus gemSpec_IDP_Frontend Kapitel 8 "Funktionsmerkmale Anwendungsfrontend des IDP Dienstes". In dieser Situation ist es nicht notwendig am IDP-Dienst zusätzlich zum Fachdienst auch noch ein dediziertes Anwendungsfrontend zu Registrieren.

Anforderungen aus gematik-Spezifikationen an ein integriertes Authenticator-Modul

Wenn nicht der gematik Authenticator für die Authentisierung verwendet wird sondern, analog zum E-Rezept, das Authenticator-Modul in ein Primärsystem oder eine andere Anwendung integriert wird so kommen dort auch die Vorgaben aus dem Kapitel 5.1.4 "Authentifizierung der LEI" des gemILF_PS_eRp zur Anwendung.

Im präferierten Fall, in dem der Authorization Server selbst den Request an den IDP-Dienst parametrisiert und nach der Authentisierung auch mit dem Authorization Code das ID_Token abruft, entfällt jedoch eine Reihe von Anforderungen, weil diese durch den Authorization Server des Fachdienst übernommen werden.

Adressen des IDP-Dienstes

Abholen des Discovery Dokument

Das Discovery Document der IDP-Dienst-Referenzimplementierung kann z. B. über den Browser durch Aufruf der Schnittstelle https://idp-ref.app.ti-dienste.de/.well-known/openid-configuration erfolgen. Das signierte JWT sieht in etwa so aus

eyJhbGciOiJCUDI1NlIxIiwia2lkIjoicHVrX2Rpc.....VR4R1lnQ1ZJNFFnPT0iXSwidHlwIjoiSldUIn0.
eyJpYXQiOjE2NzUzMzc0OTEsImV4cCI6MTY3NTQyM.....VzX3N1cHBvcnRlZCI6WyJwYWlyd2lzZSJdfQ.
T5r4MkQRhxqmMfcrDXaKoPGZqhWWQQ9R-tPHbQI6mf9JIlWnWVCen689U0JT5-jxoXYbLmzQEtWxIAcRKS7U8A

Nach der Decodierung bekommt man in der payload das Discovery-Dokument des IDP-Dienstes

{
  "iat": 1675337491,
  "exp": 1675423891,
  "issuer": "https://idp-ref.app.ti-dienste.de",
  "jwks_uri": "https://idp-ref.app.ti-dienste.de/certs",
  "uri_disc": "https://idp-ref.app.ti-dienste.de/.well-known/openid-configuration",
  "authorization_endpoint": "https://idp-ref.app.ti-dienste.de/auth",
  "sso_endpoint": "https://idp-ref.app.ti-dienste.de/auth/sso_response",
  "token_endpoint": "https://idp-ref.app.ti-dienste.de/token",
  "auth_pair_endpoint": "https://idp-ref.app.ti-dienste.de/auth/alternative",
  "uri_pair": "https://idp-pairing-ref.zentral.idp.splitdns.ti-dienste.de/pairings",
  "kk_app_list_uri": "https://idp-ref.app.ti-dienste.de/directory/kk_apps",
  "third_party_authorization_endpoint": "https://idp-ref.app.ti-dienste.de/extauth",
  "uri_puk_idp_enc": "https://idp-ref.app.ti-dienste.de/certs/puk_idp_enc",
  "uri_puk_idp_sig": "https://idp-ref.app.ti-dienste.de/certs/puk_idp_sig",
  "code_challenge_methods_supported": ["S256"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "id_token_signing_alg_values_supported": ["BP256R1"],
  "acr_values_supported": ["gematik-ehealth-loa-high"],
  "response_modes_supported": ["query"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["openid",   ....,   ....],
  "subject_types_supported": ["pairwise"]
}

Öffentliche Schlüssel und Zertifikate

Discovery Document, Access- und ID-Token sind signiert und teilweise für den Transport verschlüsselt. Für die Prüfung der Signaturen, und für die Schlüsselaushandlung zur Verschlüsselung benötigt eine Fachanwendung entsprechende öffentliche Schlüssel und Zertifikate. Diese können unter der URL, welche im Discovery Document unter dem Parameter "jwks_uri" angegeben ist, abgerufen werden.

So liefert der Aufruf von https://idp-ref.app.ti-dienste.de/certs drei Einträge

1. puk_idp_sig - öffentlicher Schlüssel und Zertifikat zur Validierung der vom IDP-Dienst ausgestellten Signaturen
2. puk_idp_enc - öffentlicher Schlüssel zum Verschlüsseln von für den IDP-Dienst bestimmten Daten
3. puk_idp_sig_sek -  öffentlicher Schlüssel des IDP-Dienst zur Authentisierung gegenüber sektoralen Identity Providern.

{"keys":[
{"kid":"puk_idp_sig",
 "use":"sig",
 "kty":"EC",
 "crv":"BP-256",
 "x":"pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
 "y":"qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
 "x5c":["MIIC+jCCAqCgAwIBAgICG3wwCgYIKoZIzj0E.......d0zgqqbskiLAbmwbxMOjrtClRS6xK2J61BATOj20w=="]},
{"kid":"puk_idp_enc",
 "use":"enc",
 "kty":"EC",
 "crv":"BP-256",
 "x":"pkU8LlTZsoGTloO7yjIkV626aGtwpelJ2Wrx7fZtOTo",
 "y":"VliGWQLNtyGuQFs9nXbWdE9O9PFtxb42miy4yaCkCi8"},
{"kid":"puk_idp_sig_sek",
 "use":"sig",
 "kty":"EC",
 "alg":"ES256",
 "crv":"P-256",
 "x":"sk8Cig9IjJqATxrJkWRdw2gJ7Qut7ygToC8o3z2C_IU",
 "y":"LGXTzotnGJuMThRp0QWa2HldCfNoxbMh-PownRgAKko"}]}

Prüfung IDP-Dienst Zertifikate

OCSP-Prüfung

Im Discovery-Dokument des IDP-Dienstes ist im claim  "uri_puk_idp_sig" ein JWK Objekt hinterlegt. Der Parameter "x5c" enthält das verwendete Signer-Zertifikat als Base64 ASN.1 DER-Encoding. Hier kommt ausnahmsweise NICHT URL-safes Base64-Encoding zum Einsatz!].

So liefert der Aufruf von https://idp-ref.app.ti-dienste.de/certs/puk_idp_sig für die IDP-Dienst-Referenzumgebung:

{"kid":"puk_idp_sig",
"use":"sig",
"kty":"EC",
"crv":"BP-256",
"x":"pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
"y":"qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
"x5c":["MIIC+jCCAqCgAwIBAgICG3wwCgYIKoZIzj0 ... lRS6xK2J61BATOj20w=="]}

Das Zertifikat sollte stündlich über OCSP geprüft werden. Es stehen sowohl im Internet wie auch aus der TI erreichbare OCSP-Responder der Komponenten-PKI zur Verfügung.

Prüfung Zertifikatsinhalte

Im Discovery-Dokument des IDP-Dienstes ist im claim  "id_token_signing_alg_values_supported" festgelegt, welche Algorithmen vom IDP-Dienst unterstützt werden. Für den IDP-Dienst in der Referenzumgebung wird z. B. nur der Algorithmus BP256R1 für die Signatur der ID-Token unterstützt. ("id_token_signing_alg_values_supported": ["BP256R1 "]). Das Signaturzertifikat für die Signatur der ID-Token ist von der Komponenten PKI der gematik ausgestellt.

Zur Prüfung der Zertifikate muss "admission" und "certificatePolicies" im Zertifikat analysiert werden, um Zertifikatstyp und technische Rolle zu ermitteln. Die Auflösung des ObjectIdentifier erfolgt anhand der Spezifikation Festlegung von OIDs.

Authorization Request

Der Endpunkt für Authorization-Request gegen den IDP-Dienst ist die URL welche im Discovery Document unter dem Parameter "authorization_endpoint" angegeben ist. Die Transportverschlüsselung (TLS) ist mit normalen Serverzertifikaten für diese URL abgesichert.

Token

Token-Request

Der Endpunkt für den Token-Request gegen den IDP-Dienst ist die URL, welche im Discovery Document unter dem Parameter "token_endpoint" angegeben ist (z. B. : https://idp-ref.app.ti-dienste.de/token). Die Transportverschlüsselung (TLS) ist mit normalem Serverzertifikaten für diese URL abgesichert.

Token-Response

Folgende claims sind immer oder Kontext abhängig Bestandteil des Token:

Prüfung der erhaltenen ID-Token

Fachdienste nutzen am besten nur die ID-Token des IDP-Dienstes. Access-Token werden für das E-Rezept verwendet, hier ist der IDP-Dienst der Authorization-Server.

• Entschlüsselung der Token mit dem vorgesehenen token_Key

Der Fachdienst erzeugt einen symmetrischen Schlüssel, den er im Token-Request im Parameter key_verifier als token_key an den IDP-Dienst übermittelt. Das abgerufene ID-Token muss mit diesem Schlüssel verschlüsselt sein. Der Fachdienst muss bei Erhalt des ID-Token vom IDP-Dienst den ID-Token mit dem token_key entschlüsseln können.

• Prüfung der zeitlichen Gültigkeit des Token

Zur Prüfung der Gültigkeit des ID-Token müssen die claims iat und exp aus dem ID-Token ausgewertet werden. Dabei ist iat der Ausstellungszeitpunkt und exp der Ablaufzeitpunkt des ID-Token. Beide claims haben das Format [Sekunden seit 1970, RFC 7519 Sect.2] . Der Zeitraum der Verwendung des Tokens muss zwischen den Werten der Attribute iat und exp liegen.

• Prüfung der Signatur des Token
  Um die Signatur der Token zu prüfen muss diese mathematisch mittels des "puk_idp_sig" aus dem jwks-Schlüsselsatz des IDP_Dienstes verifziert werden können. Das dort im x5c-Claim enthaltene Zertifikat ist nach Möglichkeit mindestens Täglich mittels OCSP auf seine Gültigkeit zu prüfen.
  
  
• Prüfung des audience-Parameters

Der im Token mitgelieferte claim aud muss mit der beim IDP-Dienst registrierten client_id übereinstimmen.

• Prüfung des nonce-Parameters

Optional kann der Fachdienst zur Absicherung gegen Attacken ein nonce generieren und diese im Authorization-Request an den IDP-Dienst mit übermitteln. In diesem Fall muss der ID-Token den claim nonce enthalten. Der Wert von nonce muss exakt dem vom Fachdienst übermittelten Wert entsprechen. Gibt der Fachdienst im Authorization-Request an den IDP-Dienst keinen Parameter nonce mit, so darf das vom IDP-Dienst ausgestellte ID-Token den claim nonce nicht enthalten.