Merge pull request #100 from gematik/feature/gemILF_VZD_FHIR_Directory

Feature/gem ilf vzd fhir directory

docs/FHIR_VZD_HOWTO_Authenticate.adoc

@@ -330,3 +330,23 @@ CAUTION: The diagramm displays the most important interaction parts. For detaile
 </p>
 ++++
 ====
+
+=== 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]
+====
+++++
+<p align="center">
+  <img width="55%" src=../images/diagrams/SequenceDiagram.FHIR-Directory.owner_auth_authenticator.svg>
+</p>
+++++
+====

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]
+====
+++++
+<p align="center">
+  <img width="55%" src=../images/diagrams/SequenceDiagram.FHIR-Directory.owner_auth_authenticator.svg>
+</p>
+++++
+====
+
+*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
 +++<s>ML-123677 - Maßnahmen gegen die Manipulation der Föderationsliste (VZD-FHIR-Directory, Sicherheitsgutachten)</s>+++ +
 +++<s>Im Sicherheitsgutachten des VZD-FHIR-Directories sind geeignete Maßnahmen gegen die Manipulation der Föderationsliste beschrieben.<=</s>+++
  +
+

src/plantuml/SequenceDiagram.FHIR-Directory.owner_auth_authenticator.puml

@@ -0,0 +1,75 @@
+@startuml
+autonumber 1 1 "<b>[00]"
+title "Entkoppelte FHIR-VZD Authentisierung"
+
+actor User as "Leistungserbringer"
+participant TIMClient as "TI-M Client"
+participant Authenticator as "gematik Authenticator"
+
+participant "gematik IDP-Dienst" as IdpDienst
+box VZD-FHIR-Directory #WhiteSmoke
+    participant "Auth-Service" as VzdAuth
+end box
+
+User->TIMClient++: Anmeldung starten
+
+TIMClient -> VzdAuth++: Decoupled Authorization Request\nPOST /owner-authenticate-decoupled\nHeader: Content-Type=application/x-www-form-urlencoded\nBody: grant_type=urn:telematik:params:grant-type:decoupled
+  VzdAuth -> VzdAuth: Erzeuge PKCE_code_challenge, PKCE_code_verifier und state
+VzdAuth -> VzdAuth: Erzeuge auth_req_id
+note right: **Siehe Bildungsregel:**\nhttps://openid.net/specs/openid-client-initiated-backchannel\n-authentication-core-1_0.html#rfc.section.7.3
+VzdAuth -> VzdAuth: code, state und auth_req_id werden als Autorisierungsauftrag\n in einem persistent Store gespeichert
+
+
+VzdAuth --> TIMClient: Decoupled Authorization Response 200 OK \n(\n\t"auth_req_id": "...",\n\t"poll_uri": "...",\n\t//{redirect_uri}//: "https://idp-ref.app.ti-dienste.de/auth?\n\t\tresponse_type=code\n\t\t&client_id=GEMgematFHI4HkPrd8SR\n\t\t&scope=fhir-vzd+openid\n\t\t&redirect_uri=https%3A%2F%2Ffhir-directory-ref.vzd.ti-dienste.de%2Fsignin-gematik-idp-dienst\n\t\t&state=HkX8By1qMekEg4a7B1aXyw\n\t\t&code_challenge=a0kY3HugNKgveqhBQjc1tmX4_m-OT7FMF175rDlOIOM\n\t\t&code_challenge_method=S256",\n\t "expires_in": 600,\n\t "interval": 3\n)
+
+par Authenticator Flow
+
+TIMClient -> Authenticator++: Deeplink-Aufruf:\nauthenticator://?\n  challenge_path=//{redirect_uri}//\n\t**&callback=DIRECT**\n\t**&cardType=HBA**
+Authenticator <--> IdpDienst++: Der Authenticator interagiert mit dem IDP\n und über einen Konnektor mit den Smartcards.\nAm Ende des Prozesses erhält der Authenticator\n den auth_code vom IDP. **Siehe nächster Aufruf!**
+IdpDienst -> Authenticator: 302 Redirect auf die redirect_uri des VZD-FHIR\n mit dem auth_code und dem state
+deactivate IdpDienst
+Authenticator -> VzdAuth: Der Authenticator ruft selbst mit einem HTTP Get,\nredirect_uri&code=XXX&state=YYY auf.\n)
+VzdAuth -> VzdAuth: Finde via state den Autorisierungsauftrag\nund speichere auth_code in diesem Autorisierungsauftrag
+VzdAuth -> Authenticator: 200 OK, Empty Body
+Authenticator->Authenticator--: Anwendung wird beendet
+VzdAuth->IdpDienst++: Übergabe des auth_code und des\nkey_verifier an den Token Endpunkt
+note left: **Siehe:**\nhttps://github.com/gematik/api-ti-messenger/blob/main/docs/IDP/\nidp.adoc#3231-erzeugung-des-key_verifier-durch-die-relying-party
+return signierter id_token
+VzdAuth->VzdAuth: Erzeuge owner-accesstoken auf Basis des id_tokens\nund speichere dieses am Autorisierungsauftrag
+
+else TI-M Client pollt
+
+TIMClient -> VzdAuth: Access Token Request POST {poll_uri}\naus Decopled Authorization Response\nBody: auth_req_id={auth_req_id}
+VzdAuth->VzdAuth: Prüfe ob für die übergebene auth_req_id\n ein Autorisierungsauftrag vorliegt und \nggf. bereits ein owner-accesstoken
+
+alt Poll Pending
+VzdAuth --> TIMClient: 400 Bad Request (Pending)
+note left
+{
+  "error":"authorization_pending"
+}
+end note
+else Poll Success
+VzdAuth -> TIMClient: 200 OK (Success)
+note left
+{
+  "access_token": "..."
+}
+end note
+else Poll Error
+VzdAuth -> TIMClient: 400 Bad Request (Error)
+note left
+{
+  "error": "access_denied"
+  ..or..
+  "error": "expired_token"
+  ..or..
+  "error": "slow_down"
+}
+end note
+end
+deactivate TIMClient
+deactivate VzdAuth
+end
+== ...fachlicher flow... ==
+@enduml