diff --git a/docs/getting-started/receiving/routing.mdx b/docs/getting-started/receiving/routing.mdx index be569ee70412bf161dfc2b6ec249a0a79a1b9f0e..37dc22f98719534d20545fca71c9dbe318e7bec8 100644 --- a/docs/getting-started/receiving/routing.mdx +++ b/docs/getting-started/receiving/routing.mdx @@ -12,3 +12,80 @@ Zustellpunkt Address Informationen können über einen Button in der Self-Servic <img width="800" alt="Zustellpunkt Address Informationen können über einen Button in der Zustellpunkt Übersichts Liste in die Zwischenablage kopiert werden. Von der Zwischenablage kann es dann in das Redaktionssystem kopiert/import werden." src={useBaseUrl('/images/ssp/destination-overview-export-address-information.png')}/> </div> + +### Inhalt eines Zustellpunkt Address Informations JWK + +Der Inhalt eines Address Informations JWK sieht beispielhaft und "json prettyfied" wie folgt aus: +```json +{ + "submissionHost": "zustelldienst.example.com", + "iss": "https://portal.example.com", + "services": [ + { + "gebietIDs": [ + "urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:rs:12345" + ], + "leistungIDs": [ + "urn:de:fim:leika:leistung:100" + ] + } + ], + "destinationId": "0c438057-ec3e-4ce0-b154-1683b5d3c2e8", + "iat": 1637685592, + "jti": "ae37e58b-e280-4706-b99e-738f24c8d98f" +} +``` + +### Signaturprüfung des vom Self-Service Portal (SSP) erstellten Zustellpunkt Address Informations JWK + +Um die Signatur eines JWT zu überprüfen, welches vom SSP ausgestellt wurde, ist es notwendig auf die verwendeten Schlüssel zugreifen zu können. +Das SSP stellt ein 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: + +```json +{ + "keys": [ + { + "alg": "PS512", + "e": "AQAB", + "key_ops": [ + "verify" + ], + "kid": "6508dbcd-ab3b-4edb-a42b-37bc69f38fed", + "kty": "RSA", + "n": "65rmDz943SDKYWt8KhmaU…ga16_y9bAdoQJZRpcRr3_v9Q" + }, + { + "alg": "PS512", + "e": "AQAB", + "key_ops": [ + "verify" + ], + "kid": "14a70431-01e6-4d67-867d-d678a3686f4b", + "kty": "RSA", + "n": "wnqKgmQHSqJhvCfdUWWyi8q…yVv3TrQVvGtsjrJVjvJR-s_D7rWoBcJVM" + } + ] +} +``` +Mit diesem JWK Set kann die Signatur eines Zustellpunkt Address Informations JWK überprüft werden. +Hierfür muss der Schlüssel mit der passenden `kid` aus dem Header des Zustellpunkt Address Informations JWK’s im JWK Set gesucht werden. +Dann kann man mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung durchführen. +Im folgenden Beispiel wird die Bibliothek [nimbus-jose-jwt](https://connect2id.com/products/nimbus-jose-jwt) für die Prüfung genutzt. + +```java +static final SSP_BASE_URL = "https://portal.example.com"; + +boolean verifySSPSignature(SignedJWT securityEventToken, String keyId) { + JWKSet jwks = JWKSet.load(SSP_BASE_URL + "/.well-known/jwks.json"); + JWK publicKey = jwks.getKeyByKeyId(keyId) + + if (publicKey.getAlgorithm() != JWSAlgorithm.PS512) { + throw new RuntimeException("The key specified for signature verification doesn't use/specify PS512 as algorithm.") + } + + JWSVerifier jwsVerifier = new RSASSAVerifier(publicKey.toRSAKey()); + return signedJWT.verify(jwsVerifier); +} +``` diff --git a/versioned_docs/version-FIT-Connect_v1/getting-started/receiving/routing.mdx b/versioned_docs/version-FIT-Connect_v1/getting-started/receiving/routing.mdx index be569ee70412bf161dfc2b6ec249a0a79a1b9f0e..37dc22f98719534d20545fca71c9dbe318e7bec8 100644 --- a/versioned_docs/version-FIT-Connect_v1/getting-started/receiving/routing.mdx +++ b/versioned_docs/version-FIT-Connect_v1/getting-started/receiving/routing.mdx @@ -12,3 +12,80 @@ Zustellpunkt Address Informationen können über einen Button in der Self-Servic <img width="800" alt="Zustellpunkt Address Informationen können über einen Button in der Zustellpunkt Übersichts Liste in die Zwischenablage kopiert werden. Von der Zwischenablage kann es dann in das Redaktionssystem kopiert/import werden." src={useBaseUrl('/images/ssp/destination-overview-export-address-information.png')}/> </div> + +### Inhalt eines Zustellpunkt Address Informations JWK + +Der Inhalt eines Address Informations JWK sieht beispielhaft und "json prettyfied" wie folgt aus: +```json +{ + "submissionHost": "zustelldienst.example.com", + "iss": "https://portal.example.com", + "services": [ + { + "gebietIDs": [ + "urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:rs:12345" + ], + "leistungIDs": [ + "urn:de:fim:leika:leistung:100" + ] + } + ], + "destinationId": "0c438057-ec3e-4ce0-b154-1683b5d3c2e8", + "iat": 1637685592, + "jti": "ae37e58b-e280-4706-b99e-738f24c8d98f" +} +``` + +### Signaturprüfung des vom Self-Service Portal (SSP) erstellten Zustellpunkt Address Informations JWK + +Um die Signatur eines JWT zu überprüfen, welches vom SSP ausgestellt wurde, ist es notwendig auf die verwendeten Schlüssel zugreifen zu können. +Das SSP stellt ein 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: + +```json +{ + "keys": [ + { + "alg": "PS512", + "e": "AQAB", + "key_ops": [ + "verify" + ], + "kid": "6508dbcd-ab3b-4edb-a42b-37bc69f38fed", + "kty": "RSA", + "n": "65rmDz943SDKYWt8KhmaU…ga16_y9bAdoQJZRpcRr3_v9Q" + }, + { + "alg": "PS512", + "e": "AQAB", + "key_ops": [ + "verify" + ], + "kid": "14a70431-01e6-4d67-867d-d678a3686f4b", + "kty": "RSA", + "n": "wnqKgmQHSqJhvCfdUWWyi8q…yVv3TrQVvGtsjrJVjvJR-s_D7rWoBcJVM" + } + ] +} +``` +Mit diesem JWK Set kann die Signatur eines Zustellpunkt Address Informations JWK überprüft werden. +Hierfür muss der Schlüssel mit der passenden `kid` aus dem Header des Zustellpunkt Address Informations JWK’s im JWK Set gesucht werden. +Dann kann man mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung durchführen. +Im folgenden Beispiel wird die Bibliothek [nimbus-jose-jwt](https://connect2id.com/products/nimbus-jose-jwt) für die Prüfung genutzt. + +```java +static final SSP_BASE_URL = "https://portal.example.com"; + +boolean verifySSPSignature(SignedJWT securityEventToken, String keyId) { + JWKSet jwks = JWKSet.load(SSP_BASE_URL + "/.well-known/jwks.json"); + JWK publicKey = jwks.getKeyByKeyId(keyId) + + if (publicKey.getAlgorithm() != JWSAlgorithm.PS512) { + throw new RuntimeException("The key specified for signature verification doesn't use/specify PS512 as algorithm.") + } + + JWSVerifier jwsVerifier = new RSASSAVerifier(publicKey.toRSAKey()); + return signedJWT.verify(jwsVerifier); +} +```