diff --git a/docs/Authenticator/authenticator.adoc b/docs/Authenticator/authenticator.adoc index fb32cbdd..5bdacc4e 100644 --- a/docs/Authenticator/authenticator.adoc +++ b/docs/Authenticator/authenticator.adoc @@ -35,7 +35,7 @@ CAUTION: Voraussetzungen für die Nutzung des von der gematik bereitgestellten * Der Authenticator ist eine Desktop-Anwendung mit grafischer Benutzerschnittstelle, welche aktuell unter Windows lauffähig ist und aus Anwendungen heraus aufgerufen wird. Es ist erforderlich den *Authenticator* in der Leistungserbringer-Umgebung zu konfigurieren. Zusätzliche Informationen finden Sie in der https://wiki.gematik.de/display/GAKB/Installationshandbuch+Authenticator[Installationsanleitung]. == Interaktion mit der Fachanwendung -Damit die Interaktion mit der Fachanwendung möglich ist, wird vorrausgesetzt das die Fachanwendung am zentralen *IDP-Dienst* registriert ist. Der *Authenticator* wird von einem Client über das Protokoll `authenticator://` gestartet (Deeplink). Beim Deeplink-Aufruf übergibt die Fachanwendung einen URL-String mit Query-Parametern. Dieser URL-String setzt sich abhängig vom verwendeten *IDP-Dienst* aus dem Protokoll (`authenticator://`) und weiteren Request-Parametern zusammen. Das Standardverhalten des *Authenticators* ist, dass nach Abschluss des Vorgangs der Response vom Aufruf der `redirect_uri` im default Browser des Betriebssystems geöffnet wird. Um das Öffnen in dem default Browser zu verhindern, bietet der *Authenticator* eine Auto-Redirect Funktion an. Mit dieser Funktion verarbeitet der *Authenticator* einen zusätzlichen Parameter: `callback=DIRECT`. Durch diesen ruft der *Authenticator* die `redirect_uri` direkt auf, anstatt das Ergebnis der Authentifizierung in einen neuen Browser-Tab zu öffnen. +Damit die Interaktion mit der Fachanwendung möglich ist, wird vorrausgesetzt, dass die Fachanwendung am zentralen *IDP-Dienst* registriert ist. Der *Authenticator* wird von einem Client über das Protokoll `authenticator://` gestartet (Deeplink). Beim Deeplink-Aufruf übergibt die Fachanwendung einen URL-String mit Query-Parametern. Dieser URL-String setzt sich abhängig vom verwendeten *IDP-Dienst* aus dem Protokoll (`authenticator://`) und weiteren Request-Parametern zusammen. Das Standardverhalten des *Authenticators* ist, dass nach Abschluss des Vorgangs der Response vom Aufruf der `redirect_uri` im default Browser des Betriebssystems geöffnet wird. Um das Öffnen in dem default Browser zu verhindern, bietet der *Authenticator* eine Auto-Redirect Funktion an. Mit dieser Funktion verarbeitet der *Authenticator* einen zusätzlichen Parameter: `callback=DIRECT`. Durch diesen ruft der *Authenticator* die `redirect_uri` direkt auf, anstatt das Ergebnis der Authentifizierung in einen neuen Browser-Tab zu öffnen. CAUTION: Die Anwendung gibt vor, welcher Kartentyp (SMC-B / HBA) für den Authentifizierungsprozess mittels *Authenticator* gesteckt werden soll. @@ -51,4 +51,4 @@ TIP: Sollten sich in den Konnektor-Terminals mehrere SMC-Bs befinden, erfolgt ab == Entwickleroption Innerhalb der Entwicklervariante des https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[Authenticators] ist ein Mockmodus integriert, der die Verwendung eines Konnektors simulieren kann. Somit können Funktionstests auch ohne physisch vorhandenen Konnektor durchgeführt werden. Diese Funktion soll die Entwicklung mit dem *Authenticator* vereinfachen, da sie neben einem speziellen Mockmodus auch mehr Logging-Möglichkeiten zur Verfügung stellt. Eine Anleitung für den Mockmodus ist link:https://wiki.gematik.de/display/GAKB/Gematik+Authenticator+-+Entwicklervariante+mit+Mockmodus[hier] zu finden. -Hersteller die den gematik *Authenticator* für eine smartcardbasierte Authentisierung an ihrer Fachanwendung bzw. ihren Fachdienst anbinden möchten, können die link:https://wiki.gematik.de/display/GAKB/Gematik+Authenticator+SDK+Dokumentation[SDK-Dokumentation] der gematik verwenden. Zusätzlich ist der Quellcode des *Authenticator* link:https://github.com/gematik/app-Authenticator[hier] einsehbar. \ No newline at end of file +Hersteller die den gematik *Authenticator* für eine smartcardbasierte Authentisierung an ihrer Fachanwendung bzw. ihren Fachdienst anbinden möchten, können die link:https://wiki.gematik.de/display/GAKB/Gematik+Authenticator+SDK+Dokumentation[SDK-Dokumentation] der gematik verwenden. Zusätzlich ist der Quellcode des *Authenticator* link:https://github.com/gematik/app-Authenticator[hier] einsehbar. diff --git a/docs/IDP/idp.adoc b/docs/IDP/idp.adoc index 862e6487..3b5e185a 100644 --- a/docs/IDP/idp.adoc +++ b/docs/IDP/idp.adoc @@ -315,9 +315,9 @@ TIP: Der Token-Endpunkt DARF `ID_TOKEN` mit einer Gültigkeitsdauer von mehr als Im ersten Schritt entschlüsselt die *Relying Party* das `ID_TOKEN` mit seinem selbst erzeugten 256-Bit AES-Schlüssel (`Token-Key`). Anschließend erfolgt die Signaturprüfung mit dem `PuK_IDP_SIG` des *IDP-Dienstes*. == Authorization Code Flow -In dem folgenden Sequenzdiagramm ist beispielhaft der Ablauf des Authorization Code Flow für den Anwendungsfall dargestellt. Im Kontext des *TI-Messenger-Dienstes* ist der *Registrierungs-Diens* die *Relying Party*. Als *Authenticator* wird der von der gematik bereitgestellte *Authenticator* verwendet. +In dem folgenden Sequenzdiagramm ist beispielhaft der Ablauf des Authorization Code Flow beim Authentisieren einer Organisation am TI-Messenger-Dienst dargestellt. Im Kontext des *TI-Messenger-Dienstes* ist der *Registrierungs-Diens* die *Relying Party*. Als *Authenticator* wird der von der gematik bereitgestellte *Authenticator* verwendet. -CAUTION: Der von der gematik bereitgestellte Authenticator wird nicht in Verbindung mit einer Web-Anwendung empfohlen, da vom Authenticator ein neuer Browser Tab geöffnet wird. Entsprechend der Fachanwendung wird im Browser eine HTML-Seite oder ein Json-Objekt(VZD-FHIR Response) angezeigt. +CAUTION: Der von der gematik bereitgestellte Authenticator wird nicht in Verbindung mit einer Web-Anwendung empfohlen, da vom Authenticator ein neuer Browser Tab geöffnet wird. Entsprechend der Fachanwendung wird im Browser eine HTML-Seite oder ein Json-Objekt(VZD-FHIR Response) angezeigt. Die Abbildung zeigt die Verwendung des *Authenticators* mit der Auto-Redirect Funktion (`callback=DIRECT`) bei der die `redirect_uri` direkt vom Authenticator aufgerufen wird und der Browserclient über Polling beim Fachdienst den Status des Austausches des Tokens abfragt. Details zur Interaktion mit dem *Authenticator* sind in Kapitel _Interaktion mit der Fachanwendung_ beschrieben. Alternativ könnte der *Authenticator* beim Aufruf der `redirect_uri` eine nutzerfreundliche Webseite der *Relying Party* in einem neuen Browsertab öffnen. diff --git a/src/openapi/TiMessengerContactManagement.yaml b/src/openapi/TiMessengerContactManagement.yaml index eaa0aa9f..78f280af 100644 --- a/src/openapi/TiMessengerContactManagement.yaml +++ b/src/openapi/TiMessengerContactManagement.yaml @@ -73,6 +73,9 @@ paths: $ref: "#/components/responses/DefaultResponse" /contacts: + parameters: + - $ref: "#/components/parameters/mxidHeader" + get: tags: - getContacts @@ -138,6 +141,7 @@ paths: /contacts/{mxid}: parameters: + - $ref: "#/components/parameters/mxidHeader" - $ref: "#/components/parameters/mxid" get: @@ -177,6 +181,14 @@ components: parameters: + mxidHeader: + name: Mxid + in: header + description: MXID of the contact settings owner. MUST match with the + MXID resolved from the Matrix-OpenID-Token. + required: true + schema: + type: string mxid: name: mxid in: path