Skip to content
Snippets Groups Projects
Verified Commit 7553e529 authored by Jonas Gröger's avatar Jonas Gröger :palm_tree:
Browse files

Review

parent 5f2e331c
No related branches found
No related tags found
1 merge request!1Dokumentation der OAuth Changes
Hide whitespace changes
Inline Side-by-side
docs/details/authentication/scopes-sender.md
+ 9
− 16
View file @ 7553e529
# OAuth Berechtigungen für sendende Systeme
# OAuth-Scopes für sendende Systeme
Für den Zugriff auf die API des Zustelldienstes werden vom Autorisierungsserver Berechtigungen in Form von OAuth-Scopes
vergeben.
Sendende Systeme werden damit berechtigt Einreichungen vorzunehmen.
Für den Zugriff auf die API des Zustelldienstes werden vom Autorisierungsserver Berechtigungen in Form von OAuth-Scopes vergeben.
Sendende Systeme werden damit berechtigt, Einreichungen vorzunehmen.
## Zustellberechtigungs-Scopes
Die Zustellberechtigungs-Scopes erlauben dem Zustelldienst festzustellen, ob ein sendendes System eine Einreichung an
einen bestimmten Zustellpunkt übermitteln darf.
Zustellberechtigungs-Scopes werden im Self-Service-Portal bei der Registrierung von API-Clients festgelegt und sind
im [`scope`-Claim des Access Tokens](/details/infrastructure-docs/sender.md) hinterlegt.
Die Zustellberechtigungs-Scopes erlauben dem Zustelldienst festzustellen, ob ein sendendes System eine Einreichung an einen bestimmten Zustellpunkt übermitteln darf.
Zustellberechtigungs-Scopes werden im Self-Service-Portal bei der Registrierung von API-Clients festgelegt und sind im [`scope`-Claim des Access Tokens](/details/infrastructure-docs/sender.md) hinterlegt.
### Zusammensetzung der Zustellberechtigungs-Scopes
......@@ -76,26 +73,22 @@ Eine Liste der amtlichen Regionalschlüssel findet sich im [Gemeindeverzeichnis
send:region:DE081150045045
```
Werden nicht alle zwölf Stellen des ARS angegeben, sondern nur ein Prefix des ARS, so können statt einer spezifischen
Gemeinde auch darüberliegende Kreise, Regierungsbezirke oder Bundesländer abgebildet werden.
Werden nicht alle zwölf Stellen des ARS angegeben, sondern nur ein Prefix des ARS, so können statt einer spezifischen Gemeinde auch darüberliegende Kreise, Regierungsbezirke oder Bundesländer abgebildet werden.
Wird ein solcher Prefix eines ARS angegeben, schließt dieser alle sich darin befindlichen Gliederungen mit ein.
**Beispiel**: Dieser Schlüssel steht für alle Leistungen in der Region Stuttgart und schließt alle darunterliegenden
Landkreise, Städte und Gemeinden mit ein:
**Beispiel**: Dieser Schlüssel steht für alle Leistungen in der Region Stuttgart und schließt alle darunterliegenden Landkreise, Städte und Gemeinden mit ein:
```
send:region:DE0811
```
**Beispiel**: Der folgenden Schlüssel referenziert über die Angabe der ersten beiden Ziffern des ARS alle
Regierungsbezirke, Landkreise, Städte und Gemeinden im Bundesland Brandenburg:
**Beispiel**: Der folgenden Schlüssel referenziert über die Angabe der ersten beiden Ziffern des ARS alle Regierungsbezirke, Landkreise, Städte und Gemeinden im Bundesland Brandenburg:
```
send:region:DE12
```
**Beispiel**: Über die ausschließliche Angabe des Prefix `DE` können alle Gebietskörperschaften in Deutschland
referenziert werden:
**Beispiel**: Über die ausschließliche Angabe des Prefix `DE` können alle Gebietskörperschaften in Deutschland referenziert werden:
```
send:region:DE
......
docs/details/authentication/scopes-subscriber.md
+ 1
− 1
View file @ 7553e529
# OAuth Berechtigungen für empfangende Systeme
# OAuth-Scopes für empfangende Systeme
Für den Zugriff auf die API des Zustelldienstes werden vom Autorisierungsserver Berechtigungen in Form von OAuth-Scopes vergeben.
Empfangende Systeme werden damit berechtigt Einreichungen abzuholen.
......
docs/getting-started/authentication.mdx
+ 14
− 9
View file @ 7553e529
......@@ -6,11 +6,15 @@ import TabItem from '@theme/TabItem'
Nachfolgend wird der Abruf von Access Tokens beim OAuth-Dienst sowie der Zugriff auf die FIT-Connect API mittels Access Tokens beschrieben.
## Abruf von Access Tokens beim OAuth-Dienst
Fast alle Anfragen an die FIT-Connect API müssen authentifiziert werden. Hierfür ist ein Access Token – abzurufen vom Autorisierungsserver – notwendig. Die URL des Autorisierungsservers kann im Self Service Portal unter (TODO: Link / Klickstrecke einfügen) abgerufen werden.
Um einen Token abrufen zu können muss die die Software zunächst als API-Client registriert werden. Die Registrierung wird in "[Accountregistrierung](../account.md)" beschrieben.
Fast alle Anfragen an die FIT-Connect API müssen authentifiziert werden.
Hierfür ist ein Access Token notwendig, das beim OAuth-Dienst über die hierfür vorgesehene `Token URL` abgerufen werden kann (siehe Abschnitt `AUTHENTICATION` in der [Schnittstellenspezifikation](../../apis/delivery-service)).
Die URL des Autorisierungsservers kann im Self Service Portal unter (TODO: Link / Klickstrecke einfügen) abgerufen werden.
Für den Abruf von Access Tokens ist die [Konfiguration eines API-Client im Self-Service-Portal](../account.md) nötig.
Das Token kann anschließend bei Anfragen über den `Authentication` Header mitgeschickt werden. Da ein Token **max. 30 Minuten** gültig ist, muss dieses rechtzeitig erneuert werden.
Das Token kann anschließend bei Anfragen über den `Authentication` Header mitgeschickt werden.
Da ein Token **max. 30 Minuten** gültig ist, muss dieses rechtzeitig erneuert werden.
Wenn keine spezifischer Scope angefragt wird (siehe nächster Abschnitt), enthält der Access Token alle Scopes, die zu diesem Zeitpunkt beim Client im Self-Service-Portal hinterlegt wurden.
<Tabs
defaultValue="curl"
......@@ -68,8 +72,9 @@ $ curl \
### Abfrage von Access Tokens mit spezifischen Scopes
Es ist möglich den Scope des Access Tokens zu beschränken. Hier im Beispiel hat der angelegte OAuth Client weitreichende
Berechtigungen: `send:region:DE`. Wir beschränken allerdings diesen konkreten Access Token auf `send:region:DE01010`.
Es ist möglich den Scope des Access Tokens zu beschränken.
Hier im Beispiel hat der angelegte OAuth Client weitreichende Berechtigungen: `send:region:DE`.
Wir beschränken allerdings diesen konkreten Access Token auf `send:region:DE01010`.
```bash
$ export OAUTH_URL=<URL>
......@@ -87,8 +92,8 @@ $ curl \
}
```
Wie in der Anfrage zu erkennen ist, wurde der Token entsprechend beschränkt. Dies funktioniert nur wenn der angefragte
`scope` innerhalb der Berechtigungen des API-Clients liegen.
Wie in der Anfrage zu erkennen ist, wurde der Token entsprechend beschränkt.
Dies funktioniert nur wenn der angefragte `scope` innerhalb der Berechtigungen des API-Clients liegen.
Weiterführende Details zu den Scopes finden sich hier:
......@@ -97,8 +102,8 @@ Weiterführende Details zu den Scopes finden sich hier:
## Zugriff auf die API mittels Access Token
Access Tokens werden vom OAuth-Dienst erzeugt und DÜRFEN NIEMALS an dritte Systeme (mit Außnahme des Zustelldienstes zum Zwecke der Authentifizierung) weitergegeben werden. Beim Zugriff auf die Antrags-API wird muss ein Access Token im `Authorization`-Header mit `Bearer`
-Authentifizierungsschema gemäß [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) an den Zustelldienst übermittelt werden:
Access Tokens werden vom OAuth-Dienst erzeugt und DÜRFEN NIEMALS an dritte Systeme (mit Außnahme des Zustelldienstes zum Zwecke der Authentifizierung) weitergegeben werden.
Beim Zugriff auf die Antrags-API wird muss ein Access Token im `Authorization`-Header mit `Bearer`-Authentifizierungsschema gemäß [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) an den Zustelldienst übermittelt werden:
**Beispiel**
......
docs/getting-started/receiving/destination.mdx
+ 26
− 61
View file @ 7553e529
......@@ -9,7 +9,9 @@ import TabItem from '@theme/TabItem'
Um Einreichungen über FIT-Connect zu empfangen, muss zunächst ein Zustellpunkt angelegt werden. Dies wird über das Self-Service-Portal umgesetzt.
:::caution
In der finalen API wird eine explizite Aktivierung des Zustellpunkts (über die API oder das Self-Service-Portal) notwendig sein, damit sichergestellt werden kann, dass ein API-Client mit dem Scope `subscribe:destination:<id>` für diese destinationId angelegt und technisch empfangsbereit ist. Die Aktivierung eines Zustellpunkts wird voraussichtlich zum 06.08. in der API und dem Self-Service-Portal umgesetzt sein. Entsprechende organisatorische und technische Hinweise zu Aktivierung werden hier ergänzt.
In der finalen API wird eine explizite Aktivierung des Zustellpunkts (über die API oder das Self-Service-Portal) notwendig sein, damit sichergestellt werden kann, dass ein API-Client mit dem Scope `subscribe:destination:<id>` für diese destinationId angelegt und technisch empfangsbereit ist.
Die Aktivierung eines Zustellpunkts wird voraussichtlich zum 06.08. in der API und dem Self-Service-Portal umgesetzt sein.
Entsprechende organisatorische und technische Hinweise zu Aktivierung werden hier ergänzt.
:::
## Zustellpunkt anlegen
......@@ -20,16 +22,19 @@ In der finalen API wird eine Anlage der eines neuen Zustellpunkts nur über das
## Vorbereitende Tätigkeiten für die Aktivierung eines Zustellpunktes
Alle neu angelegten Zustellpunkte haben nach der Erstellung den Status `created` und sind für sendende Systeme nicht sichtbar und adressierbar. Hiermit soll verhindert werden, dass Einreichungen an den Zustellpunkt übersendet werden, ohne das ein empfangsbereites System vorliegt, dass die Einreichungen für diesen Zustellpunkt an der API abrufen kann.
Alle neu angelegten Zustellpunkte haben nach der Erstellung den Status `created` und sind für sendende Systeme nicht sichtbar und adressierbar.
Hiermit soll verhindert werden, dass Einreichungen an den Zustellpunkt übersendet werden, ohne das ein empfangsbereites System vorliegt, dass die Einreichungen für diesen Zustellpunkt an der API abrufen kann.
Daher ist zwingend vor der Aktivierung ein API-Client anzulegen, der einen subscribe scope für diesen Zustellpunkt (bspw. `subscribe:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1`) besitzt.
## Zustellpunkt bearbeiten und aktivieren
Sobald ein Zustellpunkt über das Self-Service-Portal erstellt wurde und eine destinationID für diesen Zustellpunkt vergeben und dem Nutzer zugeordnet wurde, kann entweder programmatisch über die API oder über das Self-Service-Portal bearbeitet werden. Für die programmatische Bearbeitung über die API sind folgende Voraussetzung zu erfüllen:
- Die Software für die Bearbeitung des Zustellpunkts muss als API-Client mit dem manage scope für den angelegten Zustelpunkt (bspw. manage:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1) registiert sein
Sobald ein Zustellpunkt über das Self-Service-Portal erstellt wurde und eine destinationID für diesen Zustellpunkt vergeben und dem Nutzer zugeordnet wurde, kann entweder programmatisch über die API oder über das Self-Service-Portal bearbeitet werden.
Für die programmatische Bearbeitung über die API sind folgende Voraussetzung zu erfüllen:
- Die Software für die Bearbeitung des Zustellpunkts muss als API-Client mit dem manage scope für den angelegten Zustellpunkt (bspw. manage:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1) registriert sein.
**TO-DO: Lösungsneutrale Beschreibung der im Zustellpunkt zu hinterlegenden Informationen**
**TO-DO: Bearbeitung über die API gemäß der API V.1 Spec überarbeiten**
<Tabs
......@@ -41,50 +46,6 @@ Sobald ein Zustellpunkt über das Self-Service-Portal erstellt wurde und eine de
}>
<TabItem value="curl">
Im Falle der Erstellung via API muss eine [HTTP POST Nachricht](../../apis/delivery-service#post-/destinations) an den Endpunkt des Zustellpunktes gesendet werden, der alle notwendigen Informationen beinhaltet.
Ein exemplarischer Inhalt ist unten abgebildet.
```json title="myDestination.json"
{
"contactInformation": {
"legalName": "Batman Ltd.",
"address": "Batmansq. 31, 10000 Berlin, DE",
"phone": "+49111111111",
"email": "max.mustermann@musterstadt.de",
"unit": "Referat Gotham"
},
"schemas": [
{
"schemaURI": "urn:xoev-de:xfall:standard:fim-s00000000009_1.0.0",
"mimeType": "application/xml"
}
],
"callback": "https://example.com/callback",
"encryptionKid": "my-key-id-0xfff",
"publicKeys": {
"keys": [
{
"kty": "RSA",
"kid": "my-key-id-0xfff",
"alg": "RSA-OAEP-256",
"key_ops": ["wrapKey"],
"x5c": [
"MIID2DCCAkmgAwIBAgIGAXo...w73tI1m1+QAU/6chTyAWvxvATklto2KV+i36lw=="
],
"e": "AQAB",
"n": "hwAvWxlwpz7sH...2f0u3Ktf1tzzeGTl4UVnUrE35eXF"
}
]
}
}
```
Wenn die JSON-Datei entsprechend befüllt ist und man ein [gültiges JWT](../authentication.mdx) hat, kann über den Befehl unten der Zustellpunkt angelegt werden.
:::note Hinweis
Soll ein Zustellpunkt nur aktualisiert werden, muss anstelle eines POST-Befehls ein [PUT-Befehl](../../apis/delivery-service.mdx#put-/destinations/-destinationId-) für den entsprechenden Zustellpunkt gesendet werden.
:::
```bash
$ export SERVICE_URL=...
$ export JWT_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA
......@@ -92,15 +53,27 @@ $ curl \
-H "Authentication: Bearer $JWT_TOKEN" \
-H "Content-Type: application/json" \
--data "@./myDestination.json" \
-X POST $SERVICE_URL/destionations
-X POST $SERVICE_URL/destinations
> {
"destinationId": "7881dba9-4055-4854-8b6d-11ea5b7f3047",
"schemas": [
"contactInformation": {
"legalName": "Batman Ltd.",
"address": "Batmansq. 31, 10000 Berlin, DE",
"phone": "+49111111111",
"email": "max.mustermann@musterstadt.de",
"unit": "Referat Gotham"
},
"services": [
{
"schemaURI": "urn:xoev-de:xfall:standard:fim-s00000000009_1.0.0",
"mimeType": "application/xml"
"identifier": "urn:xoev-de:xfall:standard:fim-s00000000009_1.0.0",
"schemas": [
"schemaUri": "https://schema.fitko.de/fim/s00000000009_1.0.0.schema.json",
"mimeType": "application/json"
],
"region": "DE13441111"
}
],
"callback": "https://example.com/callback",
"encryptionKid": "my-key-id-0xfff",
"publicKeys": {
"keys": [
......@@ -116,16 +89,8 @@ $ curl \
"n": "hwAvWxlwpz7sH...2f0u3Ktf1tzzeGTl4UVnUrE35eXF"
}
]
},
"contactInformation": {
"legalName": "Batman Ltd.",
"address": "Batmansq. 31, 10000 Berlin, DE",
"phone": "+49111111111",
"email": "max.mustermann@musterstadt.de",
"unit": "Referat Gotham"
},
"callback": "https://example.com/callback"
}
}
```
</TabItem>
......
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