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.
Empfangende Systeme werden damit berechtigt Einreichungen abzuholen.
## Zustellberechtigungs-Scopes
...
...
@@ -14,40 +13,51 @@ im [`scope`-Claim des Access Tokens](/details/infrastructure-docs/sender.md) hin
### Zusammensetzung der Zustellberechtigungs-Scopes
Der Zustellberechtigungs-Scope kann eine beliebige Anzahl an Regionen oder eine Kombination aus Region und Leistungstyp
enthalten:
Der Zustellberechtigungs-Scope kann eine beliebige Anzahl an Regionen oder eine Kombination aus Region und Leistungen enthalten.
Scopes für sendende Systeme bestehen aus drei mit `:` getrennten Teilen:
-`send`
-`region` oder `service`
- Bei `region`: Einschränkung nach Region. Bei `service`: Einschränkung nach Service.
Im folgenden eine Beschreibung der einzelnen Varianten:
#### Scope: Region
-**Typ**: Geographische Zuordnung
-**Beispiel**: `send:region:DE081150045045`
-**Erläuterung**: Eine geographische Zuordnung zu einem Bundesland, Landkreis, einer Gemeinde etc. erfolgt über den [Amtlichen Regionalschlüssel](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel#Regionalschl%C3%BCssel), vorangestellt mit `DE`. Siehe auch: [Gemeindeverzeichnis des Statistischen Bundesamtes](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html)
-**Erläuterung**: Eine geographische Zuordnung zu einem Bundesland, Landkreis, einer Gemeinde etc. erfolgt über den [Amtlichen Regionalschlüssel](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel#Regionalschl%C3%BCssel), vorangestellt mit `DE`.
Siehe auch: [Gemeindeverzeichnis des Statistischen Bundesamtes](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html)
#### Scope: Leistung (innerhalb LeiKa)
-**Typ**: Leistungstyp innerhalb des LeiKa (LeiKa-ID)
-**Erläuterung**: Eine Leistung, die im [Leistungskatalog der öffentlichen Verwaltung](https://leitfaden.ozg-umsetzung.de/display/OZG/2.1+Verwaltungsleistungen+im+Sinne+des+OZG)(LeiKa) verzeichnet ist, wird über ihre LeiKa-ID, vorangestellt mit `urn:de:fim:leika:leistung:` referenziert. Der LeiKa ist im [FIM-Portal](https://fimportal.de/kataloge#download-leistungen) abrufbar.
-**Erläuterung**: Eine Leistung, die im [Leistungskatalog der öffentlichen Verwaltung](https://leitfaden.ozg-umsetzung.de/display/OZG/2.1+Verwaltungsleistungen+im+Sinne+des+OZG)(LeiKa) verzeichnet ist, wird über ihre LeiKa-ID, vorangestellt mit `urn:de:fim:leika:leistung:` referenziert.
Der LeiKa ist im [FIM-Portal](https://fimportal.de/kataloge#download-leistungen) abrufbar.
#### Scope: Leistung (außerhalb LeiKa)
-**Typ**: Leistungstyp außerhalb des LeiKa
-**Beispiel**: `send:service:urn:myleistung`
-**Erläuterung**: Eine Leistung, die nicht im Leistungskatalog abgebildet ist, kann übergangsweise über eine andere Leistungs-ID referenziert werden. Diese ID muss eindeutig sein.
-**Erläuterung**: Eine Leistung, die nicht im Leistungskatalog abgebildet ist, kann übergangsweise über eine andere Leistungs-ID referenziert werden.
Diese ID muss eindeutig sein.
Reine Leistungsscopes werden nicht vergeben sondern sind immer mit einer Region gekoppelt.
#### Scope: Kombination Region/Leistung
#### Scope: Kombination Region / Leistung
-**Typ**: Kombination aus Leistungstyp und Region
-**Beispiel**: `send:region:DE081100000000+send:service:urn:de:fim:leika:leistung:99108008252000` oder `send:region:DE081100000000+send:service:urn:myleistung`
-**Erläuterung**: Eine Kombination aus amtlichem Gemeindeschlüssel und LeiKa-ID. Hier erfolgt eine Einschränkung nach beiden angegeben Kriterien (Zugriff nur auf spezifische Leistung in der angegebenen Region).
-**Erläuterung**: Eine Kombination aus amtlichem Gemeindeschlüssel und LeiKa-ID.
Hier erfolgt eine Einschränkung nach beiden angegeben Kriterien (Zugriff nur auf spezifische Leistung in der angegebenen Region).
Reine Leistungsscopes werden nicht vergeben sondern sind immer mit einer Region gekoppelt.
### Einschränkung: Region
Eine Einschränkung der Berechtigung für bestimmte Regionen erfolgt auf Basis des zwölfstelligen [Amtlichen Regionalschlüssels (ARS)](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel#Regionalschl%C3%BCssel), vorangestellt mit `DE`.
Eine Liste der amtlichen Regionalschlüssel findet sich im [Gemeindeverzeichnis des Statistischen Bundesamtes](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html) sowie im [XRepository](https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:rs).
**Hinweis**: Ohne zusätzliche Einschränkung auf einen Leistungstyp ist ein Zustellberechtigungs-Scope für alle
Leistungstypen in der angegebenen Region gültig.
**Hinweis**: Ohne zusätzliche Einschränkung auf eine Leistung ist ein Zustellberechtigungs-Scope für alle Leistungen in der angegebenen Region gültig.
**Beispiel**: Mit der Angabe des zwölfstelligen ARS kann die Stadt Sindelfingen eindeutig adressiert werden:
...
...
@@ -89,31 +99,29 @@ Hierdurch ist eine Einschränkung auf Zustellpunkte möglich, die von der Kreisv
send:region:DE081150000000
```
### Einschränkung: Leistungstypen
### Einschränkung: Leistung
Um sendende Systeme zur Einreichung bei allen Zustellpunkten eines bestimmten Leistungstyps zu berechtigen, ist eine
Vergabe von Berechtigungen auf Basis von Leistungs-IDs möglich.
Um sendende Systeme zur Einreichung bei allen Zustellpunkten mit einer bestimmten Leistung zu berechtigen, ist eine Vergabe von Berechtigungen auf Basis von Leistungs-IDs möglich.
Ein Download des Leistungskatalogs mit allen LeiKa-Schlüsseln ist [über das FIM-Portal](https://fimportal.de/kataloge#download-leistungen) möglich.
**Beispiel**: Berechtigung für die LeiKa-Leistung
"[Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000)":
**Beispiel**: Berechtigung für die LeiKa-Leistung "[Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000)":
**Hinweis**: Eine Einschränkung auf bestimmte Leistungstypen erfolgt im Autorisierungsserver **immer** kombiniert mit einer geographische Zuordnung.
Um ein sendendes System zur Einreichung bei allen existierenden Zustellpunkten eines Leistungstyps zu berechtigen wird der Schlüssel `send:region:DE` genutzt (siehe nächster Abschnitt).
**Hinweis**: Reine Leistungsscopes werden nicht vergeben sondern sind **immer** mit einer Region gekoppelt.
Um ein sendendes System zur Einreichung bei allen existierenden Zustellpunkten unabhängig der Leistung zu berechtigen wird der Schlüssel `send:region:DE` genutzt (siehe nächster Abschnitt).
Über die Kombination einer geographischen Zuordnung mit einem Leistungstyp über das Plus-Symbol (`+`) ist eine Einschränkung auf Verwaltungsleistungen in einer bestimmten Region möglich.
Hierbei wird immer zuerst ("vor dem `+`") eine Einschränkung nach der Region und dann ("nach dem `+`") eine Einschränkung nach dem Leistungstyp vorgenommen.
Über die Kombination einer geographischen Zuordnung mit einer Leistung über das Plus-Symbol (`+`) ist eine Einschränkung auf Verwaltungsleistungen in einer bestimmten Region möglich.
Hierbei wird immer zuerst ("vor dem `+`") eine Einschränkung nach der Region und dann ("nach dem `+`") eine Einschränkung nach Leistung vorgenommen.
**Beispiel**: Der folgende Zustellberechtigungs-Scope berechtigt zur Einreichung für die LeiKa-Leistung "[Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000)" im Landkreis Böblingen:
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. Empfangende Systeme werden damit
berechtigt Einreichungen abzuholen.
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.
Typischerweise existiert für einen Zustellpunkt genau ein empfangsberechtigtes System (z.B. ein Fachverfahren oder eine
virtuelle Poststelle). Berechtigungen für empfangende Systeme werden beim Anlegen eines Zustellpunktes im
Self-Service-Portal vergeben.
Typischerweise existiert für einen Zustellpunkt genau ein empfangsberechtigtes System (z.B. ein Fachverfahren oder eine virtuelle Poststelle).
Berechtigungen für empfangende Systeme werden beim Anlegen eines Zustellpunktes im Self-Service-Portal vergeben.
Die Erstellung von Zustellpunkten ist [nur durch das Self-Service-Portal möglich](/details/infrastructure-docs/scopes-internal.md).
| Typ | Beispielwert | Erläuterung |
| --- | ------------ | ----------- |
| Empfangsberechtigung für einen Zustellpunkt | `subscribe:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1` | Mit dieser Berechtigung ist ein Abruf von Einreichungen sowie das Schreiben des Event Logs einer Einreichung beim referenzierten Zustellpunkt (destination) möglich. |
| Verwalten eines Zustellpunktes | `manage:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1` | Mit dieser Berechtigung ist die Änderung der in einem Zustellpunkt hinterlegten Daten (z.B. Antragsdaten-Schemata) möglich. |
## Zusammensetzung der Zustellberechtigungs-Scopes
Scopes für empfangende Systeme bestehen aus drei mit `:` getrennten Teilen:
-`subscribe` oder `manage`
-`destination`
- Der eindeutigen ID eines Zustellpunktes (destination id)
### Scope: Empfangsberechtigung für einen Zustellpunkt
-**Erläuterung**: Mit dieser Berechtigung ist ein Abruf von Einreichungen sowie das Schreiben des Event Logs einer Einreichung beim referenzierten Zustellpunkt (destination) möglich.
