From 2c8cb2f3b226764992bcc1c58a3cdc5a9d91ab8c Mon Sep 17 00:00:00 2001
From: Marco Holz <marco.holz@fitko.de>
Date: Sun, 20 Jun 2021 21:05:23 +0000
Subject: [PATCH] =?UTF-8?q?=C3=9Cberarbeitung=20von=20Authentifizierung=5F?=
=?UTF-8?q?von=5FUsern.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../Authentifizierung_von_Usern.md | 267 +++++++++++-------
1 file changed, 167 insertions(+), 100 deletions(-)
diff --git a/docs/Detailinformationen/Authentifizierung_von_Usern.md b/docs/Detailinformationen/Authentifizierung_von_Usern.md
index 1df50682..8e4b1fb5 100644
--- a/docs/Detailinformationen/Authentifizierung_von_Usern.md
+++ b/docs/Detailinformationen/Authentifizierung_von_Usern.md
@@ -1,146 +1,213 @@
-# Authentifizierung von Usern an Zustelldiensten
+# Authentifizierung von antragssendenden Systemen
+Treten die Schlüsselwörter "MUSS"/"MÜSSEN", "DARF NICHT"/"DÜRFEN NICHT", "SOLLTE"/"SOLLTEN", "SOLLTE NICHT"/"SOLLTEN NICHT" und "KANN"/"KÖNNEN" in Großbuchstaben auf, handelt es sich um Implementierungsvorgaben, die entsprechen den Begriffen "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" und "MAY" gemäß [RFC 2119](https://tools.ietf.org/html/rfc2119) zu interpretieren sind.
-Jeder Onlineantragsdienst muss bei FIT-Connect registriert sein, um FIT-Connect Formulare darstellen und übermitteln zu können. Bei der Registrierung von Onlinediensten wird festgelegt, welche Anträge die Onlinedienste auf welchen Domains ausspielen dürfen. Im Rahmen dieses Prozesses wird für jeden Onlinedienst außerdem ein Public Key hinterlegt. Nach der Anmeldung erhält jeder Onlineantragsdienst OAuth2-Credentials für den Authentifizierungstyp "Client-Credentials".
+Die Authentifizierung von antragssendenden Systemen erfolgt bei FIT-Connect auf Basis von OAuth 2.0 Client Credentials gemäß [RFC 6749](https://tools.ietf.org/html/rfc6749) und Access Tokens auf Basis von JSON Web Tokens gemäß [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519). Im Folgenden sollen die nötigen Schritte zur Registrierung und zum Zugriff auf die Schnittstelle des FIT-Connect Zustelldienstes beschrieben werden. Dieses Dokument dokumentiert die implementierten Authentifizierungsmechanismen und macht Vorgaben zur Implementierung der Authentifizierung von antragssendenden Systemen. Bei der Umsetzung der Authentifizierung kann darüber hinaus auf das vom Projekt FIT-Connect bereitgestellte Software Development Kit (SDK) zurückgegriffen werden, dass die Vorgaben aus diesem Dokument umsetzt bzw. bei deren Umsetzung unterstützt.
-Eine Registrierung eines Onlinedienstes ist über das Self-Service-Portal der FITKO möglich. (TODO: link) Dort müssen folgende Informationen über einen Onlinedienst hinterlegt werden:
+<img src="../../assets/images/oauth/JWT_konzept.png" alt="Grafik: JWT Konzept" width="400"/>
-- Freigegebene Domains, von denen der Onlinedienst Formulare übermittelt.
-- Erlaubte Zustellberechtigungs-Scopes, an die Anträge übermittelt werden dürfen.
-- Ein Public Key des Onlinedienstes, die er für die Erstellung von JWTs benutzt.
+## Schritt 1: Registrierung
+Jedes antragssendende System (z.B. ein Online-Antragsservice) muss bei FIT-Connect registriert sein, um über FIT-Connect Anträge einreichen zu können. Bei der Registrierung eines antragssendenden Systems wird festgelegt, welche Anträge das System über welche Domains ausspielen darf. Vor der Registrierung eines antragssendenden Systems muss zunächst ein kryptographisches Schlüsselpaar durch das antragssendende System erzeugt werden (im Folgenden: Onlineservice-Schlüsselpaar). Der öffentliche Schlüssel (Public Key) dieses Schlüsselpaares wird anschließend bei der Registrierung im Self-Service-Portal hinterlegt. Zur Generierung des Schlüsselpaares kann auf das bereitgestellte [Kommandozeilentool zurückgegriffen werden](https://pypi.org/project/fitconnect-cli/). Bei erfolgreicher Registrierung erhält jedes antragssendende System OAuth2-Zugangsdaten für den Authentifizierungstyp "Client-Credentials" (`client_id` und `client_secret`).
-Wenn ein Onlinedienst einem User ermöglichen möchte, einen Antrag zu übermitteln, muss er mithilfe seiner Client-Credentials beim FIT-Connect-Authentifizierungsserver einen JWT-Access-Token (Onlinedienst-Token) abrufen. Dieser Onlinedienst-Token enthält den Public-Key, der für den Onlinedienst bei der Anmeldung festgelegt wurde, im signierten Datensatz.
+Bei der Registrierung eines Online-Antragsservice über das Self-Service-Portal müssen die folgenden Informationen hinterlegt werden:
-Nun muss der Onlinedienst auf Basis des zum Public Key gehörenden Private Key einen weiteren JWT Token (User-Token) erzeugen, der Informationen dazu enthält, das der Onlinedienst dem User erlaubt, einen Antrag an eine spezifische Destinationen zu übermitteln.
+- Freigegebene Domains, von denen der Online-Antragsservice Formulare übermittelt
+- Eine Liste an [Zustellberechtigungs-Scopes](Zustellberechtigungs-Scopes.md), die definiert, an welche Zustellpunkte Anträge durch den registrierten API-Client übermittelt werden dürfen.
+- Der Public Key des Onlineservice-Schlüsselpaar
-Wenn der User nun einen Antrag an den Onlinedienst übermittelt, muss dieser sowohl den User-Token als auch den Onlinedienst-Token im Header mitübermitteln. Mithilfe der beiden Tokens kann das FIT-Connect API-Gateway nachvollziehen, von wo ein Antrag zu welcher Destination übermittelt wird und kann somit überprüfen, ob der User/Onlinedienst dafür autorisiert ist.
+## Schritt 2: Ausstellung von Berchtigungstokens für Onlineservices (Onlineservice-Token)
+Wenn ein Online-Antragsservice einer Antragsteller:in ermöglichen möchte, einen Antrag an die FIT-Connect Antrags-API zu übermitteln, muss dieser zunächst mithilfe der OAuth Client-Credentials beim OAuth-Server ein Berechtigungstoken (im Folgenden "Onlineservice-Token") nach dem Standard *JSON Web Token* gemäß [RFC 7519](https://tools.ietf.org/html/rfc7519)) abrufen. Dieser vom OAuth-Server signierte Onlineservice-Token enthält den Public-Key des Online-Antragsdienstes, der bei der Registrierung im Self-Service-Portal festgelegt wurde.
-<img src="../../assets/images/oauth/JWT_konzept.png" alt="JWT Konzept" width="400"/>
+### Payload des Onlineservice-Tokens
+Im Payload des signierten Onlineservice-Token MÃœSSEN mindestens die folgenden [standartisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein:
-### Warum ist die anonyme Authentifizierung notwendig?
+| Feld | Inhalt | **Erläuterung** |
+| --------------- | --------------------------------------- | --------------- |
+| `iat` | Unix Timestamp | Zeitpunkt, wann der Token vom Autorisierungsdienst ausgestellt wurde, als Unix Timestamp |
+| `exp` | Unix Timestamp | Zeitpunkt, wann der Token abläuft, als Unix Timestamp (Token DARF max. 24 Stunden gültig sein; vgl. [BSI APP.3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Grundschutz/Kompendium_Einzel_PDFs/06_APP_Anwendungen/APP_3_1_Webanwendungen_Edition_2020.pdf?__blob=publicationFile&v=1)) |
+| `iss` (Issuer) | *URL des Authentifizierungsservers* | Die URL des Authentifizierungsservers, der das Token ausgestellt hat. |
+| `sub` (Subject) | ID des Onlineservice | Wird bei der Anmeldung des Online-Antragsdienstes durch den Autorisierungsdienst festgelegt und dient zur Identifizierung des antragssendenden Systems |
+| `jti` (JWT ID) | *UUID des Tokens* | Eindeutige ID des ausgestellten Tokens. |
+| `scope` | *Liste von Zustellberechtigungs-Scopes* | Eine Liste der Zustellberechtigungs-Scopes, für die der Token eine Übermittlung erlaubt, separiert mit Leerzeichen gemäß [RFC 6749, Abschnitt 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) |
+| `domains` | *Liste von Domains* | Eine Liste der Domains, von denen der Onlineservice Anträge übermitteln kann, separiert mit Leerzeichen (Subdomains müssen explizit aufgeführt werden) |
+| `publicKey` | *Public Key des Onlineservice* | Der zum Schlüsselpaar des Online-Antragsservice gehörige Public Key, der dem Online-Antragsdienst bei der Registrierung im Self-Service-Portal zugeordnet wurde, im JSON Web Key-Format gemäß [RFC-7517](https://tools.ietf.org/html/rfc7517) |
+| `token_type` | `onlineservice` | Gibt an, das es sich um einen Token für einen Onlineservice handelt |
-Im Rahmen von FIT-Connect soll das massenhafte absenden (spammen) von Anträgen über Ratelimiting verhindert werden und es sollen nur vertrauenswürdige Webseiten, die dem FIT-Connect-Standards entsprechen, die Möglichkeit bekommen, Anträge über FIT-Connect zu übermitteln. Um diese Maßnahmen umsetzen und einen User über mehrere Requests hinweg sicher identifizieren zu können, ist eine Form der anonymen Authentifizierung notwendig.
-## Generierung der JWT-Tokens
+**Beispiel-Payload eines Onlineservice-Token**
+```json
+{
+ "iat": "1620072619",
+ "exp": "1620079819",
+ "iss": "https://auth.fit-connect.example.com",
+ "sub": "639c5be8-eb9c-4741-834e-4ad11629898a",
+ "jti": "1e078cd2-4717-4285-8746-91b62247eb60",
+ "scope": "leika:99108008252000 leika:99108008252000+region:08110000",
+ "domains": "example.com sub.example.com",
+ "publicKey": {
+ "kty": "RSA",
+ "e": "AQAB",
+ "key_ops": ["verify"],
+ "alg": "PS512",
+ "n": "...Public Key..."
+ },
+ "token_type": "onlineservice"
+}
+```
-Jedes Backend eines FIT-Connect Onlineantragsdienstes muss über ein System verfügen, welches JWT-Tokens für diese Instanz erzeugen und an den Browser des Users übermitteln kann. Es sollte dabei eine geeignete Form von Rate-Limiting, für die Ausstellung der Public Keys passend zum Usecase des Onlinedienstes implementieren. Es sollte die Menge der mit einem JWT-Token freigegebenen Destinationen minimieren. **Es dürfen in denen vom Onlineservice generierten JWT-Tokens keinen Informationen hinterlegt werden, die zur Identifikation des Users führen könnten.**
+## Schritt 3: Zugriff auf die Antrags-API mittels Access Tokens
+Für den Zugriff auf die Antrags-API des Zustelldienstes wird neben dem Onlineservice-Token immer auch ein sog. Access Token benötigt, der die generische [Zugriffsberechtigung des Onlinedienstes](./Zustellberechtigungs-Scopes.md) auf einen konkreten Zustellpunt (Destination) und/oder einen konkreten Antragsvorgang einschränkt. Dies ermöglicht die Weitergabe von eingeschränkten Berechtigungstokens an das Endgerät der Antragsteller:in (Browser bzw. App) und einen direkten, eingeschränkten Zugriff des Endgeräts auf die Antrags-API.
-### Anforderungen an die Keypairs
+Access Token und Onlineservice-Token müssen beim Zugriff auf die Antrags-API via HTTP-Header an den Zustelldienst übermittelt werden. Mithilfe der beiden Tokens kann nachvollzogen werden, von welchem antragssendenden System ein Antrag an welchen Zustellpunkt übermittelt wird und ob das antragssendende System hierzu autorisiert ist.
-Der Onlinedienst muss zur Registrierung bei FIT-Connect neben den Angaben dazu, welche Destinationen er unter welchen Domains verwendenden möchte, auch noch einen Public Key eines Keypairs, das nach folgenden Standards erzeugt wurde, übermitteln:
+**Beispiel**
+```http
+POST /applications HTTP/1.1
+Host: api.zustelldienst-01.example.com
+token: XXX
+online-service-token: XXX
+```
+
+Access Tokens werden entweder vom Online-Antragssservice mit Hilfe des bei der Registrierung erstellten Onlineservice-Schlüsselpaars oder vom Endgerät der Antragssteller:in mit Hilfe eines vorgangsspezifischen Schlüsselpaars signiert und DÜRFEN eine Gültigkeitsdauer von 2 Stunden NICHT überschreiten.
+
+Jedes Onlineservice-Backend muss dazu in der Lage sein, Access Tokens für den Zugriff auf die Antrags-API zu erzeugen und an das Endgerät der Antragsteller:in (Browser/App) zu übermitteln. Hierbei SOLLTE der Onlinedienst eine geeignete Form von Rate-Limiting für die Ausstellung der Access Tokens implementieren. Beim Zugriff auf die Antrags-API wird ein Rate-Limiting sowohl pro Online-Antragsdienst, als auch pro Antragsvorgang durchgeführt. In den vom Online-Antragsdienst generierten Access Tokens DÜRFEN keine Informationen hinterlegt werden, die zur Identifizierung von Antragssteller:innen geeignet sind.
-| Feld | Inhalt | **Erläuterung** |
-| ------------------ | ---------- | ------------------------------------------------------------ |
-| Hashingalgorithmus | SHA-512 | Algorithmus der zur digitalen Signatur des Keys verwendet werden muss an. Dieser muss im Fall von FIT-Connect immer SHA-512 sein. (vgl. [BSI TR-02102-1 Tabelle 4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
-| Keylänge | 4096 | Länge des zugrundeliegenden RSA-Keys. Diese entspricht der Empfehlung des BSIs für ab dem Jahr 2023. (vgl. [BSI TR-02102-1 Tabelle 3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html)) |
-| Signaturstandard | RSASSA-PSS | Entspricht dem Standard beschrieben in [RFC 4056](https://tools.ietf.org/html/rfc4056) und vom BSI empfohlen in [BSI TR-02102-1 Abschnitt 5.4.1.](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) |
+### Payload des Access Tokens
+Im Payload des signierten Access Tokens MÃœSSEN mindestens die folgenden [standartisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein:
-Bei der Erstellung und Signierung des Keys sind alle Regeln und Standards aus BSI [TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) zu beachten.
+| Feld | Inhalt | **Erläuterung** |
+| ---------------- | --------------------------- | --------------- |
+| `iat` | Unix Timestamp | Zeitpunkt, wann der Token ausgestellt wurde, als Unix Timestamp |
+| `exp` | Unix Timestamp | Zeitpunkt, wann der Token abläuft, als Unix Timestamp (Token DARF max. 2 Stunden gültig sein; vgl. [BSI APP.3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Grundschutz/Kompendium_Einzel_PDFs/06_APP_Anwendungen/APP_3_1_Webanwendungen_Edition_2020.pdf?__blob=publicationFile&v=1)) |
+| `iss` (Issuer) | ID des Onlineservice | Die ID des Onlineservice. Der angegebene Wert muss dem Feld `sub` des zugehörigen Onlineservice-Token entsprechen. |
+| `jti` (JWT ID) | *UUID des Tokens* | Eindeutige ID des ausgestellten Tokens. |
+| `aud` (Audience) | *URL der Zustelldienst-API* | Die URL der API des Zustelldienstes, für den der Token ausgestellt wurde, gemäß [RFC 7519, Abschnitt 4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3). |
+| `scope` | Zustellberechtigungs-Scope | Eingeschränkte Zustellberechtigung auf *eine* konkrete Destination-ID mit Präfix `destination:` (im Stile der Zustellberechtigungs-Scopes), für die der Token eine Antragseinreichung erlaubt. Der Zustellberechtigungs-Scope des zugehörigen Onlineservice-Token muss zur Antragseinreichung bei dieser Destination-ID berechtigen. |
+| `token_type` | *siehe unten* | Der Token-Typ gibt an, welche Funktion der ausgestellte Access Token erfüllt (siehe nächster Abschnitt). |
-### Anforderung an die JWT-Tokens
-Die vom Onlinedienst generierten JWT-Tokens müssen nach [RFC 7519](https://tools.ietf.org/html/rfc7519) über folgende Attribute verfügen:
+**Beispiel-Payload eines Access Token**
+```json
+{
+ "iat":"1620072619",
+ "exp":"1620079819",
+ "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
+ "jti": "b898ea5b-a411-4ba9-9b4c-64127e13c913",
+ "aud": "api.zustelldienst-01.example.com",
+ "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
+ "token_type": "create-submission"
+}
+```
-#### Header
+### Verwendung von Access Tokens
+Im Folgenden wird der Aufbau der eingesetzten Access Tokens beschrieben. Die hier beschriebenen Implementierungsdetails sollen dem technischen Verständnis dienen und unterstützen bei der Implementierung von Software zur Generierung und Prüfung der Access Tokens. Die im Projekt FIT-Connect bereitgestellten Code-Beispiele und SDKs setzen die hier beschriebenen Vorgaben um und KÖNNEN genutzt werden, um die beschriebene Funktionalität einfach und sicher in antragssendenden Systemen zu implementieren.
-Entsprechend [RFC 7519 Abschnnitt 8](https://tools.ietf.org/html/rfc7519#section-8):
+Je nach Art des Zugriffs MÜSSEN unterschiedliche Vorgaben für Access Tokens eingehalten werden:
-| Feld | Inhalt | **Erläuterung** |
-| ---- | ------ | ----------------------------------------------- |
-| typ | JWT | Es handelt sich um einen JWT-Token. |
-| alg | PS512 | Der JWT Token verwendet RSASSA-PSS und SHA-512. |
-| | | |
+| Art des Zugriffs | Vorgaben für Access Token |
+| ---------------- | --------------------------|
+| Initiale Antragseinreichung inkl. Vorgangseröffnung | Der Access Token wird durch das Onlineservice-Schlüsselpaar signiert. Im Payload des Tokens wird der Token-Typ auf `token_type: "create-submission"` festgelegt. |
-**Beispiel**
+Dieser Token-Typ berechtigt ausschließlich zum Anlegen von neuen Antragsvorgängen.
+**Beispiel-Payload eines Access Token mit Token-Typ ```create-submission```**
```json
{
- "typ":"JWT",
- "alg":"PS512"
+ "iat":"1620072619",
+ "exp":"1620079819",
+ "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
+ "jti": "84573d90-ad99-419b-b696-79e058eeff6d",
+ "aud": "api.zustelldienst-01.example.com",
+ "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
+ "token_type": "create-submission"
}
```
-#### Body des User-JWT-Tokens
+Beim Anlegen von neuen Antragsvorgängen MUSS für jeden Antragsvorgang ein separates kryptographisches Schlüsselpaar erzeugt werden (nachfolgend: Schlüsselpaar des Antragsvorgangs). Das Schlüsselpaar SOLLTE auf dem Endgerät der Antragsteller:in erzeugt werden. Sofern mit FIT-Connect eine Ende-zu-Ende-Verschlüsselung von der Antragsteller:in bis in das antragsempfangende System auf Verwaltungsseite realisiert werden soll, so MUSS das Schlüsselpaar auf dem Endgerät der Antragsteller:in erzeugt werden. Der öffentliche Schlüssel (Public Key) dieses Schlüsselpaares wird bei der Antragseinreichung über den Endpunkt `POST /applications` (TODO: Link) im eröffneten Vorgang hinterlegt.
-Entsprechend den [standartisierten Feldern](http://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms):
+Anschließend ermöglicht das generierte Schlüsselpaar bzw. ein daraus generierter Access Token die Authentifizierung der Antragsteller\:in:
-| Feld | Inhalt | **Erläuterung** |
-| ---------- | ------------------------- | ------------------------------------------------------------ |
-| iat | Unix Timestamp | Zeitpunkt wann der Token ausgestellt wurde als Unix Timestamp. |
-| exp | Unix Timestamp | Zeitpunkt wann der Token abläuft als Unix Timestamp (Token sollte max. 2 Stunden gültig sein vgl [BSI APP.3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Grundschutz/Kompendium_Einzel_PDFs/06_APP_Anwendungen/APP_3_1_Webanwendungen_Edition_2020.pdf?__blob=publicationFile&v=1)). |
-| scope | Liste von Destination-IDs | Eine Liste der Destination-IDs (im Stile der Zustellberechtigungs-Scopes geprefixed), für die der JWT eine Übermittlung erlaubt. |
-| sid | UUID4 der Session | Eine unique ID zur Identifizierung der Session (muss garantiert für jede Übermittlung anders sein) |
-| iss | ID des Onlinedienstes | Wird bei der Anmeldung des Onlinedienstes festgelegt und dient zur Identifizierung am API-Gateway |
-| domains | Liste von Domains | Eine Liste der Domains, von denen der Onlineservice Anträge übermitteln kann. Sie muss einem Subset der Domains entsprechen, die im domains Feld des Onlinedienst-JWT angegeben wurden. (Subdomains müssen explizit angegeben werden) |
-| clientType | user-sender | Gibt an, das es sich um denn abgeleiteten User Token eines Onlineservices handelt, mit dem Anträge eingereicht werden können. |
+| Art des Zugriffs | Vorgaben für Access Token |
+| ---------------- | --------------------------|
+| Uneingeschränkter Zugriff auf einen bestimmten Vorgang (Einreichen von Antragsdaten, Hinterlegen von Anhängen, Lesen und Schreiben des Event Log) | Der Access Token wird durch das Antragsvorgangs-Schlüsselpaar signiert. Ein Zugriff auf den Vorgang ist nur möglich, wenn im Zustelldienst zuvor der zugehörige Public Key des Antragsvorgangs-Schlüsselpaar hinterlegt wurde. Im Payload des Tokens wird der Token-Typ auf `token_type: access-case` festgelegt. |
-**Beispiel**
+Dieser Access Token wird mithilfe des Schlüsselpaares des Antragsvorgangs signiert. Im Zustelldienst wird die Signatur des Tokens mithilfe des bei der Antragserstellung hinterlegten Public Key geprüft. Der Access Token weist nach, dass der anfragende API-Client berechtigt ist, auf einen spezifischen Vorgang zuzugreifen. Mit Hilfe dieses Access Tokens können nun die Antragsdaten und Anhänge dem eröffneten Antrags hinzugefügt werden. Hierbei ist ein Zugriff auf die Antrags-API direkt durch das Endgerät der Antragsteller:in möglich.
+**Beispiel-Payload eines Access Token mit Token-Typ ```access-case```**
```json
-{ Â
- "iat":"1620072619", Â
- "exp":"1620079819",
- "scope": ["destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1"],
- "sid": "8d4dcbfd-a528-4e9b-abc3-477c4cc857aa",
- "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
- "clientType": "user-sender",
+{
+ "iat":"1620072619",
+ "exp":"1620079819",
+ "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
+ "jti": "ba3ba9a1-19d3-446b-a504-af9250cbaecf",
+ "aud": "api.zustelldienst-01.example.com",
+ "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
+ "token_type": "access-case"
}
-
```
-#### Body des Onlinedienst-JWT-Tokens
+Der Onlinedienst hat nach wie vor - sofern er die Vorgangsreferenz des Vorganges (`caseId`) kennt - jederzeit lesenden und schreibenden Zugriff auf Statusbenachrichtigungen zu einem konkreten Vorgang im zugehörigen Event Log. Hierzu stellt sich der Onlineservice selbst ein Access Token aus und kann anschließend mit Access Token und Onlineservice-Token auf das Event Log zugreifen:
-Entsprechend den [standartisierten Feldern](http://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms):
+| Art des Zugriffs | Vorgaben für Access Token |
+| ---------------- | --------------------------|
+| Lesen und Schreiben des Event Log | Der Access Token wird durch das Onlineservice-Schlüsselpaar signiert. Im Payload des Tokens wird der Token-Typ auf `token_type: "access-eventlog"` festgelegt. |
-| Feld | Inhalt | **Erläuterung** |
-| ---------- | ------------------------------------- | ------------------------------------------------------------ |
-| iat | Unix Timestamp | Zeitpunkt wann der Token ausgestellt wurde als Unix Timestamp. |
-| exp | Unix Timestamp | Zeitpunkt wann der Token abläuft als Unix Timestamp (Token sollte max. 24 Stunden gültig sein vgl [BSI APP.3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Grundschutz/Kompendium_Einzel_PDFs/06_APP_Anwendungen/APP_3_1_Webanwendungen_Edition_2020.pdf?__blob=publicationFile&v=1)). |
-| scope | Liste von Zustellberechtigungs-Scopes | Eine Liste der Zustellberechtigungs-Scopes oder Präfixes, für die der JWT eine Übermittlung erlaubt. |
-| publlicKey | Public Key des Onlinedienstes | Der Public Key, der dem Onlinedienst bei der Anmeldung zugeordnet wurde im JWK Format nach [RFC-7517](https://tools.ietf.org/html/rfc7517) |
-| aud | ID des Onlinedienstes | Wird bei der Anmeldung des Onlinedienstes festgelegt und dient zur Identifizierung des Onlineservices |
-| domains | Liste von Domains | Eine Liste der Domains, von denen der Onlineservice Anträge übermitteln kann. (Subdomains müssen explizit angegeben werden) |
-| clientType | sender | Gibt an, das es sich um einen Token für einen Onlineservice handelt, der Anträge versenden kann. |
+Mit Hilfe eines Access Tokens vom Typ `access-eventlog` können perspektivische auch andere berechtigte Systeme (z.B. Statusmonitor im Nutzer:innenkonto) auf den Status von Antragsvorgängen zugreifen).
-**Beispiel**
+**Beispiel-Payload eines Access Token mit Token-Typ ```access-eventlog```**
```json
-{ Â
- "iat":"1620072619", Â
- "exp":"1620079819",
- "scope": ["leika:99108008252000", "leika:99108008252000+region:08110000"],
- "clientType": "sender",
- "publicKey": {
- "kty": "RSA",
- "e": "AQAB",
- "key_ops": ["verify"],
- "alg": "PS512",
- "n": "...Public Key..."
- },
- "aud": "639c5be8-eb9c-4741-834e-4ad11629898a",
- "domains": ["example.com", "sub.example.com"]
+{
+ "iat":"1620072619",
+ "exp":"1620079819",
+ "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
+ "jti": "2c633a19-9e84-4b23-8caf-960580e8c883",
+ "aud": "api.zustelldienst-01.example.com",
+ "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
+ "token_type": "access-eventlog"
}
-
```
-## Validierung der JWT-Tokens durch die Sender-API/API-Gateway
-
-Bei jedem eingegangen Antrag muss der JWT-Token des Users validiert werden, um so Missbrauch der Antragsübermittlungsschnittstelle zu verhindern und nur korrekt implementierten FIT-Connect-Clients Zugang zur Antragsübermittlung zu geben.
-
-Nach dem Anlegen eines Antragsübertragungsprozesses kann auf diesen nur mit JWT-Tokens von demselben Onlinedienst und mit derselben Session-ID zugegriffen werden.
+## Kryptographische Vorgaben
+### Kryptographische Vorgaben für JSON Web Tokens
+Alle generierten JWT-Tokens MÜSSEN den Vogaben aus [RFC 7519](https://tools.ietf.org/html/rfc7519) entsprechen und über folgende Header-Attribute verfügen:
-Das API-Gateway muss die JWT-Tokens validieren:
+| Feld | Inhalt | **Erläuterung** |
+| ----- | ------- | --------------- |
+| `typ` | `JWT` | Es handelt sich um einen JSON Web Token (JWT). |
+| `alg` | `PS512` | Zur Signaturerstellung wird der Signaturalgorithmus RSASSA-PSS mit SHA-512 und MGF1 mit SHA-512 verwendet. |
-1. Überprüfen ob es sich um einen JWT mit einer **RSASSA-PSS (PS512)** Signatur handelt.
-2. Überprüfen, ob diese noch gültig sind und
- 1. der User-JWT-Token maximal für 2h ausgestellt wurde.
- 2. der Onlinedienst-JWT-Token für max. 24h ausgestellt wurde.
-3. Mithilfe des Public Keys des Authentifizierungsservers die Signatur des Onlinedienst-JWT überprüfen.
-4. Mithilfe des im JWT-Token des Onlinedienst enthaltenen Public Key die Signatur des User JWT überprüfen
-5. Überprüfen, ob die Destination-ID teil der in den Zustellberechtigungs-Scopes (**scope** Parameter in den JWT Tokens) beider JWT-Tokens ist. (Zugangsberechtigung des Onlinedienstes und des Users). Bzw. ob die LeiKa/Region entsprechend der Destination freigegeben ist.
-6. Überprüfen, ob die Website (origin), von der der Antrag abgesendet wurde, im domain Feld beider JWKs verzeichnet ist. (Verhindern von gefälschten Onlinediensten, die nicht den FIT-Connect-Standards entsprechen)
-7. Das API-Gateway kann aufgrund der folgenden Parameter Rate-Limiting für API-Calls (angepasst an die jeweiligen Use Cases des Onlineservices) betreiben:
+**Beispiel**
+```json
+{
+ "typ":"JWT",
+ "alg":"PS512"
+}
+```
-- sid
-- IP-Addresse des Users
-- Website von der der Antrag übermittelt wird bzw. das Fehlen eines Referers
-- Onlineservice-ID
+### Kryptographische Vorgaben für das im Onlineservice-Token hinterlegte Schlüsselpaar ("Onlineservice-Schlüsselpaar")
+Jedes antragssendende System MUSS vor der Registrierung im Self-Service-Portal ein Schlüsselpaar erzeugen und den öffentlichen Teil des Schüsselpaares (Public Key) bei der Registrierung im Self-Service angeben.
+
+Das erzeugte Schlüsselpaar MUSS eine Schlüssellänge von 4096 Bit aufweisen. Der zugehörige Public Key im Format *JSON Web Key* (JWK) MUSS über die folgenden Attribute gemäß [RFC 7515](https://tools.ietf.org/html/rfc7515#section-4) verfügen:
+
+| Feld | Inhalt | **Erläuterung** |
+| ------- | ----------------------------------------- | --------------- |
+| kty | `"RSA"` | Keytype gemäß [RFC 7517, Abschnitt 4](https://tools.ietf.org/html/rfc7517#section-4) |
+| key_ops | `["verify"]` | Schlüsselverwendung (Prüfung von digitalen Signaturen) gemäß [RFC 7517, Abschnitt 4.3](https://tools.ietf.org/html/rfc7517#section-4.3) |
+| alg | `"PS512"` | Vorgesehener Algorithmus zur Erstellung und Prüfung von Signaturen in Kombination mit diesem JWK. Vorgabe gemäß [BSI TR-02102-1, Abschnitt 5.4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) |
+| kid | *Eindeutige ID des Keys* | Eindeutige ID zur Referenzierung des JSON Web Key gemäß [RFC 7515, Abschnitt 4.1.4](https://tools.ietf.org/html/rfc7515#section-4.1.4) dar. Es wird empfohlen, hierfür eine UUID gemäß [RFC 4122](https://tools.ietf.org/html/rfc4122) zu verwenden. |
+| n | *Modulus des Public Key zum Zertifikat* | Der Modulus des Public Key gemäß [RFC 7518, Abschitt 6.3.1.1](https://tools.ietf.org/html/rfc7518.html#section-6.3.1.1) ("Base64urlUInt" enkodiert) |
+| e | `"AQAB"` | Der Exponent des Public Key gemäß [RFC 7518, Abschitt 6.3.1.2](https://tools.ietf.org/html/rfc7518.html#section-6.3.1.2)) |
+
+### Kryptographische Vorgaben für das vorgangsspezifische Schlüsselpaar ("Schlüsselpaar des Antragsvorgangs")
+Bei der Antrangseinreichung MUSS für jeden Antragsvorgang ein separates kryptographisches Schlüsselpaar erzeugt werden (nachfolgend: Schlüsselpaar des Antragsvorgangs). Das Schlüsselpaar SOLLTE auf dem Endgerät der Antragsteller:in erzeugt werden. Sofern mit FIT-Connect eine Ende-zu-Ende-Verschlüsselung von der Antragsteller:in bis in das antragsempfangende System auf Verwaltungsseite realisiert werden soll, so MUSS das Schlüsselpaar auf dem Endgerät der Antragsteller:in erzeugt werden. Der öffentliche Schlüssel (Public Key) dieses Schlüsselpaares wird bei der Einreichung eines Antrags im Antragsvorgang hinterlegt und ermöglicht die spätere Authentifizierung der Antragsteller:in.
+
+Das erzeugte Schlüsselpaar MUSS eine Schlüssellänge von 4096 Bit aufweisen. Der zugehörige Public Key im Format *JSON Web Key* (JWK) MUSS über die folgenden Attribute gemäß [RFC 7515](https://tools.ietf.org/html/rfc7515#section-4) verfügen:
+
+| Feld | Inhalt | **Erläuterung** |
+| ------- | ----------------------------------------- | --------------- |
+| kty | `"RSA"` | Keytype gemäß [RFC 7517, Abschnitt 4](https://tools.ietf.org/html/rfc7517#section-4) |
+| key_ops | `["verify"]` | Schlüsselverwendung (Prüfung von digitalen Signaturen, Verschlüsselung von (symmetrischen) Schlüsseln) gemäß [RFC 7517, Abschnitt 4.3](https://tools.ietf.org/html/rfc7517#section-4.3) |
+| alg | `"PS512"` | Vorgesehener Algorithmus zur Erstellung und Prüfung von Signaturen in Kombination mit diesem JWK. Vorgabe gemäß [BSI TR-02102-1, Abschnitt 5.4.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) |
+| kid | *Eindeutige ID des Keys* | Eindeutige ID zur Referenzierung des JSON Web Key gemäß [RFC 7515, Abschnitt 4.1.4](https://tools.ietf.org/html/rfc7515#section-4.1.4) dar. Es wird empfohlen, hierfür eine UUID gemäß [RFC 4122](https://tools.ietf.org/html/rfc4122) zu verwenden. |
+| n | *Modulus des Public Key zum Zertifikat* | Der Modulus des Public Key gemäß [RFC 7518, Abschitt 6.3.1.1](https://tools.ietf.org/html/rfc7518.html#section-6.3.1.1) ("Base64urlUInt" enkodiert) |
+| e | `"AQAB"` | Der Exponent des Public Key gemäß [RFC 7518, Abschitt 6.3.1.2](https://tools.ietf.org/html/rfc7518.html#section-6.3.1.2)) |
--
GitLab