From 7a307c4c7b0a4c83a27e7b55eede462f287ee867 Mon Sep 17 00:00:00 2001
From: Florian Kaufmann <florian.kaufmann@codecentric.de>
Date: Wed, 24 Nov 2021 17:54:10 +0100
Subject: [PATCH] =?UTF-8?q?Exzensive=20Doku=20f=C3=BCr=20den=20Inhalt=20un?=
=?UTF-8?q?d=20Validierung=20von=20Zustellpunkt=20Address=20Informations?=
=?UTF-8?q?=20JWKS?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/getting-started/receiving/routing.mdx | 77 +++++++++++++++++++
.../getting-started/receiving/routing.mdx | 77 +++++++++++++++++++
2 files changed, 154 insertions(+)
diff --git a/docs/getting-started/receiving/routing.mdx b/docs/getting-started/receiving/routing.mdx
index be569ee70..37dc22f98 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 be569ee70..37dc22f98 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);
+}
+```
--
GitLab