Skip to content
Snippets Groups Projects
Commit 9c5eaae2 authored by Marco Holz's avatar Marco Holz
Browse files

Use Proof-of-Possession-Tokens for OAuth-Authentication

parent 3be3cc44
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
docs/details/authentication/cli.md
+ 1
− 1
View file @ 9c5eaae2
......@@ -122,7 +122,7 @@ Wenn ein JWT zum Abrufen von Einreichungen generiert werden soll, kann auf den P
$ fitconnect get_jwt receiver-config.json
```
Als Antwort erhält man einen (vom Authentifizierungsserver via OAuth2 Client Credentials Flow abgerufenen) JWT, welchen man zur Authentifizierung beim Abrufen von Einreichungen verwenden kann.
Als Antwort erhält man einen (vom Autorisierungsserver via OAuth2 Client Credentials Flow abgerufenen) JWT, welchen man zur Authentifizierung beim Abrufen von Einreichungen verwenden kann.
```bash
$ curl -i \
......
docs/details/authentication/sender.md
+ 112
− 110
View file @ 9c5eaae2
This diff is collapsed.
docs/details/authentication/subscriber.md
+ 31
− 38
View file @ 9c5eaae2
# Authentifizierung von empfangenden Systemen
Die Authentifizierung von empfangenden 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 empfangende 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)
Die Authentifizierung von empfangenden 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 empfangende Systeme mit Hilfe von OAuth 2.0 Client-Credentials beim Autorisierungsdienst authentifizieren. Die hierfür nötigen Client 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 empfangende 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.
Zum Abruf von Anträgen müssen sich empfangende Systeme zunächst mithilfe der OAuth Client-Credentials beim OAuth-Server ein Berechtigungstoken (im Folgenden "Access Token") nach dem Standard JSON Web Token gemäß [RFC 7519](https://tools.ietf.org/html/rfc7519) abrufen. Dieser vom OAuth-Server signierte 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
......@@ -12,7 +12,7 @@ Entweder:
Oder:
- Name und Bezeichung der angeboteten Leistungen, wenn diese nicht Teil des Leistungskataloges sind
- Name und Bezeichnung der angebotenen Leistungen, wenn diese nicht Teil des Leistungskataloges sind
Außerdem
......@@ -27,33 +27,46 @@ Bei erfolgreicher Registrierung erhält die für den Zustellpunkt verantwortlich
## Zugriff auf die Antrags-API mittels Access Token
Der Access Token für empfangende Systeme muss beim Zugriff auf die Antrags-API via HTTP-Header an den Zustelldienst übermittelt werden.
Der Access Token für empfangende Systeme muss beim Zugriff auf die Antrags-API im `Authorization`-Header mit `Bearer`-Authentifizierungsschema gemäß [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) an den Zustelldienst übermittelt:
**Beispiel**
```http
POST /applications HTTP/1.1
Host: api.zustelldienst-01.example.com
Token: XXX
Authorization: Bearer ey...
```
### Payload des Access Tokens für empfangende Systeme
### Header des Access Tokens für empfangende Systeme
Im Header des Access Tokens für empfangende Systeme werden vom Autorisierungsdienst gemäß den Vorgaben aus [RFC 7519](https://tools.ietf.org/html/rfc7519) die folgende Header-Attribute gesetzt:
| 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
{
"typ": "JWT",
"alg": "PS512"
}
```
Im Payload des signierten Access Token MÜSSEN mindestens die folgenden [standartisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein:
### Payload des Access Tokens für empfangende Systeme
Im Payload des signierten Access Token MÜSSEN mindestens die folgenden [standardisierten Felder](https://www.iana.org/assignments/jwt/jwt.xhtml) gesetzt sein:
| 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 empfangenden Systems | Wird bei der Anmeldung des empfangenden Systems durch den Authorisierungsdienst festgelegt und dient zur Identifizierung des empfangenden Systems. |
| `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 Autorisierungsservers* | Die URL des Autorisierungsservers, der das Token ausgestellt hat. |
| `sub` (Subject) | *ID des empfangenden Systems* | Wird bei der Anmeldung des empfangenden Systems durch den Autorisierungsdienst festgelegt und dient zur Identifizierung des empfangenden Systems. |
| `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` | *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 empfangendes System handelt |
| `token_type` | `subscriber` | Gibt an, das es sich um einen Token für ein empfangendes System handelt. |
**Beispiel-Payload eines Access Tokens mit Token-Typ `subscriber`**
```json
{
"iat": "1620072619",
......@@ -61,37 +74,17 @@ Im Payload des signierten Access Token MÜSSEN mindestens die folgenden [standar
"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",
"aud": "https://api.zustelldienst-01.example.com",
"scope": "subscribe:destination:36141427-d405-40a4-8f8b-3592d544e85b manage:destination:36141427-d405-40a4-8f8b-3592d544e85b",
"token_type": "subscriber"
}
```
## 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** |
| ----- | ------- | --------------- |
| `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
{
"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:
Beim Abruf am Zustelldienst muss dieser bzw. das API-Gateway überprüfen, ob der JWT-Token valide ist. Dafür sollten mindestens 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. 2h ausgestellt wurde.
4. Mithilfe des Public Keys des Authentifizierungsservers überprüfen, ob die Signatur des JWT gültig ist.
4. Mithilfe des Public Keys des Autorisierungsservers überprüfen, ob die Signatur des JWT gültig ist.
5. Überprüfen, ob die Destination-ID, die abgerufen werden soll, in den Zustellberechtigungs-Scopes des JWT enthalten ist (*scope* Parameter des JWT).
docs/details/encryption.mdx
+ 8
− 0
View file @ 9c5eaae2
......@@ -356,3 +356,11 @@ Die folgenden Attribute müssen im JOSE-Header bei der Übertragung signierter D
| alg | "PS512" | Legt RSASSA-PSS mit SHA512 als Algorithmus für die Signatur fest. Bezeichner gemäß [RFC 7518, Abschnitt 3.5](https://tools.ietf.org/html/rfc7518.html#section-3.5) |
| kid | *ID des Public Keys* | Die ID des JSON Web Keys mit dem Attribute "verify" aus dem von der Subscriber-API bereitgestellten Keysets, der zur Verifizierung der Signatur dient. Gemäß [RFC7515, Abschnitt 4.1.4](https://tools.ietf.org/html/rfc7515#section-4.1.4). |
| cty | *MIME-Type der Inhaltsdaten* | MIME-Type der Inhaltsdaten (Fachdaten, Medatadaten) nach [RFC 7515, Abschnitt 4.1.10](https://tools.ietf.org/html/rfc7515#section-4.1.10) |
## Vorgaben für JSON Web Tokens (JWTs)
Alle generierten JWT-Tokens MÜSSEN den Vorgaben aus [RFC 7519](https://tools.ietf.org/html/rfc7519) entsprechen und über folgende Header-Attribute verfügen:
| Feld | Inhalt | **Erläuterung** |
| ----- | ------- | --------------- |
| `alg` | `PS512` | Zur Signaturerstellung wird der Signaturalgorithmus RSASSA-PSS mit SHA-512 und MGF1 mit SHA-512 verwendet. |
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment