Merge branch 'pr-oauth-scopes' into 'main'

Überarbeitung der Dokumentation zu OAuth-Scopes

See merge request fit-connect/api!58

docs/details/authentication/scopes.md

-# Zustellberechtigungs-Scope
+# OAuth-Scopes
 
-Die Zustellberechtigungs-Scopes erlauben dem Zustelldienst festzustellen, ob ein dort eingesendeter Einreichung vom Versender an eine Destination übermittelt werden darf.
+Für den Zugriff auf die Zustelldienst-Schnittstellen werden vom Authorisierungsserver Berechtigungen in Form von OAuth-Scopes vergeben, die sendende Systeme zur Antragseinreichung und empfangende Systeme zur Abholung von Einreichungen berechtigen.
 
-## Zusammensetzung der Zustellberechtigungs-Scopes
+## Berechtigungen für sendende Systeme (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 der [Berechtigungs-Tokens für sendende Systeme](./sender.md) hinterlegt.
 
-Der Zustellberechtigungsscope kann entweder eine Destination-ID oder alternativ eine spzifische Art der Leistung, eine bestimmte Region oder eine Kombination aus Region und Leistung enthalten. Die Angabe im Scope beschränkt Zugriffe auf die angegeben Zustellpunkte, Leistungen oder Regionen. 
+### Zusammensetzung der Zustellberechtigungs-Scopes
+Der Zustellberechtigungs-Scope kann die Angabe einer konkrete Destination-ID, einer bestimmte Region oder einer Kombination aus Region und Leistungstyp enthalten. Die Angabe im Scope beschränkt Zugriffe auf die angegeben Zustellpunkte, Leistungen oder Regionen.
 
-Ein Zustellberechtigungs-Scope kann den folgenden Typen entsprechen:
+Ein Zustellberechtigungs-Scope kann aus den folgenden Bestandteilen bestehen:
 
-| Type           | Beispiel                                         | Erläuterung                                                  |
-| -------------- | ------------------------------------------------ | ------------------------------------------------------------ |
-| destination    | destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1 | Die UUID einer in FIT-Connenct angelegten Destination.       |
-| leika          | leika:99108008252000                             | LeiKa steht dafür, das die folgende ID einer Leistung im [Leistungskatalog der öffentlichen Verwaltung](https://leitfaden.ozg-umsetzung.de/display/OZG/2.1+Verwaltungsleistungen+im+Sinne+des+OZG) verzeichnet ist. |
-| region         | region:08110000                                  | Region steht für einen [Amtlichen Gemeindeschlüssel](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel) |
-| region-leika   | region:08110000+leika:99108008252000             | Eine Kombination aus einem amtlichen Gemeindeschlüssel und einer LeiKa-ID. Hier erfolgt eine Einschränkung nach beiden angegeben Kriterien (Zugriff nur auf spezifische Leistung in der angegebenen Region). |
-| custom-service | custom-service:42                                | Eine Leistung, die nicht im Leistungskatalog abgebildet wird. |
+| Typ                                     | Beispielwert                                            | Erläuterung |
+| --------------------------------------- | ------------------------------------------------------- | ----------- |
+| Konkreter Zustellpunkt                  | `send:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1` | Die Angabe einer eindeutige Destination-ID eines Zustellpunktes schränkt Zugriffe auf einen einzelnen Zustellpunkt ein. |
+| Geographische Zuordnung                 | `send:region:DE081150045045`                            | 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), geprefixed mit dem Wert `DE`. Siehe auch: [Gemeindeverzeichnis des Statistischen Bundesamtes](https://www.destatis.de/DE/Themen/Laender-Regionen/Regionales/Gemeindeverzeichnis/_inhalt.html) |
+| LeiKa-ID                                | `send:servicetype-leika:99108008252000`                 | 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 referenziert. Der LeiKa ist im [FIM-Portal](https://fimportal.de/kataloge#download-leistungen) abrufbar. |
+| Leistungstyp außerhalb des LeiKa        | `send:servicetype-custom:42`                            | Eine Leistung, die nicht im Leistungskatalog abgebildet ist, kann übergangsweise über eine andere Leistungs-ID referenziert werden. Diese ID muss eindeutig sein. |
+| Kombination aus Leistungstyp und Region | `send:region:DE081100000000+send:servicetype-leika:99108008252000` oder `send:region:DE081100000000+send:servicetype-custom:42` | 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). |
 
-## Beispiele
-Beschränkung auf eine spezifische Destination:
+### Einschränkung der Berechtigung auf einzelne Zustellpunkte
+Im einfachsten Fall ist ein sendendes System zur Einreichung bei genau einem konkreten Zustellpunkt berechtigt:
 
+**Beispiel**: Beschränkung auf einen spezifischen Zustellpunkt:
 ```
-destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1
+send:destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1
 ```
 
-Bei den Destinationen kann zusätzlich der Scope **destination:create** (erstellen der Destination) , **destination:manage** (verwalten der Destination) und **destination:subscribe** (subscriben auf Webhooks) vergeben werden.
+### Einschränkung der Berechtigung auf Leistungstypen
+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. 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)“:
 ```
-destination:manage:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1
+send:servicetype-leika:99108008252000
 ```
 
-LeiKa-Leistung für die [Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000):
 
+### Einschränkung der Berechtigung auf bestimmte Regionen
+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), geprefixed mit dem Wert `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.
+
+**Beispiel**: Mit der Angabe des zwölfstelligen ARS kann die Stadt Sindelfingen eindeutig adressiert werden:
 ```
-leika:99108008252000
+send:region:DE081150045045
 ```
 
-Wenn ein Prefix für einen AGS angegeben wird, schließt dieser alle sich darin befindlichen Subentitäten mit ein. Dieser Schlüssel steht für alle Leistungen in der Region Stuttgart und schließt alle darunterliegenden Gemeinden, Stadtteile, etc. mit ein:
+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:
+```
+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:
+```
+send:region:DE12
+```
 
+**Beispiel**: Über die ausschließliche Angabe des Prefix `DE` können alle Gebietskörperschaften in Deutschland referenziert werden:
 ```
-region:08110000
+send:region:DE
 ```
 
-Die LeiKa-Leistung für die [Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000) in der Region Stuttgart:
+Eine Einschränkung auf konkrete Verwaltungsebenen ist durch das Auffüllen des ARS auf zwölf Stellen mit Nullen möglich.
 
+**Beispiel**: Der folgende Schlüssel referenziert explizit nur den Kreis Böblingen, nicht jedoch beispielsweise die Stadt Leonberg, die im Kreis Böblingen liegt. Hierdurch ist eine Einschränkung auf Zustellpunkte möglich, die von der Kreisverwaltung Böblingen betrieben werden, ohne eine Berechtigung für Zustellpunkte der Stadt Leonberg zu gewähren.
 ```
-region:08110000+leika:99108008252000
+send:region:DE081150000000
 ```
 
-## Kombination verschiedener Berechtigungen
 
-Wenn eine Liste von Zustellberechtigungsscopes angegeben wird, sind diese immer unabhängig voneinander zu betrachten. Im folgenden Fall werden sowohl alle Leistungen in der Region Stuttgart als auch die Leistung [Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000) in Brandenburg freigegeben:
+### Kombination von Regionen und Leistungstypen
+Ü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.
 
-```json
-["region:08110000", "region:12000000+leika:99108008252000"]
+**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:
+```
+send:region:DE08115+send:servicetype-leika:99108008252000
 ```
 
-## Regex zur Validierung
+### Erteilung mehrere unabhängiger Zustellberechtigungen
+In den [Berechtigungs-Tokens für sendende Systeme](./sender.md) kann eine Liste von Zustellberechtigungs-Scopes, separiert mit Leerzeichen gemäß [RFC 6749, Abschnitt 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3), angegeben werden. Wenn eine Liste von Zustellberechtigungs-Scopes angegeben wird, sind diese immer unabhängig voneinander zu betrachten. Ein sendendes System ist in diesem Fall zur Einreichung bei allen Zustellpunkten berechtigt, die von mindestens einem der angegebenen Zustellberechtigungs-Scopes referenziert werden.
 
+**Beispiel**: Im folgenden Beispiel werden sowohl alle Leistungen im Landkreis Böblingen, als auch die Leistung „[Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000)“ im Bundesland Brandenburg freigegeben:
 ```
-(leika:[0-9]{1,12})|(region:[0-9]{1,12})|(custom-service:[0-9]{1,12})|(destination(:create|:manage|:subscribe)?:[0-9A-F]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89AB][0-9a-f]{3}-[0-9a-f]{12})
+send:region:DE08115 send:region:DE12+send:servicetype-leika:99108008252000
+```
+
+## Berechtigungen für empfangende Systeme
+Berechtigungen für empfangende Systeme geben an, ob ein empfangendes System Einreichungen eines bestimmten Zustellpunktes abrufen darf. 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.
+
+| 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 von Einreichungen für einen über eine Destination-ID eindeutig referenzierten Zustellpunkt 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. |
+
+## Weitere technische Zustellberechtigungen
+| Typ | Beispielwert | Erläuterung |
+| --- | ------------ | ----------- |
+| Erstellen von Zustellpunkten | `create:destination` | Mit dieser Berechtigung ist das Erstellen von neuen Zustellpunkten bei einem Zustelldienst möglich. Diese Berechtigung wird aktuell nur intern für die Erstellung von Zustellpunkten durch den Authorisierungsdienst genutzt. |
+
+## Regex zur Validierung der OAuth-Scopes
+Der folgende reguläre Ausdruck erfasst alle möglichen OAuth-Scopes:
+```regex
+(subscribe|manage|send):destination:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|send:((region:DE[0-9]{0,12}\+(send:servicetype-leika:[0-9]{1,14}|send:servicetype-custom:\w+))|region:DE[0-9]{0,12})|create:destination
 ```
 
+**Hinweis**: Eine Einschränkung auf bestimmte Leistungstypen erfolgt im Authorisierungsdienst *immer* in Kombination mit der Einschränkung auf eine geographische Zuordnung. Um ein sendendes System zur Einreichung bei allen existierenden Zustellpunkten eines Leistungstyps zu berechtigen, wird hierbei der Schlüssel `send:region:DE` genutzt.