From 53022f13b9ff010cf09568aaa599fb27d22c6483 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 8 Aug 2024 09:58:08 +0200 Subject: [PATCH] Fix broken gemILF_VZD_FHIR_Directory links (#251) * Fix broken gemILF_VZD_FHIR_Directory links * Update to 1.2.2 implementation guide --- README.adoc | 2 +- docs/Client/Client.adoc | 22 +++++++++++----------- docs/FHIR-Directory/FHIR-Directory.adoc | 10 +++++----- docs/Fachdienst/Registrierungsdienst.adoc | 16 ++++++++-------- docs/IDP/idp.adoc | 2 +- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.adoc b/README.adoc index 8ca5e722..50626354 100644 --- a/README.adoc +++ b/README.adoc @@ -51,7 +51,7 @@ Die folgende Abbildung gibt einen Überblick über die Systemarchitektur des *TI image::System_overview.png[width="100%"] -TIP: Auf die Schnittstellen zur Autentisierung am *Auth-Service* des *VZD-FHIR-Directory* wird in der oben gezeigten Abbildung verzichtet. Die Informationen hierzu können in dem entsprechenden Kapitel für das *VZD-FHIR-Directory* link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#2-fhirdirectoryauthenticationapis[hier] nachgelesen werden. +TIP: Auf die Schnittstellen zur Autentisierung am *Auth-Service* des *VZD-FHIR-Directory* wird in der oben gezeigten Abbildung verzichtet. Die Informationen hierzu können in dem entsprechenden Kapitel für das *VZD-FHIR-Directory* link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#fhirdirectoryauthenticationapis[hier] nachgelesen werden. link:docs/Fachdienst/Fachdienst.adoc[*TI Messenger-Fachdienst*] diff --git a/docs/Client/Client.adoc b/docs/Client/Client.adoc index 55445ed4..adf68236 100644 --- a/docs/Client/Client.adoc +++ b/docs/Client/Client.adoc @@ -24,7 +24,7 @@ Im Kontext des *TI-Messenger-Dienstes* wird zwischen den folgenden Ausprägungen * *TI-Messenger-Clients für Akteure* und * *TI-Messenger-Clients mit Administrationfunktionen*. -Beide Arten von Clients basieren auf dem offenen Kommunikationsprotokoll Matrix und werden auf dem Endgerät eines Akteurs verwendet. In der folgenden Dokumentation werden die zwei Ausprägungen der Clients beschrieben. +Beide Arten von Clients basieren auf dem offenen Kommunikationsprotokoll Matrix und werden auf dem Endgerät eines Akteurs verwendet. In der folgenden Dokumentation werden die zwei Ausprägungen der Clients beschrieben. IMPORTANT: Die Seite ergänzt die Spezifikation gemäß link:https://fachportal.gematik.de/fachportal-import/files/gemSpec_TI-Messenger-Client_V1.1.1.pdf[[gemSpec_TI-Messenger-Client]], die als Grundlage für das Verständnis vorrausgesetzt wird. @@ -39,7 +39,7 @@ image::I_Client.png[align="center",width="90%"] NOTE: Der Aufruf der vom *Matrix-Homeserver* angebotenen Schnittstellen der [Matrix - Client-Server API] erfolgt immer über den *Messenger-Proxy*. -In den folgenden Kapiteln werden die vom _TI-Messenger Modul_ zu verwendenen Schnittstellen sowie die vom *TI-Messenger-Client* bereitzustellenden Funktionen beschrieben. +In den folgenden Kapiteln werden die vom _TI-Messenger Modul_ zu verwendenen Schnittstellen sowie die vom *TI-Messenger-Client* bereitzustellenden Funktionen beschrieben. ===== Matrix - Client-Server API Der *Matrix-Homeserver* muss die REST-Schnittstellen gemäß der Matrix https://spec.matrix.org/v1.3/client-server-api/[[Client-Server API]] für den *TI-Messenger-Client* zur Verfügung stellen. Diese müssen für die *TI-Messenger-Clients* aus dem Internet angeboten werden. Für die Verarbeitung der `Matrix-Events` muss der *TI-Messenger-Client* die in der [Matrix-Client-Server API] clientspezifischen Verhaltensweisen implementieren. Diese sind in der API mit dem Keyword _behaviour_ gekennzeichnet. Unter folgendem https://spec.matrix.org/v1.3/client-server-api/#client-behaviour-21[Link] ist ein Beispiel dargestellt. @@ -95,13 +95,13 @@ NOTE: In der veröffentlichten und zulassungsrelevanten Spezifikationsversion v1 - `/search` + - `/owner` -Für den Aufruf der beiden Endpunkte `/search` und `/owner` am *FHIR-Proxy* für die Suche und Pflege von Einträgen werden Zugriffstoken benötigt, um die Berechtigung für den Zugriff nachzuweisen. Daher muss der *TI-Messenger-Client* zuvor am *Auth-Service* des *VZD-FHIR-Directory* die notwendigen Token anfragen. Im folgenden werden die Aufrufe der Endpunkte weiter beschrieben. +Für den Aufruf der beiden Endpunkte `/search` und `/owner` am *FHIR-Proxy* für die Suche und Pflege von Einträgen werden Zugriffstoken benötigt, um die Berechtigung für den Zugriff nachzuweisen. Daher muss der *TI-Messenger-Client* zuvor am *Auth-Service* des *VZD-FHIR-Directory* die notwendigen Token anfragen. Im folgenden werden die Aufrufe der Endpunkte weiter beschrieben. ===== Auth-Service Der *Auth-Service* des *VZD-FHIR-Directory* bietet die zwei Endpunkte an, die die beiden Zugriffstoken (`search-accesstoken` und `owner-accesstoken`) ausstellen. Die zwei Endpunkte werden in den folgenden Kapiteln weiter beschrieben. ====== /tim-authenticate -Für den Zugriff auf die Suchfunktionalität von FHIR-Ressourcen (`/search`-Endpunkt) authentisiert sich der *TI-Messenger-Client* gegenüber dem *VZD-FHIR-Directory* mit einem 3rd-Party-Token (`Matrix-OpenID Token`), das er von seinem *Matrix-Homeserver* anfordern kann (siehe link:https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3useruseridopenidrequest_token[Matrix OpenID Token]). Dieses 3rd-Party-Token benötigt der *TI-Messenger-Client*, um es beim `/tim-authenticate`-Endpunkt des *VZD-FHIR-Directory* gegen ein `search-accesstoken` einzutauschen. Bei Aufruf des Endpunktes `/tim-authenticate` ist es erforderlich, das 3rd-Party-Token (`Matrix-OpenID-Token`) im Header sowie die URL des *Matrix-Homeservers* im Parameter `MXID` zu übergeben. Der Aufruf des `/tim-authenticate`-Endpunktes ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Authenticate.adoc#21-authenticate-for-the-search-endpoint[hier] beschrieben. +Für den Zugriff auf die Suchfunktionalität von FHIR-Ressourcen (`/search`-Endpunkt) authentisiert sich der *TI-Messenger-Client* gegenüber dem *VZD-FHIR-Directory* mit einem 3rd-Party-Token (`Matrix-OpenID Token`), das er von seinem *Matrix-Homeserver* anfordern kann (siehe link:https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3useruseridopenidrequest_token[Matrix OpenID Token]). Dieses 3rd-Party-Token benötigt der *TI-Messenger-Client*, um es beim `/tim-authenticate`-Endpunkt des *VZD-FHIR-Directory* gegen ein `search-accesstoken` einzutauschen. Bei Aufruf des Endpunktes `/tim-authenticate` ist es erforderlich, das 3rd-Party-Token (`Matrix-OpenID-Token`) im Header sowie die URL des *Matrix-Homeservers* im Parameter `MXID` zu übergeben. Der Aufruf des `/tim-authenticate`-Endpunktes ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-for-the-search-endpoint[hier] beschrieben. ====== /owner-authenticate Für die Pflege von FHIR-Ressourcen (`/owner`-Endpunkt) authentisiert sich der *TI-Messenger-Client* gegenüber dem *VZD-FHIR-Directory* unter Verwendung einer Smartcard (HBA), um ein `owner-accesstoken` vom *Auth-Service* zu erhalten. Für die Authentisierung mittels Smartcard ist der von der gematik bereitgestellte link:/docs/IDP/idp.adoc[zentrale IDP-Dienst] zu verwenden. @@ -114,10 +114,10 @@ Der durchzuführende Authorization Code Flow ist link:/docs/IDP/idp.adoc#4-autho Der *FHIR-Proxy* bietet zwei Endpunkte zur Suche und Pflege von FHIR-Ressourcen an, die nur unter Verwendung eines gültigen Zugriffstoken aufgerufen werden können. Die zwei Endpunkte werden in den folgenden Kapiteln weiter beschrieben. ====== /search -Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectorySearchAPI` den Endpunkt `/search` an, um FHIR-Ressourcen zu suchen. Um diesen Endpunkt aufrufen zu können, wird ein `search-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle für die Suche von FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Search.adoc[search API examples] beschrieben. +Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectorySearchAPI` den Endpunkt `/search` an, um FHIR-Ressourcen zu suchen. Um diesen Endpunkt aufrufen zu können, wird ein `search-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle für die Suche von FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Search.adoc[search API examples] beschrieben. ====== /owner -Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectoryOwnerAPI` den Endpunkt `/owner` an, um FHIR-Ressourcen zu suchen und eigene Einträge zu pflegen. Um diesen Endpunkt aufrufen zu können, wird ein `owner-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben. +Der *FHIR-Proxy* bietet über die Schnittstelle `FHIRDirectoryOwnerAPI` den Endpunkt `/owner` an, um FHIR-Ressourcen zu suchen und eigene Einträge zu pflegen. Um diesen Endpunkt aufrufen zu können, wird ein `owner-accesstoken` im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben. ==== Auth Modul Über das _Auth Modul_ wird die Kommunikation mit Smartcards (HBA) realisiert, um diese zur Authentisierung am `/owner-authenticate`-Endpunkt zu ermöglichen. Im Folgenden wird der Prozess kurz skizziert, nachdem beim Aufruf des `/owner-authenticate`-Endpunktes das _Auth Modul_ einen `Redirect` zum `Authorization Endpoint` des *IDP-Dienstes* vom *Auth-Service* erhalten hat. @@ -130,7 +130,7 @@ An dem Endpunkt `/signin-gematik-idp-dienst` übergibt das _Auth Modul_ des *TI- === Bereitstellung weiterer Funktionalitäten ==== Sichbarkeit -*TI-Messenger-Clients* müssen über eine Funktion verfügen die die Sichtbarkeit eines Akteurs für den *TI-Messenger-Dienst* im Personenverzeichnis über den `/owner`-Endpunkt des *VZD-FHIR-Directory* ein bzw. ausschalten kann. Wenn ein Akteur den Status seines Endpunktes von `active` nach `off` link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc#232-update-endpoint-put[ändert], muss der *TI-Messenger-Client* prüfen, ob diese `MXID` auch im Organisationsverzeichnis eingetragen ist. Wird die `MXID` ebenfalls im Organisationsverzeichnis gefunden und ist der hinterlegte Status in diesem Verzeichnis active, dann ist im *TI-Messenger-Client* dem Akteur ein entsprechender Hinweis anzuzeigen, dass eine Inkonsistenz in der hinterlegten Sichtbarkeit vorliegt. +*TI-Messenger-Clients* müssen über eine Funktion verfügen die die Sichtbarkeit eines Akteurs für den *TI-Messenger-Dienst* im Personenverzeichnis über den `/owner`-Endpunkt des *VZD-FHIR-Directory* ein bzw. ausschalten kann. Wenn ein Akteur den Status seines Endpunktes von `active` nach `off` link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#update-endpoint-put[ändert], muss der *TI-Messenger-Client* prüfen, ob diese `MXID` auch im Organisationsverzeichnis eingetragen ist. Wird die `MXID` ebenfalls im Organisationsverzeichnis gefunden und ist der hinterlegte Status in diesem Verzeichnis active, dann ist im *TI-Messenger-Client* dem Akteur ein entsprechender Hinweis anzuzeigen, dass eine Inkonsistenz in der hinterlegten Sichtbarkeit vorliegt. IMPORTANT: Aus dem Hinweis muss hervorgehen, dass ein Kontaktieren des Administrators seiner Organisation notwendig ist, um die gewünschte Sichtbarkeit ebenfalls im Organisationsverzeichnis zu hinterlegen. @@ -176,14 +176,14 @@ Der Administrator einer Organisation (in der Rolle "Org-Admin") verwaltet mittel *Authentisierung* -Für den Zugriff auf die `/owner`-Schnittstelle am *FHIR-Proxy* wird ein `owner-accesstoken` benötigt, das vom `/owner-authenticate`-Endpunkt des *Auth-Service* ausgestellt wird. Zur Authentisierung am Endpunkt fragt der *Org-Admin-Client* beim zuständigen *Registrierungs-Dienst* einen `RegService-OpenID-Token` an, welcher am `/owner-authenticate`-Endpunkt gegen ein `owner-accesstoken` ausgetauscht wird. Ein Beispiel für die Authentisierung ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Authenticate.adoc#231-authenticate-with-an-regservice-openid-token[hier] zu finden. +Für den Zugriff auf die `/owner`-Schnittstelle am *FHIR-Proxy* wird ein `owner-accesstoken` benötigt, das vom `/owner-authenticate`-Endpunkt des *Auth-Service* ausgestellt wird. Zur Authentisierung am Endpunkt fragt der *Org-Admin-Client* beim zuständigen *Registrierungs-Dienst* einen `RegService-OpenID-Token` an, welcher am `/owner-authenticate`-Endpunkt gegen ein `owner-accesstoken` ausgetauscht wird. Ein Beispiel für die Authentisierung ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-with-an-regservice-openid-token[hier] zu finden. *Bearbeitung* -Zur Pflege der FHIR-Ressourcen ist es erforderlich, dass der *Org-Admin-Client* den Endpunkt `/owner` unter Verwendung des `owner-accesstoken` (welches im Authorization Header mit übergeben werden muss) aufruft. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in der link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben. Der vom *Org-Admin-Client* angebotene Funktionsumfang ist: +Zur Pflege der FHIR-Ressourcen ist es erforderlich, dass der *Org-Admin-Client* den Endpunkt `/owner` unter Verwendung des `owner-accesstoken` (welches im Authorization Header mit übergeben werden muss) aufruft. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in der link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc[owner API examples] beschrieben. Der vom *Org-Admin-Client* angebotene Funktionsumfang ist: -* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc#22-administration-of-resource-healthcareservice[HealthcareServices] und -* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.0/docs/FHIR_VZD_HOWTO_Owner.adoc#23-administration-of-resource-endpoint--metatagoriginowner[Endpoints]. +* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#administration-of-resource-healthcareservice[HealthcareServices] und +* Verwaltung von link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#administration-of-resource-endpoint-meta-tag-originowner[Endpoints]. ==== Funktionsaccounts Einrichtungen im Gesundheitswesen sind sehr unterschiedlich strukturiert und wollen hinsichtlich ihrer Erreichbarkeit flexibel eigene Strukturen abbilden können. Daher sind beim *TI-Messenger-Dienst* Funktionsaccounts notwendig, die es ermöglichen, Akteure unterhalb der Struktur erreichbar zu machen. Hierfür ist es erforderlich das über den *Org-Admin-Client* ein `Endpoint` im *FHIR-Directory* angelegt wird. diff --git a/docs/FHIR-Directory/FHIR-Directory.adoc b/docs/FHIR-Directory/FHIR-Directory.adoc index 21de3d31..ddf0b7b1 100644 --- a/docs/FHIR-Directory/FHIR-Directory.adoc +++ b/docs/FHIR-Directory/FHIR-Directory.adoc @@ -63,19 +63,19 @@ Weitere Informationen zu den Verzeichnistypen können link:https://github.com/ge == OAuth-Service Der *OAuth-Service* stellt ein `ti-provider-accesstoken` aus, welches am `/ti-provider-authenticate`-Endpunkt übergeben werden muss. Hierfür muss sich ein Anbieter eines *TI-Messenger-Fachdienstes* mittels seiner link:/docs/Fachdienst/Fachdienst.adoc#214-beantragung-der-ti-provider-credentials-am-vzd-fhir-directory[Zugangsdaten] am OAuth-Service authentisieren. -Der Aufruf des Endpunktes kann https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#22-authenticate-for-the-provider-api[hier] nachgelesen werden. +Der Aufruf des Endpunktes kann https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-for-the-provider-api[hier] nachgelesen werden. == Auth-Service -Der *Auth-Service* stellt Zugriffstoken aus, die für den Zugriff auf die Endpunkte am *FHIR-Proxy* benötigt werden. Der Aufruf der Endpunkte am *Auth-Service* ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#2-fhirdirectoryauthenticationapis[dort] beschrieben. +Der *Auth-Service* stellt Zugriffstoken aus, die für den Zugriff auf die Endpunkte am *FHIR-Proxy* benötigt werden. Der Aufruf der Endpunkte am *Auth-Service* ist link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#fhirdirectoryauthenticationapis[dort] beschrieben. == FHIR-Proxy Der *FHIR-Proxy* gibt Zugriff auf das *FHIR-Directory* unter Vorlage eines validen `ACCESS_TOKEN` und somit auf die FHIR-Ressourcen. Die vom *FHIR-Proxy* zur Verfügung gestellten Endpunkte werden für die Suche und Pflege von FHIR-Ressourcen verwendet sowie zur Pflege eigener TIM Provider Einträge. Der Aufruf der Endpunkte am *FHIR-Proxy* sind der folgenden Aufzählung zu entnehmen: -* https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Provider.adoc#2-fhirdirectoryproviderapi[/tim-provider-services] +* https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Provider.adoc#fhirdirectoryproviderapi[/tim-provider-services] -* https://github.com/gematik/api-vzd/blob//1.0.1/docs/FHIR_VZD_HOWTO_Search.adoc#21-fhirdirectorysearchapi-search-for-practitioners-and-organizations[/search] +* https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Search.adoc#fhirdirectorysearchapi-search-for-practitioners-and-organizations[/search] -* https://github.com/gematik/api-vzd/blob//1.0.1/docs/FHIR_VZD_HOWTO_Owner.adoc#2-fhirdirectoryownerapi[/owner] +* https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Owner.adoc#fhirdirectoryownerapi[/owner] TIP: Die Anbieter eines *TI-Messenger-Fachdienstes* nutzen die Schnittstelle `/tim-provider-services`, um die Föderationsliste abzufragen und um die Domains der von ihnen betriebenen *Messenger-Services* als Teil der TI-Messenger Föderation zu verwalten. diff --git a/docs/Fachdienst/Registrierungsdienst.adoc b/docs/Fachdienst/Registrierungsdienst.adoc index 9b8ae213..7cba1c87 100644 --- a/docs/Fachdienst/Registrierungsdienst.adoc +++ b/docs/Fachdienst/Registrierungsdienst.adoc @@ -33,7 +33,7 @@ Die abstrakte Schnittstelle `I_Registration` muss die folgenden Funktionalitäte CAUTION: Für die initiale Registrierung einer Organisation am *TI-Messenger-Fachdienst* ist die Verwendung der SMC-B notwendig und somit die Verwendung von einem Konnektor und Kartenterminal Voraussetzung. -Im folgenden werden die umzusetzenden Funktionalitäten der Schnittstelle beschrieben. +Im folgenden werden die umzusetzenden Funktionalitäten der Schnittstelle beschrieben. === Bereitstellung von Webschnittstellen Die von der abstrakten Schnittstelle `I_Registration` angebotene Funktionalität soll als Webschnittstelle bereitgestellt werden, die von einem Akteur über einen Webclient (*Frontend des Registrierungs-Dienstes*) genutzt wird. Diese muss für alle Akteure im Internet verfügbar sein. @@ -44,8 +44,8 @@ Die abstrakte Schnittstelle `I_Registration` muss es einer Organisation ermögli === Bereitstellung eines Messenger-Service Nach dem Authentifizierungsvorgang muss das bereitgestellte Admin-Konto verwendet werden, um *Messenger-Services* für die Organisation zu erstellen. Um einen neuen *Messenger-Service* zu erstellen, muss ein *Registrierungs-Dienst*: -. sich gegenüber dem Endpunkt `/tim-provider-services` gemäß https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#22-authenticate-for-the-provider-api[Authentisierung für die Anbieter-API] authentisieren und -. die neue Domäne zur Föderationsliste https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Provider.adoc#24-add-own-domain[hinzufügen]. +. sich gegenüber dem Endpunkt `/tim-provider-services` gemäß https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-for-the-provider-api[Authentisierung für die Anbieter-API] authentisieren und +. die neue Domäne zur Föderationsliste https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Provider.adoc#add-own-domain[hinzufügen]. == Schnittstelle: I_requestToken Die abstrakte Schnittstelle `I_requestToken` wird vom *Registrierungs-Dienst* zur Verfügung gestellt, um ein `RegService-OpenID-Token` anzufordern, das gegen ein `owner-accesstoken` am *Auth-Service* des *VZD-FHIR-Directory* ausgetauscht werden kann. Die Schnittstelle ist nur für Akteure in der Rolle "Org-Admin" zugänglich, um im Anschluß die FHIR-Ressourcen der Organisation im *VZD-FHIR-Directory* verwalten zu können. @@ -86,7 +86,7 @@ TIP: *VZD-FHIR-Directory* Endpunkte: + === Austausch des RegService-OpenID-Token Das `RegService-OpenID-Token` kann am `/owner-authenticate`-Endpunkt des *Auth-Service* gegen ein `owner-accesstoken` eingetauscht werden. -Weitere Details sind in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#231-authenticate-with-an-regservice-openid-token[Authentisierung RegService-OpenID-Token] beschrieben. +Weitere Details sind in link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-with-an-regservice-openid-token[Authentisierung RegService-OpenID-Token] beschrieben. == Schnittstelle: I_internVerification Bei der Schnittstelle `I_internVerification` handelt es sich um eine abstrakte Schnittstelle, deren Ausgestaltung dem Hersteller obliegt. @@ -98,12 +98,12 @@ Die Schnittstelle muss die folgenden Funktionalitäten bereitstellen: TIP: Die geforderten Funktionalitäten dürfen auch über seperate Schnittstellen zur Verfügung gestellt werden. -Die umzusetzenden Funktionalitäten werden im folgenden beschrieben. +Die umzusetzenden Funktionalitäten werden im folgenden beschrieben. === Bereitstellung und Aktualisierung der Föderationsliste. -Um die Zugehörigkeit zur TI-Messenger-Föderation zu verifizieren, muss der *Registrierungs-Dienst* den *Messenger-Proxies* über die abstrakte Schnittstelle `I_internVerification` eine aktuelle Föderationsliste zur Verfügung stellen. Dazu muss der *Registrierungs-Dienst* die Operation `/tim-provider-services/getFederationList` am *FHIR-Proxy* des *VZD-FHIR-Directory* aufrufen, um eine aktuelle Föderationsliste zu erhalten. Diese Schnittstelle ist am *VZD-FHIR-Directory* durch einen `ACCESS_TOKEN` geschützt (https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Authenticate.adoc#22-authenticate-for-the-provider-api[provider-accesstoken]). Nach Erhalt des `provider-accesstokens` muss dieses im Authorization Header genutzt werden, um über die Operation https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Provider.adoc#22-query-federationlist[getFederationList] eine aktuelle Föderationsliste abzufragen. +Um die Zugehörigkeit zur TI-Messenger-Föderation zu verifizieren, muss der *Registrierungs-Dienst* den *Messenger-Proxies* über die abstrakte Schnittstelle `I_internVerification` eine aktuelle Föderationsliste zur Verfügung stellen. Dazu muss der *Registrierungs-Dienst* die Operation `/tim-provider-services/getFederationList` am *FHIR-Proxy* des *VZD-FHIR-Directory* aufrufen, um eine aktuelle Föderationsliste zu erhalten. Diese Schnittstelle ist am *VZD-FHIR-Directory* durch einen `ACCESS_TOKEN` geschützt (https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#authenticate-for-the-provider-api[provider-accesstoken]). Nach Erhalt des `provider-accesstokens` muss dieses im Authorization Header genutzt werden, um über die Operation https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Provider.adoc#query-federationlist[getFederationList] eine aktuelle Föderationsliste abzufragen. -Die aktuelle Struktur der Föderationsliste ist https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/src/schema/FederationList.json[hier] hinterlegt. +Die aktuelle Struktur der Föderationsliste ist https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/src/schema/FederationList.json[hier] hinterlegt. Im folgenden ist ein Beispiel für den Aufbau der Föderationsliste gezeigt: @@ -154,7 +154,7 @@ a| |==== === Berechtigungsprüfung - Stufe 3 -Der *Registrierungs-Dienst* muss den *Messenger-Proxies* über die abstrakte Schnittstelle `I_internVerification` eine Funktion anbieten, mit der die Überprüfung auf `MXID`-Einträge im *VZD-FHIR-Directory* möglich ist. Zur Prüfung muss der *Registrierungs-Dienst* die Operation `whereIs (GET /tim-provider-services/localization)` am *FHIR-Proxy* des *VZD-FHIR-Directory* verwenden. Ein Beispielaufruf ist https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.0.1/docs/FHIR_VZD_HOWTO_Provider.adoc#query-mxid-location[hier] zu finden. +Der *Registrierungs-Dienst* muss den *Messenger-Proxies* über die abstrakte Schnittstelle `I_internVerification` eine Funktion anbieten, mit der die Überprüfung auf `MXID`-Einträge im *VZD-FHIR-Directory* möglich ist. Zur Prüfung muss der *Registrierungs-Dienst* die Operation `whereIs (GET /tim-provider-services/localization)` am *FHIR-Proxy* des *VZD-FHIR-Directory* verwenden. Ein Beispielaufruf ist https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Provider.adoc#query-mxid-location[hier] zu finden. TIP: Es kann nur eine `MXID` im URL Format beim Aufruf der Operation `whereIs` übergeben werden. diff --git a/docs/IDP/idp.adoc b/docs/IDP/idp.adoc index 3a6d14e0..b30db265 100644 --- a/docs/IDP/idp.adoc +++ b/docs/IDP/idp.adoc @@ -112,7 +112,7 @@ PU: https://idp.app.ti-dienste.de/auth RU: https://idp-ref.app.ti-dienste.de/token + PU: https://idp.app.ti-dienste.de/token -In den folgenden Unterkapiteln werden die Endpunkte weiter beschrieben. +In den folgenden Unterkapiteln werden die Endpunkte weiter beschrieben. ==== Discovery-Endpunkt Das Discovery Dokument ist ein Base64 kodiertes Metadatendokument, das den Großteil der Informationen enthält, die für eine Anwendung zum Durchführen einer Anmeldung erforderlich sind. Hierzu gehören Informationen wie z. B. die zu verwendenden Schnittstellen und der Speicherort der öffentlichen Signaturschlüssel des *IDP-Dienstes*.