diff --git a/docs/FHIR_VZD_HOWTO_Authenticate.adoc b/docs/FHIR_VZD_HOWTO_Authenticate.adoc index 019835da..c6270666 100644 --- a/docs/FHIR_VZD_HOWTO_Authenticate.adoc +++ b/docs/FHIR_VZD_HOWTO_Authenticate.adoc @@ -330,3 +330,23 @@ CAUTION: The diagramm displays the most important interaction parts. For detaile
++++ ==== + +=== Authenticate using the gematik Authenticator +The link:https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[gematik Authenticator] is a windows application that can be used to simplify the interaction with a connector, the card terminals and the users smartcards(SMC-B/HBA). The authenticator app can be started using a deeplink call (authenticator://) and the authenticator app takes over control. The authenticator offers 2 possibilities to interact with the caller: + +* calling the redirect_uri using the registered application for http calls +* calling the redirect_uri directly using a HTTP get Request + +The first option would require that the redirect_uri provided by the VZD-FHIR directory has to return application specific content that fits the callers needs. As the caller can be any application, this flow is not an option. +For the second option the caller needs information on the actual status of the authenticator authorization process.To fullfill this need the VZD-FHIR directory will provide an endpoint that can be used by clients to query the actual authorization process status. +The following sequence diagramm shows the process in detail. + +.owner-authenticate with the gematik Authenticator +[%collapsible%open] +==== +++++ ++ +
+++++ +==== \ No newline at end of file diff --git a/docs/VZD_FHIR_Directory-Spec-Changes.adoc b/docs/VZD_FHIR_Directory-Spec-Changes.adoc index 57607f4b..00e8289d 100644 --- a/docs/VZD_FHIR_Directory-Spec-Changes.adoc +++ b/docs/VZD_FHIR_Directory-Spec-Changes.adoc @@ -192,6 +192,135 @@ Siehe Kapitel 4.6.3 Zusammenführung mehrerer TelematikID´s zu einer Organisati |=== + +== Anbieten eines Polling Endpunktes +Wenn der Authenticator der gematik von Clients genutzt wird, um eine Authentifizierung auf Basis von Smartcards zu realisieren, dann ist es notwendig am Ende des Prozesses, die Kontrolle wieder an den Client zu übergeben und diesen mit den notwendigen Informationen für die weiteren Prozesschritte zu versorgen. Im folgenden werden die Anpassungen am Auth-Service des VZD-FHIR Directories beschrieben, die notwendig sind, um eine Anmeldung unter Verwendung des gematik Authenticators zu realsieren. + +Beim Anmeldevorgang verwendet der User eine Smartcard als Authentifizierungsmittel. Der Ablauf orientiert sich hierbei an den OIDC-Vorgaben zur link:https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html[Client initiated backchannel authentication]. Um die Kollisionen mit standard OAuth2 Grants zu vermeiden, definiert die gematik einen eigenen Grant urn:telematik:params:grant-type:decoupled als link:https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-08#section-6.3[Extension]. + +Der Standard kann nicht zu 100% umgesetzt werden, da hierfür ebenfalls noch eine Anpassung des gematik Authenticators und des IDP der gematik notwendig sind.Als Übergangslösung wird der Client den Aufruf des Authenticators übernehmen und das VZD-FHIR Directory einen Endpunkt bereitstellen über den der Status des Authentifizierungsvorgangs abgefragt werden kann. +OIDC Konformität und Abweichungen werden im Anschluss an das Sequenzdiagramm im Rahmen der Erläutertung der einzelnen Schritte hervorgehoben. +.owner-authenticate with the gematik Authenticator +[%collapsible%open] +==== +++++ ++ +
+++++ +==== + +*Notwendige Anpassungen/Neuerungen am VZD-FHIR Directory* +[options="header"] +|===== +| Funktionalität | Anfoderung +| Bereitstellung des initalen authenticate Endpunkt am Auth-Service a| Das VZD-FHIR Directory muss einen /owner-authenticate-decoupled Endpunkt anbieten der POST Request mit dem übergebene grant_type urn:telematik:params:grant-type:decoupled akzeptiert. + +.neuer owner Endpunkt +[%collapsible%closed] +==== +[source] +---- +POST /owner-authenticate-decoupled HTTP/1.1 +Host: https://fhir-directory-ref.vzd.ti-dienste.de/ +Content-Type: application/x-www-form-urlencoded + +grant_type=urn%3Atelematik%3Aparams%3Agrant-type%3Adecoupled +---- +==== +Erhält das VZD-FHIR Directory eine derartige Anfrage wird ein Autorisierungsauftrag mit den Werten: + +* auth_reg_id +* state +* owner-accesstoken(in diesem Moment noch unbefüllt) +* code_challenge + +erstellt und es werden folgende Daten an den Client im Response zurück geliefert: + +.owner Response +[%collapsible%closed] +==== +[source, json] +---- +HTTP/1.1 200 OK +Content-Type: application/json +Cache-Control: no-store + +{ + "auth_req_id": "bspuw6ea-scst-u5hn-p3nt-37khzwY4g", + "redirect_uri": "https://idp-ref.app.ti-dienste.de/...", + "poll_uri": "https://fhir-directory-ref.vzd.ti-dienste.de/...", + "expires_in": 600, + "interval": 3 +} +---- +==== +* expires_in: definiert die Zeit, die die auth_reg_id gültig ist und genutzt werden kann in Sekunden +* interval: definiert das Mindestwarteintervall zwischen 2 Pollinganfragen + +| Bereitstellung eines neuen polling Endpunktes am Auth-Service a| Das VZD-FHIR Directory muss einen Endpunkt anbieten, der von Clients genutzt werden kann, um den Status eines Autorisierungsauftrages abzufragen. +Dazu übergibt ein anfragender Client die folgenden Werte (wobei ist durch VZD festgelegter Endpoint, welcher im Schritt 06 dem Client über poll_uri mitgeteilt wird) + +.Token Request +[%collapsible%closed] +==== +[source, json] +---- +POST /oauth/v2/oauth-token HTTP/1.1 +Host: idsvr.example.com +Content-Type: application/x-www-form-urlencoded + +grant_type=urn%3Atelematik%3Aparams%3Agrant-type%3Adecoupled +auth_req_id=bspuw6ea-scst-u5hn-p3nt-37khzwY4g +---- +==== +Es wird geprüft, ob für die auth_req_id noch gültig ist und bereits ein owner-accesstoken vorliegt: +a) Es liegt ein passendes Token vor: +Dann antwortet der Auth-Service in seinem Response mit dem entsprechenden owner-accesstoken: + +.Token Response Success +[%collapsible%closed] +==== +[source, json] +---- +HTTP/1.1 200 OK + Content-Type: application/json + Cache-Control: no-store + + { + "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN" + "token_typ": "Bearer" + "expires_in": "86400" +} +---- +==== +b) liegt kein passendes Token vor dann antwortet der Server mit: + +.Token Response Error +[%collapsible%closed] +==== +[source, json] +---- +HTTP/1.1 400 Bad Request +Content-Type: application/json +Cache-Control: no-cache, no-store + +{ + "error": [ERROR_REASON] +} +---- +==== +Die ERROR_REASON kann die folgenden Werte annehmen: + +* authorization_pending - Der Authentifizierungsprozess ist noch nicht abgeschlossen +* slow_down - Wenn der Token Request noch nicht abgeschlossen ist und der Client hat den Request schneller als 3 Sekunden gestellt. +* access_denied - Der Authentifizierungsprozess konnte im Hintergrund nicht erfolgreich durchgeführt werden. +Das minimal erlaubte Polling-Interval wird auf 3 Sekunden festlgelegt. Das VZD speichert den Zeitstempel der letzten Polling-Anfrage, sodass bei der nächsten Anfrage mit dem gleichen auth_req_id der letzte Zeitstempel abgerufen werden kann (z.B. in der gleichen Datenbanktabelle). Der Zeitunterschied des aktuellen Zeitstempel und den letzten Zeitstempel muss im Minimum 3 Sekunden betragen. +| Bereitstellung einer neuen Redirect_uri | Aktuell liefert die vom VZD-FHIR Directory verwendete Redirect_uri (/signin-gematik-idp-dienst) bei Übergabe des Auth_code und des state einen owner-accesstoken zurück. Diese Rückgabe ist nicht notwendig, wenn der Authenticator die Redirect_uri direkt aufruft. +|===== +======= + + == Support und Unterstützungsleistungen Produktivbetrieb TI-Messenger *Es wird in gemSpec_VZD Kapitel 4.6.1.2.3 wie folgt ergänzt* + + @@ -213,3 +342,4 @@ Tabelle: Tab_VZD_Mapping_Eintragstyp_und_ProfessionOID +++