Für Anwendungen bei der Integration

Allgemeine Fragen zum gematik Authenticator

Frage: Woher bekomme ich den Quellcode des gematik Authenticators?

Antwort: 

Den aktuellen Quellcode des gematik Authenticators finden Sie auf unserem öffentlich zugänglichen Github Repository. [ Klick hier (gematik Authenticator GitHub Repository) ]

Frage: Gibt es eine ausführliche Dokumentation für die Integration des gematik Authenticators in meine Fachanwendung?

Antwort:

Frage: Welche Fehlercodes gibt es im gematik Authenticator?

Antwort:

Alle derzeit genutzten Fehlercodes des gematik Authenticators finden Sie zusammengefasst auf unserer Übersichtsseite. [ Klicke hier ( Übersicht Fehlercodes ) ]

Frage: Gibt es eine Beispielkonfiguration für nginx oder Apache für die OpenID-Authentifizierung mit dem gematik Authenticator und dem IDP der gematik, insbesondere bezüglich der zusätzlichen Verschlüsselung?

Antwort:

Da kein nginx oder Apache genutzt wird, gibt es derzeit auch keine Beispielkonfigurationen.

Fragen zu notwendigen Vorbedingungen

Frage: Was muss ich als Hersteller einer (Fach-)Anwendung tun, um meine Anwendung erfolgreich für die Nutzung des zentralen IDP's zu registrieren?

Antwort:

Wenn Sie ein Anbieter einer (neuen) (Fach-)Anwendung sind und Sie den gematik Authenticator in Ihre Anwendung integrieren möchten, um den Nutzenden eine Anmeldung per gematik Authenticator zu ermöglichen, müssen Sie sich bezüglich der Anbindung initial an folgende Adresse wenden: IDP-Registrierung@gematik.de. Sie werden anschließend weitere Informationen zur Registrierung Ihrer Anwendung erhalten.
Achtung: Wenn Sie ein Nutzender einer Anwendung (wie bspw. dem Organspenderegister sind), ist eine Registrierung nicht notwendig. Bei Problemen wenden Sie sich hier bitte an Ihren DVO oder an authenticator@gematik.de.

Frage: Muss ich im Voraus Zertifikate beantragen oder registrieren?

Antwort:

Eine Registrierung von Zertifikaten ist nicht notwendig. Der zentrale IDP-Dienst ist mit einem TLS-Server-Zertifikat ausgestattet, welches gegen den Truststore des gematik Authenticators geprüft wird. Eine beidseitige Authentisierung mittels TLS-Client-Zertifikat ist nicht vorgesehen. Die Zertifikate aus den Smartcards (HBA/SMC-B) müssen dem zentralen IDP-Dienst vorab nicht bekannt sein und müssen nicht registriert werden.

Frage: Wo kann ich meine Konnektor-Zertifikate hinterlegen?

Antwort:

Die notwendigen Zertifikate müssen im Verzeichnis 

• für Windows: C:\Program Files\gematik Authenticator\resources\certs-konnektor
• für MacOS: /Users/[Ihr Benutzername]/Library/Application Support/gematik Authenticator/resources/certs-konnektor

hinterlegt werden.

Frage: Wo kann ich meine fachanwendungsspezifischen Zertifikate hinterlegen?

Antwort:

Die notwendigen Zertifikate müssen im Verzeichnis 

• für Windows: C:\Program Files\gematik Authenticator\resources\certs-idp
• für MacOS: /Users/[Ihr Benutzername]/Library/Application Support/gematik Authenticator/resources/certs-idp

hinterlegt werden.

Frage: Besteht die Möglichkeit, den gematik Authenticator lokal ohne jegliche Freischaltungen zu testen?

Antwort:

Ja, wir bieten für solche Fälle den gematik Authenticator als sogenannte Mock-Version an. Diese kann ebenfalls über unser GitHub Repository heruntergeladen werden. [ Klicke hier ]

Diese Version ermöglicht ein Testen ohne zusätzliche Freischaltungen und/oder Hardware wie beispielsweise einem Konnektor oder Smartcards. Eine ausführlichere Dokumentation unserer gematik Authenticator Mock-Version steht ebenfalls zur Verfügung. [ Klicke hier ( Dokumentation gematik Authenticator Mock-Version ) ]

Fragen zur Integration

Frage: Woher weiß der Fachdienst, welcher challenge_path im Deeplink genutzt werden muss?  

Antwort:

Der Fachdienst erhält den challenge_path anhand des authorization_endpoint. Dieser ist innerhalb des Discovery Documents des IDPs zu finden. Erkennbar ist dieses an der Endung "/.well-known/openid-configuration".

Beispiel: https://idp.app.ti-dienste.de/.well-known/openid-configuration

Frage: Was muss der Fachdienst verarbeiten können, wenn dieser den authorization_code des gematik Authenticators weitergeleitet bekommt?

Antwort:

1. Der authorization_code muss per Token Request beim token_endpoint des IDP-Dienstes eingereicht werden.
2. Im Token Request wird der authorization_code über den Parameter "code" übergeben.
3. Zusätzlich muss zum "code" noch der Parameter key_verifier übergeben werden.
4. Der key_verifier enthält einen verschüsselten JWT (Json Web Token) mit code_verifier und einem token_key (= AES-Schlüssel) im Body

5. In dem HTTP-Request MUSS der HTTP-Header user-agent gemäß [RFC7231] mit <Produktname>/<Produktversion> <Herstellername>/<client_id> 
   <Produktname> gemäß eigener Definition, Länge 1-20 Zeichen, Zeichenvorrat [0-9a-zA-Z\-\.]
   <Produktversion> gemäß Produktidentifikation
   <Herstellername> gemäß eigener Definition, Länge 1-20 Zeichen, Zeichenvorrat [0-9a-zA-Z\-\.] 
   <client_id> gemäß Registrierung bei der gematik
   mitgesendet werden. Siehe "A_20015-01 - PS" der Spezifikation im [ Klicke hier ( Fachportalseite des gematik Authenticators ) ].

6. Der Token Response enthält den id_token und access_token. Beide sind JWEs, die mit dem token_key (=AES-Schlüssel) entschlüsselt werden können.
7. Der Dienst hat jetzt den entschlüsselten ID/ACCESS Token

Frage: Woher weiß der Fachdienst, wohin der Token-Request gesendet werden muss?

Antwort:

Der Fachdienst erhält diese Information über den sogenannten token_endpoint. Dieser ist innerhalb des Discovery Documents des IDPs zu finden. Erkennbar ist dieses an der Endung "/.well-known/openid-configuration".

Beispiel: https://idp.app.ti-dienste.de/.well-known/openid-configuration

Frage: Wie muss der Fachdienst den key_verifier erstellen?

Antwort:

Gehen Sie dafür wie folgt vor:

1. AES-Schlüssel würfeln und speichern
2. code_verifier aus dem Speicher nehmen
3. Beides als body_claims in einen JWT  (Json Web Token) schreiben
4. JWT (Json Web Token) mit dem ENC-Schlüssel des IDPs verschlüsseln
5. Der resultierende JWE (Json Web Encryption) ist der key_verifier

Frage: Bei welchem Endpunkt tausche ich als WANDA den authorization_code gegen den access_token ein?

Antwort:

Für die Einlösung des authorization_code beim token_endpoint muss der Endpunkt genommen werden, welcher laut WANDA Basic/Smart erreichbar ist:

Frage: Wie lauten die IDP Endpunkte?

Antwort:

Die Endpunkte können Sie der nachfolgenden Tabelle entnehmen.

idp-ref.zentral.idp.splitdns.ti-dienste.de

idp.zentral.idp.splitdns.ti-dienste.de