Zum Hauptinhalt springen

OAuth-Scopes für sendende Systeme

Für den Zugriff auf die Submission API 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 hinterlegt.

Zusammensetzung der Zustellberechtigungs-Scopes​

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​

Scope: Leistung (innerhalb LeiKa)​

  • Typ: Leistungstyp innerhalb des LeiKa (LeiKa-Schlüssel)
  • Beispiel: send:service:urn:de:fim:leika:leistung:99108008252000
  • Erläuterung: Eine Leistung, die im Leistungskatalog der öffentlichen Verwaltung (LeiKa) verzeichnet ist, wird über ihren LeiKa-Schüssel, vorangestellt mit urn:de:fim:leika:leistung: referenziert. Der LeiKa ist im FIM-Portal 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. Reine Leistungsscopes werden nicht vergeben sondern sind immer mit einer Region gekoppelt.

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-Schlüssel. 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), vorangestellt mit DE.

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:

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. 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:

send:region:DE

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.

send:region:DE081150000000

Einschränkung: Leistung​

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 möglich.

Beispiel: Berechtigung für die LeiKa-Leistung "Begutachung von abgeschleppten Fahrzeugen" mit LeiKa-Schlüssel 99108008252000:

send:service:urn:de:fim:leika:leistung:99108008252000

Vor dem LeiKa-Schlüssel muss also der Präfix urn:de:fim:leika:leistung: stehen.

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). Hier wäre das:

send:region:DE+send:service:urn:de:fim:leika:leistung:99108008252000

Einschränkung: Region+Leistung​

Ü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" im Landkreis Böblingen:

send:region:DE08115+send:service:urn:de:fim:leika:leistung:99108008252000

Nutzung mehrerer Scopes im Scope Claim eines Access Tokens​

Der scope Claim des Access Tokens kann mehrere Zustellberechtigungs-Scopes – separiert mit Leerzeichen gemäß RFC 6749, Abschnitt 3.3 – enthalten. Diese sind unabhängig (oder-Verknüpfung) voneinander zu betrachten. Die parallele Nutzung aller Berechtigungsvarianten (Region und Leistung+Region) ist möglich. Das kann erfolgen, wenn z.B. zu einem Client mehrere unterschiedliche Berechtigungen hinterlegt sind oder ein Client bei der Tokenabfrage explizit bestimmte Scopes abfragt.

Beispiel: Ein Client hat die Scopes send:region:DE12 hinterlegt und könnte somit an alle Zustellpunkte in Brandenburg (12) senden. Die Token-Abfrage geschieht allerdings mit dem Scope eines Landkreises: send:region:DE124412. Da sich dieser Landkreis innerhalb von Brandenburg befindet, erhält der Client einen Token mit dem Token des Landkreises. Dies ist aus Sicherheitsperspektive einreichungsspezifisch zu bevorzugen ("Prinzip der geringsten Privilegien").

Ein sendendes System ist daher zur Einreichung bei allen Zustellpunkten berechtigt, auf die mindestens einer der Scopes zutrifft.

Beispiel: Mit diesem Zustellberechtigungs-Scope kann ein sendendes System Einreichungen für alle Leistungen im Landkreis Böblingen, als auch die Leistung "Begutachung von abgeschleppten Fahrzeugen" im Bundesland Brandenburg vornehmen:

send:region:DE08115 send:region:DE12+send:service:urn:de:fim:leika:leistung::99108008252000