diff --git a/docs/Detailinformationen/Authentifizierung_von_antragsempfangenden_Systemen.md b/docs/Detailinformationen/Authentifizierung_von_antragsempfangenden_Systemen.md
index 7b0ce90687d282e860ab8d5b1921b8624041d92b..37c583fe6851af96a618ee93f5c257a57686fde3 100644
--- a/docs/Detailinformationen/Authentifizierung_von_antragsempfangenden_Systemen.md
+++ b/docs/Detailinformationen/Authentifizierung_von_antragsempfangenden_Systemen.md
@@ -1,12 +1,13 @@
-# Authentifizierung von Fachanwendungen
+# Authentifizierung von antragsempfangenden Systemen
+Die Authentifizierung von antragsempfangenden 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). Zum Abruf von Anträgen müssen sich antragsempfangende Systeme mit Hilfe von OAuth 2.0 Client-Credentials beim Authorisierungsdienst authentifizieren. Die hierfür nötigen Client erhalten Behörden und andere Abrufberechtigte, nach einer Anmeldung im Self-Service-Portal der FITKO. (TODO: link)
-Fachanwendungen haben die Möglichkeit FIT-Connect Anträge abzurufen. Dafür müssen sie sich mithilfe von oauth2 "Client-Credentials" authentifizieren. Diese erhalten Behörden und andere Abrufberechtigte, nach einer Anmeldung im Self-Service-Portal der FITKO. (TODO: link)
+Zum Abruf von Anträgen müssen sich antragsempfangende Systeme zunächst mithilfe der OAuth Client-Credentials beim OAuth-Server ein Berechtigungstoken (im Folgenden "Subscriber-Token") nach dem Standard JSON Web Token gemäß [RFC 7519](https://tools.ietf.org/html/rfc7519) abrufen. Dieser vom OAuth-Server signierte Subscriber-Token kann anschließend genutzt werden, um sich gegenüber der Antrags-API eines Zustelldienstes zu authentifizieren.
Für jede Destination müssen folgende Informationen im Self-Service-Portal bereitgestellt werden
Entweder:
-- Liste der [LeiKa-IDs](https://www.it-planungsrat.de/DE/Projekte/Anwendungen/LeiKaPlus/leiKaPlus.html) und [Amtlicher Gemeindeschlüssel](https://www.statistikportal.de/de/gemeindeverzeichnis)
+- Eine Liste der [LeiKa-IDs](https://www.it-planungsrat.de/DE/Projekte/Anwendungen/LeiKaPlus/leiKaPlus.html) und [Amtlicher Regionalschlüssel](https://www.dcat-ap.de/def/politicalGeocoding/regionalKey/)
Oder:
@@ -15,67 +16,75 @@ Oder:
Außerdem
- Der Public Key zur Verschlüsselung der Antragsdaten
-- Der Public Key der Fachanwendung zur Signaturprüfung
-- Callback Endpunkte
+- Der Public Key des antragsempfangenden Systems zur Signaturprüfung
+- Callback-Endpunkte des antragsempfangenden Systems
- Referenzen zu allen von diesem Endpunkt unterstützen Schemas
-Nach anlegen einer Destination erhält die Behörde, die für die Destination verantwortlich ist die OAuth Client Credentials. Mit diesen kann sich das Fachverfahren authentifizieren und erhält dafür einen JWT. Mit diesem JWT ist dann ein Abruf der hinterlegten Anträge möglich
-
-
+Bei erfolgreicher Registrierung erhält die für den Zustellpunkt verantwortliche Behörde OAuth2-Zugangsdaten für den Authentifizierungstyp "Client-Credentials" (`client_id` und `client_secret`). Mit diesen kann sich das antragsempfangende System beim Authentifizuerungsdienst authentifizieren und erhält einen Access Token im JSON Web Token-Format (JWT). Mit diesem Access Token ist anschließend ein Abruf der im Zustelldienst hinterlegten Anträge möglich.
<img src="../../assets/images/oauth/JWT-Konzept-Fachanwendung.png" alt="JWT Konzept" width="400"/>
-### Anforderung an die JWT-Tokens
-Die vom Auth Server generierten JWTs müssen nach [RFC 7519](https://tools.ietf.org/html/rfc7519) über folgende Attribute verfügen:
+## Zugriff auf die Antrags-API mittels Access Token
+Der Access Token für antragsempfangende Systeme muss beim Zugriff auf die Antrags-API via HTTP-Header an den Zustelldienst übermittelt werden.
-#### Header
+**Beispiel**
+```http
+POST /applications HTTP/1.1
+Host: api.zustelldienst-01.example.com
+Token: XXX
+```
-Entsprechend [RFC 7519 Abschnnitt 8](https://tools.ietf.org/html/rfc7519#section-8):
-| Feld | Inhalt | **Erläuterung** |
-| ---- | ------ | ----------------------------------------- |
-| typ | JWT | Es handelt sich um einen JWT. |
-| alg | PS512 | Der JWT verwendet RSASSA-PSS und SHA-512. |
+### Payload des Access Tokens für antragsempfangende Systeme
+Im Payload des signierten Access Token MÃœSSEN mindestens die folgenden [standartisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein:
-**Beispiel**
+| 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. 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) | *URL des Authentifizierungsservers* | Die URL des Authentifizierungsservers, der das Token ausgestellt hat. |
+| `sub` (Subject) | ID des antragsempfangenden Systems | Wird bei der Anmeldung des antragsempfangenden Systems durch den Authorisierungsdienst festgelegt und dient zur Identifizierung des antragsempfangenden 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 einen Abruf von Anträgen erlaubt (Präfix `destination:subscribe`), separiert mit Leerzeichen gemäß [RFC 6749, Abschnitt 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) |
+| `token_type` | `subscriber` | Gibt an, das es sich um einen Token für ein antragsempfangendes System handelt |
+**Beispiel-Payload eines Access Tokens mit Token-Typ `subscriber`**
```json
{
- "typ":"JWT",
- "alg":"PS512"
+ "iat": "1620072619",
+ "exp": "1620079819",
+ "iss": "https://auth.fit-connect.example.com",
+ "sub": "7e336be5-7528-4832-a1da-756229b72ab3",
+ "jti": "f2456e4b-121e-4900-a1ad-a83f720d7e2d",
+ "scope": "destination:subscribe:36141427-d405-40a4-8f8b-3592d544e85b destination:subscribe:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
+ "token_type": "subscriber"
}
```
-#### Body des Subscriber-JWT-Tokens
-Entsprechend den [standartisierten Feldern](http://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms):
+## 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:
-| 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 Zustellberechtigungs-Scopes | Eine Liste der Zustellberechtigungs-Scopes, für die der JWT einen Abruf erlaubt. |
-| clientType | subscriber | Gibt an, das es sich um einen Token für ein antragsempfangendes System (Fachanwendung oder virtuelle Poststelle) handelt. |
+| 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. |
**Beispiel**
-
```json
{
- "iat":"1620072619",
- "exp":"1620079819",
- "scope": ["destination:subscribe:36141427-d405-40a4-8f8b-3592d544e85b", "destination:subscribe:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1"],
- "clientType": "subscriber"
+ "typ": "JWT",
+ "alg": "PS512"
}
```
## Validierung der JWT-Tokens durch den Zustelldienst
-
Beim Abruf am Zustelldienst muss dieser bzw. das API-Gateway überprüfen, ob der JWT-Token valide ist. Dafür sollten mindestes folgende Überprüfungen durchgeführt werden:
1. Überprüfen, ob es sich um einen JWT mit einer **RSASSA-PSS (PS512)** Signatur handelt.
2. Überprüfen, ob der JWT noch gültig ist.
-3. Überprüfen, ob der JWT für max. 4h ausgestellt wurde.
-3. Mithilfe des Public Keys des Authentifizierungsservers die Signatur des JWT überprüfen.
-4. Überprüfen, ob die Destination-ID, die abgerufen werden soll, in den Zustellberechtigungs-Scopes des JWT enthalten ist (*scope* Parameter des JWT). (Zugangsberechtigung der Fachanwendung)
-
+3. Überprüfen, ob der JWT für max. 2h ausgestellt wurde.
+3. Mithilfe des Public Keys des Authentifizierungsservers überprüfen, ob die Signatur des JWT gültig ist.
+4. Überprüfen, ob die Destination-ID, die abgerufen werden soll, in den Zustellberechtigungs-Scopes des JWT enthalten ist (*scope* Parameter des JWT).