Merge pull request #97 from gematik/feature/gemILF_VZD_FHIR_Directory

Feature/gem ilf vzd fhir directory

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.0
+|Version: |1.0.1
 |Referencing: |gemILF_FHIR_VZD
 |===
 
@@ -34,6 +34,8 @@ image::gematik_logo.svg[gematik,float="right"]
 
 |1.0.0 |28.07.23 | |Initial document |gematik
 
+|1.0.1 |25.08.23 |Chap. 2.4 |added chapter for owner auth |gematik
+
 |===
 
 == Classification of the document
@@ -114,7 +116,7 @@ The request returns a matrix access_token
 ====
 ++++
 <p align="center">
-  <img width="55%" src=../images/diagrams/SequenceDiagram.FHIR-Directory.search.auth.svg>
+  <img width="55%" src=../images/diagrams/SequenceDiagram.FHIR-Directory.search_auth.svg>
 </p>
 ++++
 ====
@@ -194,6 +196,7 @@ For search examples see: link:FHIR_VZD_HOWTO_Search.adoc[Search Examples]
 === Authenticate for the provider API
 To use the TIM-PROVIDER-API, a corresponding TIM-Provider-API Token is needed.
 The following sequence diagram shows the flow to obtain such a token 
+
 .Search-Acccesstoken Flow
 [%collapsible%open]
 ====
@@ -271,7 +274,7 @@ The RegService-OpenID-Token must have the following structure:
 ----
 HEADER
 {
-  "alg": "ES256",
+  "alg": "BP256R1",
   "typ": "JWT"
   "x5c": [
      "<X.509 Sig-Cert, base64-encoded DER>"
@@ -300,14 +303,30 @@ curl -X GET "[baseUrl]/owner-authenticate" -H "Authorization: Bearer eyJhbGciOiJ
 [%collapsible%open]
 ====
 . jwt structure must follow https://www.rfc-editor.org/rfc/rfc7519#section-7.2[RFC7519 Validating a JWT]
-. OCSP check of the signature certificate
-. compare the signature certificate with one handed over while registering for the provider services endpoint credentials
-. validating signature(must be signed with certificate from X5c header)
 . validating certificate 
 .. type is C.FD.SIG
 .. technical role is "oid_tim" 
-. validating the used algorithm and the expiration time
+. validating the used algorithm(BP256R1) and the expiration time
 . checking for existence of field idnummer containing the TelematikID
+
+*Optional and mandatory starting with FHIR VZD 1.2*
+
+. compare the signature certificate with the one handed over while registering for the provider services endpoint credentials
+. OCSP check of the signature certificate
+. validating signature certificate against the X.509-Root-CA certificate
 ====
 
 === Authenticate for the owner endpoint as an user
+The user can authenticate himself by using his smartcard(HBA/SMC-B). The following diagram shows the interaction between a client, the Auth-Service of the VZD-FHIR Directory, a smartcard and the IDP.
+
+CAUTION: The diagramm displays the most important interaction parts. For detailed information on the checks performed by the IDP or the detailed smartcard interaction steps please consult the product specific specification.
+
+.owner-authenticate Flow
+[%collapsible%open]
+====
+++++
+<p align="center">
+  <img width="55%" src=../images/diagrams/SequenceDiagram.FHIR-Directory.owner_auth.svg>
+</p>
+++++
+====

docs/FHIR_VZD_HOWTO_Provider.adoc

@@ -18,7 +18,7 @@ image::gematik_logo.svg[gematik,float="right"]
 
 [width="100%",cols="50%,50%",options="header",]
 |===
-|Version: |1.0.0
+|Version: |1.0.1
 |Referencing: |gemILF_FHIR_VZD
 |===
 
@@ -34,6 +34,8 @@ image::gematik_logo.svg[gematik,float="right"]
 
 |1.0.0 |28.07.23 | |Initial document |gematik
 
+|1.0.1 |25.08.23 | Chap. 2|added link to auth page & removed Bearer for info endpoint |gematik
+
 |===
 
 == Classification of the document
@@ -52,16 +54,18 @@ _The following specification was created by gematik solely from a technical poin
 
 
 == FHIRDirectoryProviderAPI
+To access the provider API a valid provider access_token is needed that can be obtained by authenticating via link:FHIR_VZD_HOWTO_Authenticate.adoc#22-authenticate-for-the-provider-api[Provider Authenticate].
+
 === Query API Information
+This operation returns generell API information and no authentication is needed.
+
+.Request
 [source]
 ----
-curl -X GET \
+curl  -X GET \
   'https://fhir-directory-ref.vzd.ti-dienste.de/tim-provider-services/' \
-  --header 'Accept: */*' \
-  --header 'User-Agent: Thunder Client (https://www.thunderclient.com)' \
-  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXRlc3QudnpkLnRpLWRpZW5zdGUuZGUvdGktcHJvdmlkZXItYXV0aGVudGljYXRlIiwiYXVkIjoiaHR0cHM6Ly9maGlyLWRpcmVjdG9yeS10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlL3RpbS1wcm92aWRlci1zZXJ2aWNlcyIsInN1YiI6ImdlbWF0aWsiLCJpYXQiOjE2NzU2ODY3ODUsImV4cCI6MTY3NTc3MzE4NSwiY2xpZW50SWQiOiJnZW1hdGlrIn0.lvE0wqBpoRJPFSRhApl4xregokrIRf8R_Zplg6itm5pl86PAE-uGEJh_ir0Pu2ZOrE3fbgM29zSTA6lfjN72CQ'
+  --header 'Accept: */*'
 ----
-This operation returns generell API information.
 
 .Response Content
 [source]
@@ -84,11 +88,13 @@ This operation returns generell API information.
 ----
 
 === Query FederationList
+This operation returns the federation list. 
+
+.Request
 [source]
 ----
 curl -X GET "[baseUrl]/tim-provider-services/FederationList/federationList.jws" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXRlc3QudnpkLnRpLWRpZW5zdGUuZGUvdGktcHJvdmlkZXItYXV0aGVudGljYXRlIiwiYXVkIjoiaHR0cHM6Ly9maGlyLWRpcmVjdG9yeS10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlL3RpbS1wcm92aWRlci1zZXJ2aWNlcyIsInN1YiI6ImdlbWF0aWsiLCJpYXQiOjE2Nzg4NzI5NjAsImV4cCI6MTY3ODk1OTM2MCwiY2xpZW50SWQiOiJnZW1hdGlrIn0.hZDJXa-l1OK_B2NE54znl5FYWa5mW01Fw7LOiDo2kNIJOx2HPDCnEqxixd-7m9L34wq8WE4qVaA9jB6BNwX7qw"
 ----
-This operation returns the federation list. 
 
 .Response Content
 [source]
@@ -97,19 +103,53 @@ eyJ4NWMiOlsiTUZvd0ZBWUhLb1pJemowQ0FRWUpLeVFEQXdJSUFRRUhBMElBQkJpMkt6RlE4bEs0TFMy
 ----
 
 === Query MXID Location
+This operation returns the location of the MXID. 
+
+.Request
 [source]
 ----
 curl -X GET "[baseUrl]/tim-provider-services/localization?mxid=%401-2arvtst-ap000037%3Atim.test.gematik.de' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXRlc3QudnpkLnRpLWRpZW5zdGUuZGUvdGktcHJvdmlkZXItYXV0aGVudGljYXRlIiwiYXVkIjoiaHR0cHM6Ly9maGlyLWRpcmVjdG9yeS10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlL3RpbS1wcm92aWRlci1zZXJ2aWNlcyIsInN1YiI6ImdlbWF0aWsiLCJpYXQiOjE2ODEyMjEwNjUsImV4cCI6MTY4MTMwNzQ2NSwiY2xpZW50SWQiOiJnZW1hdGlrIn0.gThvA77gnbQAAtDYCj9THKc8DzKdR6afOkrgldKEgspOohGU6LFdQ5KsMEkkzJ1-g2oAl6rSGa4Drhz7oIrZ9g"
 ----
-This operation returns the location of the MXID. 
 
 .Response Content
 [source]
 ----
 "org"
 ----
 
+=== Add own domain
+This operation adds a new domain to the federation list.
+
+.Request
+[source]
+----
+curl  -X POST \
+  '[baseUrl]/tim-provider-services/federation' \
+  --header 'Accept: */*' \
+  --header 'User-Agent: Thunder Client (https://www.thunderclient.com)' \
+  --header 'Authorization: Bearer eyJhbGciOiJCUDI1NlIxIiwidHlwIjoiSldUIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXJlZi52emQudGktZGllbnN0ZS5kZS90aS1wcm92aWRlci1hdXRoZW50aWNhdGUiLCJhdWQiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXJlZi52emQudGktZGllbnN0ZS5kZS90aW0tcHJvdmlkZXItc2VydmljZXMiLCJzdWIiOiJnZW1hdGlrIiwiaWF0IjoxNjkyMjg1MzE0LCJleHAiOjE2OTIzNzE3MTQsImNsaWVudElkIjoiZ2VtYXRpayJ9.MN77Ar9JhuY8c1Qp_kHuWA2E8pFIO2btralTmJXqaOYYqHGxLZtISd_ybu-NbhI5Y3LWc6M7FP4Jg6ltqSxj_Q' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+  "domain": "matrix.test.service-ti.de",
+  "telematikID": "MY-SMC-B-Testkarte",
+  "isInsurance": false
+}'
+----
+
+.Response Content
+[source]
+----
+{
+  "domain": "matrix.test.service-ti.de",
+  "telematikID": "MY-SMC-B-Testkarte",
+  "isInsurance": false
+}
+----
+
 === Query own domains
+This operation returns all own domains. 
+
+.Request
 [source]
 ----
 curl -X GET \
@@ -118,7 +158,6 @@ curl -X GET \
   --header 'User-Agent: Thunder Client (https://www.thunderclient.com)' \
   --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXJlZi52emQudGktZGllbnN0ZS5kZS90aS1wcm92aWRlci1hdXRoZW50aWNhdGUiLCJhdWQiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXJlZi52emQudGktZGllbnN0ZS5kZS90aW0tcHJvdmlkZXItc2VydmljZXMiLCJzdWIiOiJnZW1hdGlrIiwiaWF0IjoxNjgxMjg3MDg2LCJleHAiOjE2ODEzNzM0ODYsImNsaWVudElkIjoiZ2VtYXRpayJ9.g-TOcYRmT64grzhQUKsdCXXJ0wH3WSQuVQwPAh6PrvQecJFPDcOqjOba-ojcUBWeIgT4lZBwGIjC4uBNMTKL4w'
 ----
-This operation returns all own domains. 
 
 .Response Content
 [source]
@@ -131,35 +170,36 @@ This operation returns all own domains.
   },
   {
     "domain": "ti-messenger.gdomain",
-    "telematikID": "1-2arvtst-ap000094",
+    "telematikID": "1-2arvtest-ap000094",
     "isInsurance": false
   },
   {
     "domain": "testserver.dev.service-ti.de",
-    "telematikID": "1-1gemref-testowner-0001",
+    "telematikID": "1-gemref-testowner-0001",
     "isInsurance": false
   }
 ]
 ----
 
 === Check own managed domains
-[source]
+This operation returns the own domains that are marked as "inactive".
+
+.Request
 ----
 curl -X GET \
   'https://fhir-directory-ref.vzd.ti-dienste.de/tim-provider-services/federationCheck' \
   --header 'Accept: */*' \
   --header 'User-Agent: Thunder Client (https://www.thunderclient.com)' \
   --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXJlZi52emQudGktZGllbnN0ZS5kZS90aS1wcm92aWRlci1hdXRoZW50aWNhdGUiLCJhdWQiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXJlZi52emQudGktZGllbnN0ZS5kZS90aW0tcHJvdmlkZXItc2VydmljZXMiLCJzdWIiOiJnZW1hdGlrIiwiaWF0IjoxNjgxMjg3MDg2LCJleHAiOjE2ODEzNzM0ODYsImNsaWVudElkIjoiZ2VtYXRpayJ9.g-TOcYRmT64grzhQUKsdCXXJ0wH3WSQuVQwPAh6PrvQecJFPDcOqjOba-ojcUBWeIgT4lZBwGIjC4uBNMTKL4w'
 ----
-This operation returns the own domains that are marked as "inactive".
 
 .Response Content
 [source]
 ----
 {
   "inactiveOrganizationDomains": [
     {
-      "domain": "testserver.dev.service-ti.de",
+      "domain": "testserver.service-ti.de",
       "telematikID": "1-1gemref-testowner-0001",
       "isInsurance": false
     }

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.0
+|Version: |1.0.1
 |Referencing: |gemILF_VZD_FHIR_Directory
 |===
 
@@ -33,6 +33,7 @@ image::gematik_logo.svg[gematik,float="right"]
  |*Editing* +
 
 |1.0.0 |28.07.23 | |Initial document |gematik
+|1.0.1 |25.08.23 | |Corrections and update according current development |gematik
 
 |===