Merge branch 'feature/gemILF_VZD_FHIR_Directory' into main_tmp

README.adoc

@@ -25,6 +25,7 @@ image:https://shields.io/badge/Application Maintenance API-1.2.4-green?logo=swag
 
 == Aktuelles
 
+
 * *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]

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/VZD_FHIR_Directory-Spec-Changes.adoc

@@ -192,7 +192,138 @@ 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* +
  +
 Es wird in gemSpec_VZD Kapitel 5. wie folgt ergänzt
@@ -207,3 +338,12 @@ Tabelle: Tab_VZD_Mapping_Eintragstyp_und_ProfessionOID
 
 
 |===
+
+== Korrekturen
+*Es wird in gemSpec_VZD_FHIR_Directory Kapitel "4.2.3 Erzeugung und Bereitstellung der Föderationsliste" wie folgt angepasst* +
+ +
++++<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/openapi/DirectoryAdministration.yaml

@@ -3,8 +3,19 @@ info:
   title: I_Directory_Administration
   description: REST Schnittstelle zur Pflege der Verzeichniseinträge.
               Über diese Schnittstelle können Verzeichniseinträge inklusive Zertifikaten erzeugt, aktualisiert und gelöscht werden. Die Administration von Fachdaten erfolgt über Schnittstelle I_Directory_Application_Maintenance und wird durch die Fachanwendungen durchgeführt. Lesender Zugriff auf die Fachdaten ist mit Operation getDirectoryEntries in vorliegender Schnittstelle möglich.
-  version: 1.11.0
+  version: 1.12.1
 
+  # Änderungen in Version 1.12.1 
+  #  - Merge von Versionen 1.12.0 und 1.11.1
+  #
+  # Änderungen in Version 1.12.0 
+  #  - Schema baseDirectoryEntry um Attribut providedBy erweitert. 
+  #    Damit wird die Zusammenführung von mehreren LDAP Einträgen in einer FHIR Organisation möglich.
+  #
+  # Änderungen in Version 1.11.1
+  #  - Schema baseDirectoryEntry um Attribut providedBy erweitert.
+  #  - Operation read_Directory_Entry: Suchparameter für komLeData und kimData vereinfacht
+  #
   # Änderungen in Version 1.11.0 
   #  - Schema FAD1 um kimData erweitert. Damit wird in read_Directory_Entry zusätzlich zu komLeData
   #    auch kimData im Response aufgenommen
@@ -345,6 +356,8 @@ paths:
                   - holder
                   - professionOID
                   - mail
+                  - komLeData
+                  - kimData    
           - Suche nach Vorhandensein oder leerem Inhalt eines Attributs des VZD Datensatzes mit dem Kode \00 in den Parametern
           
                   - givenName
@@ -540,50 +553,34 @@ paths:
           Selektiert alle Datensätze, deren Attribut FAD1.mail den angegebenen String in einem Wert des arry's enthält.
         schema:
           type: string  
-      - name: komLeData-mail
-        in: query
-        description: |
-          Erlaubt die Suche mit Hilfe des Attributs FAD1.komLeData.mail
-          
-          Selektiert alle Datensätze, deren Attribut FAD1.komLeData.mail den angegebenen String in einem Wert des arry's enthält.
-          Bitte beachten: Dieser Suchparameter wird auf eine LDAP Wildcard Suche mit führendem * abgebildet und verlangsamt die Operation signifikant.
-        schema:
-          type: string  
-      - name: komLeData-version
+      - name: komLeData
         in: query
         description: |
-          Erlaubt die Suche mit Hilfe des Attributs FAD1.komLeData.version
+          Erlaubt die Suche mit Hilfe des Attributs FAD1.komLeData
           
-          Selektiert alle Datensätze, deren Attribut FAD1.komLeData.version den angegebenen String in einem Wert des arry's enthält.
+          Selektiert alle Datensätze, deren Attribut FAD1.komLeData den angegebenen String in einem Wert des array's enthält.
+          komLeData enthält die "version" und "mail" durch Komma getrennt in einem array.
+          Beispiel: 1.0,mc_smcb_za@dom1.komle.telematik-test
+          Für diesen Suchparameter kann ein Wildcard genutzt werden.
         schema:
           type: string  
-      - name: kimData-mail
+      - name: kimData
         in: query
         description: |
           Erlaubt die Suche mit Hilfe des Attributs FAD1.kimData.mail
           
           Selektiert alle Datensätze, deren Attribut FAD1.kimData.mail den angegebenen String in einem Wert des arry's enthält.
+                    
+          Selektiert alle Datensätze, deren Attribut FAD1.kimData den angegebenen String in einem Wert des array's enthält.
+          komLeData enthält die "mail", "version" und "appTags" durch Komma getrennt in einem array.
+          Die appTags werden durch das Pipe Zeichen getrennt. 
+          Bitte beachten: Wenn das Pipe Zeichen im Suchstring genutzt wird muss die besondere
+          Bedeutung dieses Zeichens bei der LDAP Suche beachtet werden.
+          Beispiel: mz_smcb_za@dom2.kim.telematik-test,1.0,DALE-UV;Einsendung;V1.0|eEB;V1.0
+          Für diesen Suchparameter kann ein Wildcard genutzt werden, z.B. 
+            mz_smcb_za@dom2.kim.telematik-test*
         schema:
-          type: string  
-      - name: kimData-version
-        in: query
-        description: |
-          Erlaubt die Suche mit Hilfe des Attributs FAD1.kimData.version
-          
-          Selektiert alle Datensätze, deren Attribut FAD1.kimData.version den angegebenen String in einem Wert des arry's enthält.
-          Bitte beachten: Dieser Suchparameter wird auf eine LDAP Wildcard Suche mit führendem * abgebildet und verlangsamt die Operation signifikant.
-        schema:
-          type: string  
-      - name: kimData-appTags
-        in: query
-        description: |
-          Erlaubt die Suche mit Hilfe des Attributs FAD1.kimData.appTags
-          
-          Selektiert alle Datensätze, deren Attribut FAD1.kimData.appTags den angegebenen String in einem Wert des arry's enthält.
-          Bitte beachten: Dieser Suchparameter wird auf eine LDAP Wildcard Suche mit führendem * abgebildet und verlangsamt die Operation signifikant.
-        schema:
-          type: string  
-
+          type: string
 
       responses:
         200:
@@ -2081,6 +2078,28 @@ components:
           description: 'Wird beim Anlegen des Eintrags vom VZD aus dem Zertifikat übernommen (Feld registrationNumber der Extension Admission).
                     Falls der Basiseintrag (baseDirectoryEntry) ohne Zertifikat angelegt wird, kann in Operation add_Directory_Entry die telematikID angegeben werden.
             Damit ist der Verzeichniseintrag bereits über die telematikID im baseDirectoryEntry auffindbar. Diese telematikID muss mit der telematikID aus dem Zertifikatseintrag (userCertificate) übereinstimmen. Simmten die telematikIDs nicht überein, wird die Operation mit Fehlercode 422 abgelehnt' 
+        providedBy:
+          type: string
+          description: |
+           Erlaubt die Zusammenführung von mehreren LDAP Einträgen in einer FHIR Organisation.
+           In Attribut providedBy wird dazu die telematikID der übergeordneten Oragnisation eingetragen.
+           Wird in Attribut "providedBy" im LDAP VZD Eintrag eine TelematikID eingetragen, 
+           wird für den LDAP Eintrag im FHIR VZD ein HealthcareService unter der - mit der TelematikID -
+           referenzierten Organisation generiert.
+           Randbedingungen:
+            - Es wird nur eine Hierarchieebene unterstützt (providedBy vom referenzierten Datensatz
+              MUSS leer sein)
+            - Es können nur Organisationseinträge zusammengeführt/verlinkt werden (personalEntry=false)
+            - Das Attribut "providedBy" darf nur eine TelematikID enthalten.
+            - Der Client - der dieses Attribut setzt - MUSS auch für den referenzierten 
+              LDAP Datensatz als Holder eingetragen sein.
+            - Wenn Attribut providedBy gesetzt wurde, kann es nur zurückgesetzt 
+              (Inhalt auf leer gesetzt) werden. Eine Änderung auf einen anderen Wert 
+              wird nicht unterstützt.  
+            - Vor Löschung eines LDAP VZD Eintrags müssen alle Verlinkungen über Attribut "providedBy"
+              von anderen Datensätzen auf den zu löschenden Datensatz entfernt werden.  
+            Bei Nichteinhaltung der Randbedingungen wird die Schreiboperation (POST/PUT) mit
+            Fehler (HTTP Status 400) und entsprechendem Fehlertext beendet.
         specialization:
           maxItems: 100
           type: array