diff --git a/docs/changelog.md b/docs/changelog.md index ad585ca7402836f724b2f93a5ba6925e43414e78..a1bae2b2f06b593e85a743a5201606318eba9d18 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -4,6 +4,9 @@ Das Format dieser Datei basiert auf [Keep a Changelog](https://keepachangelog.co Das hier veröffentlichte Changelog bezieht sich auf die [Testinstanz von FIT-Connect](https://docs.fitko.de/fit-connect/docs/getting-started/get-started#testing). +## 2022-10-13 +### Dokumentation +- Dokumentation zur [Prüfung der `destinationSignature`](sending/get-destination.mdx#destinationSignature) überarbeitet und präzisiert. ## 2022-10-10 ### Dokumentation diff --git a/docs/sending/get-destination.mdx b/docs/sending/get-destination.mdx index 78262cace7bdeceb6d46ee34e038ba63a50c6acb..5a28b4d164fbddefed7c1abd93134a3972c8a202 100644 --- a/docs/sending/get-destination.mdx +++ b/docs/sending/get-destination.mdx @@ -108,8 +108,12 @@ Die Zustellpunkt-Informationen bestehen aus: - Der Name der zuständigen Fachbehörde (`destinationName`). - Die URL des Logos der zuständigen Fachbehörde (`destinationLogo`). -### Inhalt der Adressierungsinformationen (Parameter `destinationSignature`) +### Adressierungsinformationen (Parameter `destinationSignature`) {#destinationSignature} +Die im Parameter `destinationSignature` hinterlegten Adressierungsinformationen sind vom Self-Service Portal (SSP) signiert und wurden zuvor von der für den Zustellpunkt zuständigen Stelle [im Portalverbund hinterlegt](../organisation-tasks/routing.mdx). + +#### Payload der `destinationSignature` Der dekodierte Inhalt (Payload) der Adressierungsinformationen sieht beispielhaft wie folgt aus (Leerzeichen und Zeilenumbrüche dienen ausschließlich der besseren Lesbarkeit): + ```json { "submissionHost": "submission-api-testing.fit-connect.fitko.dev", @@ -130,10 +134,11 @@ Der dekodierte Inhalt (Payload) der Adressierungsinformationen sieht beispielhaf } ``` -### Signaturprüfung der vom Self-Service Portal (SSP) signierten Adressierungsinformationen (Parameter `destinationSignature`) {#checkDestinationSignature} -Bei den signierten Adressierungsinformationen handelt es sich um signierte JSON Web Tokens (JWTs). -Um die Signatur der vom Self-Service-Portal signierten JWTs zu überprüfen, ist es notwendig, auf die verwendeten Schlüssel (im Format JSON Web Key, kurz JWK) zugreifen zu können. -Das Self-Service-Portal stellt ein JSON Web Key Set (JWKS) öffentlich zugänglich über den Endpunkt `/.well-known/jwks.json` bereit. +#### Signaturprüfung der Adressierungsinformationen (Parameter `destinationSignature`) {#checkDestinationSignature} +Bei den vom Self-Service Portal (SSP) signierten Adressierungsinformationen handelt es sich um einen signierten JSON Web Token (JWT). +Durch eine Prüfung der Signatur des JWT kann eine Manipulation der Adressierungsinformationen durch die Systeme des Portalverbund sowie den Routingdienst ausgeschlossen werden. + +Den zur Prüfung der Signatur benötigten öffentlichen Schlüssel (im Format JSON Web Key, kurz JWK) stellt das Self-Service-Portal stellt in einem JSON Web Key Set (JWKS) öffentlich zugänglich über den Endpunkt `/.well-known/jwks.json` bereit. Für unser Testsystem ist das JWKS z.B. [hier](https://portal.auth-testing.fit-connect.fitko.dev/.well-known/jwks.json) verfügbar. Ein Beispiel für ein JWKS ist in folgendem Ausschnitt dargestellt: @@ -154,9 +159,14 @@ Ein Beispiel für ein JWKS ist in folgendem Ausschnitt dargestellt: } ``` -Mit diesem JWKS kann die Signatur der Adressierungsinformationen überprüft werden. -Hierfür muss der Schlüssel mit der passenden Schlüssel-ID (Key-ID) aus dem `kid`-Header der Adressierungsinformationen im JWKS ermittelt werden. -Dann kann man mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung durchführen. +Zur Prüfung der Signatur der Adressierungsinformationen muss der passenden Schlüssel mit der im `kid`-Header der Adressierungsinformationen hinterlegten Schlüssel-ID im JWKS ermittelt werden. +Anschließend kann mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung erfolgen. + +#### Prüfung von Leistungsschlüssel/ARS {#checkservices} +Zusätzlich sollte geprüft werden, ob der gegenüber der Routing-API angefragte Leistungsschlüssel und ARS zu einer der in den Adressierungsinformationen angegeben Kombinationen aus Leistungsschlüssel und ARS passt. +Erfolgt eine Anfrage auf Basis einer über die Routing API ermittelten Area-ID (anhand einer Postleitzahl bzw. eines Gebeitsnamens), so muss an dieser Stelle auf das korrekte Mapping des Routingdienstes zw. Postleitzahl/Gebeitsnamen und ARS vertraut werden, sodass eine Prüfung des ARS durch den Sender keinen Mehrwert bietet und daher ausgelassen werden kann. + +#### Code-Beispiel <Tabs defaultValue="java" @@ -203,6 +213,8 @@ Im folgenden Beispiel wird die Bibliothek [nimbus-jose-jwt](https://connect2id.c validateTrueOrElseThrow(payload.getClaim("jti") != null, "The claim jti is missing in the payload of the JWT."); validateTrueOrElseThrow(payload.getClaim("destinationId") != null, "The claim destinationId is missing in the payload of the JWT."); validateTrueOrElseThrow(payload.getClaim("submissionHost") != null, "The claim submissionHost is missing in the payload of the JWT."); + + // check if requested region/service matches an entry of the services list validateTrueOrElseThrow(payload.getClaim("services") != null, "The claim services is missing in the payload of the JWT."); validateTrueOrElseThrow(!((JSONArray) payload.getClaim("services")).isEmpty(), "At least one service is needed."); validateTrueOrElseThrow(