Merge pull request #104 from gematik/feature/gemILF_VZD_FHIR_Directory

FHIR VZD Implementierungsleitfaden v1.0.2

README.adoc

@@ -18,17 +18,18 @@ ifdef::env-github[]
 endif::[]
 
 image:https://shields.io/badge/gem Spec VZD-v1.14.0-blue[link="https://fachportal.gematik.de/fachportal-import/files/gemSpec_VZD_V1.14.0.pdf"]
-image:https://shields.io/badge/gemILF_Pflege_VZD-v1.5.4-green[link="https://github.com/gematik/api-vzd/blob/gemILF_Pflege_VZD/1.5.4/docs/gemILF_Pflege_VZD.adoc"]
-image:https://shields.io/badge/simplifier.net-0.10.1-red[link="https://simplifier.net/vzd-fhir-directory"] +
+image:https://shields.io/badge/gemILF_Pflege_VZD-v1.5.5-green[link="https://github.com/gematik/api-vzd/blob/gemILF_Pflege_VZD/1.5.5/docs/gemILF_Pflege_VZD.adoc"]
+image:https://shields.io/badge/simplifier.net-0.10.2-red[link="https://simplifier.net/vzd-fhir-directory"] +
 image:https://shields.io/badge/Admin API-1.9.5-green?logo=swagger[link="https://github.com/gematik/api-vzd/blob/I_Directory_Administration/1.9.5/src/openapi/DirectoryAdministration.yaml"]
 image:https://shields.io/badge/Application Maintenance API-1.2.4-green?logo=swagger[link="https://github.com/gematik/api-vzd/blob/I_Directory_Application_Maintenance/1.2.4/src/openapi/DirectoryApplicationMaintenance.yaml"]
 
 == Aktuelles
 
+* *11.09.2023* 👨‍💻 https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.2/docs/gemILF_VZD_FHIR_Directory.adoc[FHIR VZD Implementierungsleitfaden v1.0.2]
 * *25.08.2023* 👨‍💻 https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/gemILF_VZD_FHIR_Directory.adoc[FHIR VZD Implementierungsleitfaden v1.0.1]
 * *28.07.2023* 👨‍💻 https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/gemILF_VZD_FHIR_Directory.adoc[FHIR VZD Implementierungsleitfaden v1.0.0]
 * *12.05.2023* 👨‍💻 https://github.com/gematik/api-vzd/blob/gemILF_Pflege_VZD/1.5.5/docs/gemILF_Pflege_VZD.adoc[Implementierungsleitfaden v1.5.5]
-* *11.04.2023* 🔥 https://simplifier.net/packages/de.gematik.fhir.directory/0.10.1/~introduction[FHIR Package 0.10.1]
+* *11.04.2023* 🔥 https://simplifier.net/packages/de.gematik.fhir.directory/0.10.2/~introduction[FHIR Package 0.10.2]
 * *18.01.2023* 👨‍💻 https://github.com/gematik/api-vzd/blob/I_Directory_Administration/1.9.5/src/openapi/DirectoryAdministration.yaml[Directory Administration API v1.9.5]
 * *18.01.2023* 👨‍💻 https://github.com/gematik/api-vzd/blob/I_Directory_Application_Maintenance/1.2.4/src/openapi/DirectoryApplicationMaintenance.yaml[Directory Application Maintenance API v1.2.4]
 * *14.12.2022* 📄 https://fachportal.gematik.de/schnelleinstieg/downloadcenter/releases#c6770[Spezifikationen Verzeichnisdienst „VZD FHIR 1.0.0“]

docs/FHIR_VZD_HOWTO_Authenticate.adoc

@@ -18,7 +18,7 @@ image::gematik_logo.svg[gematik,float="right"]
 
 [width="100%",cols="50%,50%",options="header",]
 |===
-|Version: |1.0.1
+|Version: |1.0.2
 |Referencing: |gemILF_FHIR_VZD
 |===
 
@@ -36,6 +36,8 @@ image::gematik_logo.svg[gematik,float="right"]
 
 |1.0.1 |25.08.23 |Chap. 2.4 |added chapter for owner auth |gematik
 
+|1.0.2 |11.09.23 |Chap. 2.5 |added chapter "2.5. Authenticate using the gematik Authenticator" |gematik
+
 |===
 
 == Classification of the document
@@ -330,3 +332,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/gemILF_VZD_FHIR_Directory.adoc

@@ -18,7 +18,7 @@ image::gematik_logo.svg[gematik,float="right"]
 
 [width="100%",cols="50%,50%",options="header",]
 |===
-|Version: |1.0.1
+|Version: |1.0.2
 |Referencing: |gemILF_VZD_FHIR_Directory
 |===
 
@@ -28,13 +28,13 @@ image::gematik_logo.svg[gematik,float="right"]
 |===
 |*Version* +
  |*Stand* +
- |*Chap./ Page* +
+ |*Doc./ Chap./ Page* +
  |*Change reason, special instructions* +
  |*Editing* +
 
 |1.0.0 |28.07.23 | |Initial document |gematik
 |1.0.1 |25.08.23 | |Corrections and update according current development |gematik
-
+|1.0.2 |11.09.23 |FHIR_VZD_HOWTO_Authenticate |added "Authenticate using the gematik Authenticator" |gematik
 |===
 
 == Classification of the document
@@ -69,4 +69,3 @@ The content of these parts is contained in the linked documents. +
 IMPORTANT: For easier readability, links to explanations on https://www.hl7.org/fhir are used in this document. All information on these pages is always displayed for the latest FHIR version. The FHIR version used here for the FHIR VZD can be found here: https://simplifier.net/VZD-FHIR-Directory/~dependencies 
 
 
-

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