Für Nutzer oder Administratoren

#FrageAntwort
1Was muss bei einer Installation beachtet werden?

Bitte führen Sie die Installation unter Administratorrechte aus, denn nur so kann eine erfolgreiche Installation garantiert werden.
Starten Sie den Authenticator initial ebenfalls mit Administratorrechten, sodass die Software zu Beginn erfolgreich Firewallregeln setzen kann.

2Es öffnet sich plötzlich ein anderer Browser als der von mir verwendete Browser.

Stellen Sie sicher, dass der von Ihnen verwendete Browser dem im System hinterlegten default-Browser entspricht. Hintergrund ist, dass der Authenticator mit dem im System hinterlegten default-Browser für die sichere Anmeldung verwendet.

3Was kann ich tun, wenn der Aufruf der Sharepoint-Download-URL des Authenticators sich nicht ordnungsgemäß öffnen lässt?Versuchen Sie, die URL über den Inkognitomodus des Browsers zu öffnen. Wenn Sie selbst ein firmeninternes Sharepoint nutzen, kann der Aufruf des gematik Sharepoint-Links gestört sein.
4Welche Karten unterstützt der Authenticator und wie wird entschieden, welche genutzt werden soll?

Der Authenticator unterstützt grundsätzlich die Authentifizierung mit HBA- sowie SMC-B-Karten.

Allerdings entscheidet nicht der Authenticator, welche Karte gesteckt werden soll, sondern die genutzte Fachanwendung selbst.
Die Fachanwendung gibt grundsätzlich immer vor, welche Karte für den Authentifizierungsprozess mittels Authenticator gesteckt werden soll.

Bei Fragen hierzu wenden Sie sich bitte an den Support der Fachanwendung.

5

Der Funktionstest zeigt, dass er keine Verbindung zum Konnektor herstellen kann:


  1. Stellen Sie bitte sicher, dass Sie die korrekte IP- und Port-Adresse konfiguriert haben
    1. Der Port ist standardmäßig 443 (HTTPS)
  2. Prüfen Sie unter "TLS-Authentisierung" folgendes:
    1. Bei Auswahl von "Zertifikat": Umwandlung einer p12-Datei in PEM-Format
      1. Sind die PEM-Dateien im korrekten Format?
    2. Bei Auswahl von "Benutzername/Passwort": Prüfen Sie bitte, ob die eingegebenen Daten korrekt sind.

6

Welche Dienste muss der Authenticator erreichen?

Der Authenticator kommuniziert mit dem IDP-Dienst je nach Anwendung über die TI und über das Internet:

IDP-Dienst TI-Endpunkt: https://idp.zentral.idp.splitdns.ti-dienste.de/

IDP-Dienst Internet-Endpunkt: https://idp.app.ti-dienste.de/

Die Entscheidung, welcher Endpunkt genutzt wird, obliegt der Fachanwendung und nicht dem Authenticator!

Für eine manuelle Erreichbarkeitsprüfung kann das Discovery-Document heruntergeladen werden: https://idp.app.ti-dienste.de/.well-known/openid-configuration

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

7

Der Funktionstest zeigt den IDP-Fehler "Fehler: self signed certificate in certificate chain"

Es könnte ein HTTPS-Proxy/Firewall auf der Verbindungsstrecke zum IDP vorhanden sein.

Damit der Authenticator Ihrem HTTPS-Proxy vertrauen kann, so wie es Ihr Browser macht, muss das Public-Server-Zertifikat des IDPs in dieses Verzeichnis abgelegt werden: C:\Program Files\gematik Authenticator\resources\certs-idp

Stichwort: SELF_SIGNED_CERT_IN_CHAIN

Wir empfehlen auch immer die neueste Version des Authenticators installiert zu haben, sodass alle aktuellsten Zertifikate genutzt werden.

8

Der Funktionstest zeigt den IDP-Fehler "Bad response: 407 mit der URL ...""

Der Fehlerstatus-Code gibt an, dass der Request nicht erfolgreich abgesetzt werden konnte.

Grund hierfür könnte sein, dass gültige Authentifizierungsdaten für eine Proxy-Authentifizierung zwischen Browser und Server fehlen.

Bitte vergewissern Sie sich, dass Sie entsprechende Proxy-Autorisierungsdaten oder eine entsprechende Firewallfreischaltung zur Kommunikation mit entsprechendem Endpunkt hinterlegen.


Mit folgendem Curl können Sie überprüfen, ob Sie die jeweiligen Endpunkte erreichen:

IDP Internet-Endpunkt:

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

 IDP PU TI Endpunkt:

curl -v https://idp.zentral.idp.splitdns.ti-dienste.de/.well-known/openid-configuration

9

Welche Anwendungen können bereits mit dem Authenticator genutzt werden?

das ZVR (zentrale Vorsorge-Register): https://zvr-ae.bnotk.de/

10

Was muss getan werden, wenn ich auf eine Fachanwendung nicht zugreifen kann?
Bspw. ZVR: https://zvr-ae.bnotk.de/

Der gematik Authenticator wird im Zusammenspiel mit weiteren Anwendungen der TI (WANDA) eingesetzt, die für die Nutzerinteraktion einen Web-Browser verwenden (eine sogenannte Web-Anwendung). Je nach Anwendung und Konnektor-Konfiguration kann es hierbei erforderlich sein, ein IP Routing für diese Anwendung zu konfigurieren, damit die Anwendung über die TI erreichbar ist. Die Einrichtung des IP-Routings kann hierbei am Arbeitsplatz selbst oder zentral am Gateway konfiguriert werden.

Achten Sie daher darauf, dass ein entsprechendes IP-Routing zu der jeweiligen Fachanwendung eingerichtet wurde.

Dies können Sie mittels folgendem Befehl in der Windows-Kommandozeile (Kommandozeile CMD mit Admin-Rechten) ausführen:
route add <Netzwerk> MASK <Mask> <IP-Konnektor > –p

Nach Einrichtung des Routings können sie mit folgenden Befehlen innerhalb der Kommandozeile testen, ob die Fachwendung erreicht werden kann:

  • traceroute <Netzwerk>
  • ping <DNS Fachanwendung>
    • Bsp. ZVR: ping zvr-ae.bnotk.de

Weitere Informationen hierzu finden Sie innerhalb unseres Installationshandbuchs unter dem Punkt "Zugriff auf Fachanwendung ermöglichen".


Des Weiteren sollte auch geprüft werden, dass die Firewall die Kommunikation mit der Fachanwendung nicht blockiert. Schauen Sie daher bitte auch die eingestellten Firewallfreischaltungen an.

11

Welche Firewall-Freischaltungen sind für die Nutzung des Authenticators notwendig?

DescriptionSourceDestinationPortProtokoll
Verbindung zum IDP via InternetLokaler Client/Workstation (localhost)idp.app.ti-dienste.de443https
Verbindung zum IDP via TI EndpunktLokaler Client/Workstation (localhost)idp.zentral.idp.splitdns.ti-dienste.de443https

Verbindung zu WANDA Applikationen

Bsp.: Zentrales Vorsorgerister

Lokaler Client/Workstation (localhost)

Bsp.: Lokaler Client/Workstation (localhost)

100.102.0.0 / 15

Bsp.: https://zvr-ae.bnotk.de/

443

Bsp.: 443

https

Bsp.: https

Auto-UpdatefunktionLokaler Client/Workstation (localhost)https://github.com/gematik/app-Authenticator443https
KonnektorLokaler Client/Workstation (localhost)internes Netzwerk443https
KartenterminalLokaler Client/Workstation (localhost)internes Netzwerk443https

12

Wie sieht die aktuelle Ablaufkette für die Authentisierung mittels Authenticator aus?

  1. Über einen Anmeldeprozess innerhalb der Web-Anwendung wird der Authenticator gestartet, um für den Nutzer den Anmeldeprozess durchzuführen.
  2. Die Anfrage in der Fachanwendung löst den Authentifizierungsprozess aus.
  3. Je nachdem, ob die Anmeldung über HBA oder SMC-B erfolgt, wird via Konnektor ein entsprechendes Zertifikat abgefragt.
  4. Prüfung, ob die entsprechende Karte gesteckt ist. Falls nicht, wird aufgefordert, die Karte zu stecken.
  5. Der Nutzer muss eine PIN eingeben, die ihm eindeutig zugeordnet ist.
  6. Daraufhin erfolgt eine Überprüfung durch einen externen Identitätsdienst.
  7. Ist die Überprüfung erfolgreich, kehrt der Nutzer in die Fachanwendung zurück und kann darin arbeiten.

13

Was muss getan werden, wenn der Zugriff auf das Anfrageportal der gematik nicht funktioniert?

Es kann vorkommen, dass die Useranlage zur Nutzung des Anfrageportals des Authenticators für den jeweiligen Ticketmelder nicht direkt reibungslos funktioniert.
In diesem Fall sollte folgender Workaround durchgeführt werden, sodass das Kundenkonto erfolgreich eingerichtet wird:

14

Anmeldung mittels Smartcard nicht erfolgreich

Was muss getan werden, wenn zwar alle Funktionstests grün sind, der Login im Browser jedoch mit folgender Fehlermeldung fehlschlägt?

Das AUT Zertifikat ist ungültig

Überprüfen Sie, ob die eingesetzte Karte (eHBA/SMC-B) vollständig aktiviert wurde.

Zur Nutzung einer Karte bedarf es einer vollständigen Aktivierung. Diese besteht zum einen in der Änderung des Transport-Pins sowie einer Aktivierung in Richtung OCSP. In der jeweiligen Dokumentation bei Aushändigung wird das explizit erwähnt.

Der Fehler deutet auf einen Fehler mit der Kommunikation mit OCSP hin, welcher durch vollständige Aktivierung der Karte behoben wird.

15

Wenn ich den Funktionstest ausführe, erhalte ich die Meldung

"Fehler: Hostname/IP does not match certificate´s altnames: IP: XXX.XX.X.XX is not in the cert´s list:"


Hier ist das Problem, dass der FQDN nicht im Serverzertifikat enthalten ist. In einer TLS-Verbindung wird der FQDN (Fully Qualified Domain Name) der URL gegen den SubjectDN (Distinguished Name) des Serverzertifikats geprüft. Während des TLS-Handshakes prüft der Client, ob der FQDN mit dem Common Name im SubjectDN des Serverzertifikats übereinstimmt.


Der Fehler kann daher auftreten, wenn im Authenticator die TLS-Überprüfung auf "aktiviert" gesetzt wird.


Lösung:  Im Authenticator die TLS-Überprüfung auf "deaktiviert" setzen

Für Anwendungen bei der Integration

FrageAntwort
Welche Fehlercodes gibt es?Alle aktuellen Fehlercodes können Sie auf folgender Seite einsehen: Authenticator Fehlercodes
Woher bekomme ich den Quelltext des Authenticators?https://github.com/gematik/app-Authenticator
Gibt es eine Beispielkonfiguration für nginx oder apache für die OpenID-Authentifizierung mit dem Authenticator und dem IDP der Gematik, insbesondere wegen der zusätzlichen Verschlüsselung?Es ist kein nginx oder apache im Einsatz - daher gibt es auch keine entsprechende Beispielkonfiguration.
Besteht die Möglichkeit, den Authenticator auch lokal ohne jegliche Freischaltungen zu testen?Ja - hierzu kann der Authenticator ab Version 2.1.0 genutzt werden. Diese Version beinhaltet einen Mockmodus, der zum Testen genutzt werden kann.
Woher weiß der Fachdienst, welcher challenge_path im deeplink genutzt werden muss?  Der Dienst bekommt das über den "authorization_endpoint " mit. Zu finden innerhalb des Discovery Document des IDPs (/.well-known/openid-configuration)
Was muss der Fachdienst noch machen, wenn er vom Authenticator den Authorization_Code weitergeleitet bekommt?
  1. Der Authorization_Code muss per Token Request beim Token-Endpunkt 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" mitgegeben werden.
  4. Der "key_verifier" enthält einen verschüsselten JWT (also einen JWE) mit dem 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> mit:
    <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 Fachportal.

  6. Der Token Response enthält "id_token" und "access_token". Beide sind JWEs, die mit dem token_key=AES-Schlüssel entschlüsselt werden können.
  7. Abschluss. Der Dienst hat jetzt den entschlüsselten ID/ACCESS Token
Woher weiß der Fachdienst, wohin der Token-Request gesendet werden muss?Der Dienst bekommt das über den "token_endpoint" mit. Zu finden innerhalb des Discovery Document des IDPs (/.well-known/openid-configuration)
Wie muss der Fachdienst den "key_verifier" erstellen?
  1. AES-Schlüssel würfeln und merken
  2. code_verifier aus dem Speicher nehmen
  3. Beides als body_claims in einen JWT schreiben
  4. JWT mit dem ENC-Schlüssel des IDPs verschlüsseln
  5. Der resultierende JWE ist der key_verifier
Was muss ich tun, um mich erfolgreich für die Nutzung des zentralen IDP's zu registrieren?

Sie müssen sich bezüglich der Anbindung an folgende Adresse wenden: IDP-Registrierung@gematik.de und werden dann alle weiteren Informationen von den zuständigen Transitionmanagern erhalten.

Muss ich auch im Voraus Zertifikate beantragen oder registrieren?Eine Registrierung von Zertifikaten ist nicht notwendig. Der zentrale IDP-Dienst ist mit einem TLS-Server-Zertifikat ausgestattet, welches gegen den Truststore des 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.
Bei welchem Endpunkt tausche ich als WANDA den Authorization Code gegen den Access Token ein?

Für das Einlösung des Authorization Code beim Token Endpunkt muss der Endpunkt genommen werden, welcher laut Wanda Basic/Smart erreichbar ist:

Welcher IDP-Dienst Endpunkt muss verwendet werden?WANDA BasicWANDA Smart
Deeplink (Authenticator → IDP-Dienst)Internet-IDPTI-Endpunkt

Token Request (Fachanwendung → IDP-Dienst)

Internet-IDPTI-Endpunkt
Wie heißen die IDP Endpunkte? 
Identity ProviderRU Internetidp-ref.app.ti-dienste.de

RU TI-Endpunkt
idp-ref.zentral.idp.splitdns.ti-dienste.de

PU Internetidp.app.ti-dienste.de

PU TI-Endpunkt
idp.zentral.idp.splitdns.ti-dienste.de
Wo kann ich meine Konnektor-Zertifikate hinterlegen?

Die notwendigen Zertifikate müssen im Verzeichnis:

C:\Program Files\gematik Authenticator\resources\certs-konnektor

hinterlegt werden.

Wo kann ich fachanwendungsspezifische Zertifikate hinterlegen?

Die notwendigen Zertifikate müssen im Verzeichnis:

C:\Program Files\gematik Authenticator\resources\certs-idp

hinterlegt werden.

Für Credential Manager

FrageAntwort

Was ist der Credential Manager im Kontext des Authenticators?

Der Credential Manager ist ein Sicherheitsfeature, das ab Version 4.8.0 im Authenticator integriert ist. Er dient dazu, sensible Informationen wie Passwörter sicher zu speichern und zu verwalten, anstatt sie im Klartext in der Konfigurationsdatei zu hinterlegen.

Welche Informationen werden im Credential Manager gespeichert?

 Im Credential Manager werden folgende Daten gespeichert:

  • Konnektor Basic Auth Benutzername
  • Konnektor Basic Auth Passwort
  • Proxy Basic Auth Benutzername
  • Proxy Basic Auth Passwort
  • P12-Zertifikat Passwort

Wie wird der Benutzername für das P12-Zertifikat im Credential Manager gespeichert?

Da im P12-Zertifikat keine Benutzerinformationen enthalten sind, wird der Benutzername standardmäßig als "p12Password" im Credential Manager gespeichert.

Wie funktioniert der Credential Manager in der Standalone-Version des Authenticators?

In der Standalone-Version des Authenticators werden die Einstellungen automatisch gespeichert. Dabei werden sensible Daten im Credential Manager und nicht sensible Daten in der Konfigurationsdatei config.json gespeichert.

Was passiert, wenn keine Eintragung im Credential Manager möglich ist?

In der Version 4.8.0 des Authenticators ist der Zugriff auf den Credential Manager in vielen Fällen zwingend erforderlich. Sollte ein Fehler beim Zugriff oder bei der Speicherung der Daten im Credential Manager auftreten, wird ein Fehler mit dem Code AUTHCL0010 angezeigt.

Muss ich bei einer zentralen Konfiguration alle Clients einzeln aktualisieren?

Derzeit arbeiten wir an einem Skript, das die Passwörter in einer Massenaktion für alle Clients in den Credential Manager überträgt. Sie können die Möglichkeiten, die Ihre Systeme bieten, nutzen, um Einstellungen für alle Clients gleichzeitig vorzunehmen. Mit anderen Worten, ist es möglich, die Aktualisierung der Clients zentralisiert zu handhaben, indem Sie die Werkzeuge und Funktionen Ihres Systems verwenden, um die notwendigen Änderungen für alle Clients gleichzeitig durchzuführen. Dies erleichtert den Prozess und spart Zeit, im Vergleich zur individuellen Aktualisierung jedes einzelnen Clients.

© gematik GmbH 2024