Authentifizierung_von_antragssendenden_Systemen.md

Authentifizierung von antragssendenden Systemen

Treten die Schlüsselwörter "MUSS"/"MÜSSEN", "DARF NICHT"/"DÜRFEN NICHT", "SOLLTE"/"SOLLTEN", "SOLLTE NICHT"/"SOLLTEN NICHT" und "KANN"/"KÖNNEN" in Großbuchstaben auf, handelt es sich um Implementierungsvorgaben, die entsprechen den Begriffen "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" und "MAY" gemäß RFC 2119 zu interpretieren sind.

Die Authentifizierung von antragssendenden Systemen erfolgt bei FIT-Connect auf Basis von OAuth 2.0 Client Credentials gemäß RFC 6749 und Access Tokens auf Basis von JSON Web Tokens gemäß RFC 7519. Im Folgenden sollen die nötigen Schritte zur Registrierung und zum Zugriff auf die Schnittstelle des FIT-Connect Zustelldienstes beschrieben werden. Dieses Dokument dokumentiert die implementierten Authentifizierungsmechanismen und macht Vorgaben zur Implementierung der Authentifizierung von antragssendenden Systemen. Bei der Umsetzung der Authentifizierung kann darüber hinaus auf das vom Projekt FIT-Connect bereitgestellte Software Development Kit (SDK) zurückgegriffen werden, dass die Vorgaben aus diesem Dokument umsetzt bzw. bei deren Umsetzung unterstützt.

Schritt 1: Registrierung

Jedes antragssendende System (z.B. ein Online-Antragsservice) muss bei FIT-Connect als API-Client registriert sein, um über FIT-Connect Anträge einreichen zu können. Bei der Registrierung eines antragssendenden Systems wird festgelegt, welche Anträge das System über welche Domains ausspielen darf. Vor der Registrierung eines antragssendenden Systems muss zunächst ein kryptographisches Schlüsselpaar durch das antragssendende System erzeugt werden (im Folgenden: Onlineservice-Schlüsselpaar). Der öffentliche Schlüssel (Public Key) dieses Schlüsselpaares wird anschließend bei der Registrierung im Self-Service-Portal hinterlegt. Zur Generierung des Schlüsselpaares kann auf das bereitgestellte Kommandozeilentool zurückgegriffen werden. Bei erfolgreicher Registrierung erhält jedes antragssendende System OAuth2-Zugangsdaten für den Authentifizierungstyp "Client-Credentials" (client_id und client_secret).

Bei der Registrierung eines antragssendenden Systems als API-Client über das Self-Service-Portal müssen die folgenden Informationen hinterlegt werden:

• Freigegebene Domains, von denen der Online-Antragsservice Formulare übermittelt
• Eine Liste an Zustellberechtigungs-Scopes, die definiert, an welche Zustellpunkte Anträge durch den registrierten API-Client übermittelt werden dürfen.
• Der Public Key des Onlineservice-Schlüsselpaar

Schritt 2: Ausstellung von Berchtigungstokens für Onlineservices (Onlineservice-Token)

Wenn ein Online-Antragsservice einer Antragsteller:in ermöglichen möchte, einen Antrag an die FIT-Connect Antrags-API zu übermitteln, muss dieser zunächst mithilfe der OAuth Client-Credentials beim OAuth-Server ein Berechtigungstoken (im Folgenden "Onlineservice-Token") nach dem Standard JSON Web Token gemäß RFC 7519) abrufen. Dieser vom OAuth-Server signierte Onlineservice-Token enthält den Public-Key des Online-Antragsdienstes, der bei der Registrierung im Self-Service-Portal festgelegt wurde. Aus Sicht von API-Clients (antragssendende und -empfangende Systeme) sind die Inhalte dieses Tokens gemäß OAuth-Spezifikation als bedeutungslos anzusehen und SOLLTEN daher NICHT interpretiert werden. Eine Prüfung des Onlineservice-Token auf Korrektkeit und Gültigkeit erfolgt ausschließlich durch den Zustelldienst.

Payload des Onlineservice-Tokens

Der hier beschriebene Payload des Onlineservice-Tokens dient lediglich der Dokumentation/Spezifikation. Antragssendende Systeme müssen den Payload des Tokens nicht auswerten oder interpretiern können. Im Payload des signierten Onlineservice-Token werden vom Authorisierungsdienst die folgenden standartisierten Felder gesetzt:

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. 24 Stunden gültig sein; vgl. BSI APP.3.1)
iss (Issuer)	URL des Authentifizierungsservers	Die URL des Authentifizierungsservers, der das Token ausgestellt hat.
sub (Subject)	ID des Onlineservice	Wird bei der Registrierung des Online-Antragsdienstes im Self-Service-Portal durch den Autorisierungsdienst festgelegt und dient zur Identifizierung des antragssendenden Systems
jti (JWT ID)	UUID des Tokens	Eindeutige ID des ausgestellten Tokens.
scope	Liste von Zustellberechtigungs-Scopes	Eine Liste der Zustellberechtigungs-Scopes, für die der Token eine Übermittlung erlaubt, separiert mit Leerzeichen gemäß RFC 6749, Abschnitt 3.3. Die jeweiligen Zustellberechtigungs-Scopes werden im Self-Service-Portal bei der Registrierung des API-Client festgelegt.
domains	Liste von Domains	Eine Liste der Domains, von denen der Onlineservice Anträge übermitteln kann, separiert mit Leerzeichen (Subdomains müssen explizit aufgeführt werden)
publicKey	Public Key des Onlineservice	Der zum Schlüsselpaar des Online-Antragsservice gehörige Public Key, der dem Online-Antragsdienst bei der Registrierung im Self-Service-Portal zugeordnet wurde, im JSON Web Key-Format gemäß RFC-7517
token_type	sender	Gibt an, das es sich um einen Token für ein antragssendendes System (typischerweise einen Onlineservice) handelt.

Beispiel-Payload eines Onlineservice-Token

{
  "iat": "1620072619",
  "exp": "1620079819",
  "iss": "https://auth.fit-connect.example.com",
  "sub": "639c5be8-eb9c-4741-834e-4ad11629898a",
  "jti": "1e078cd2-4717-4285-8746-91b62247eb60",
  "scope": "leika:99108008252000 leika:99108008252000+region:08110000",
  "domains": "example.com sub.example.com",
  "publicKey": {
    "kty": "RSA",
    "e": "AQAB",
    "key_ops": ["verify"],
    "alg": "PS512",
    "n": "...Public Key..."
  },
  "token_type": "sender"
}

Schritt 3: Zugriff auf die Antrags-API mittels Access Tokens

Für den Zugriff auf die Antrags-API des Zustelldienstes wird neben dem Onlineservice-Token immer auch ein sog. Access Token benötigt, der die generische Zugriffsberechtigung des Onlinedienstes auf einen konkreten Zustellpunt (Destination) und/oder einen konkreten Antragsvorgang einschränkt. Dies ermöglicht die Weitergabe von eingeschränkten Berechtigungstokens an das Endgerät der Antragsteller:in (Browser bzw. App) und einen direkten, eingeschränkten Zugriff des Endgeräts auf die Antrags-API.

Access Token und Onlineservice-Token müssen beim Zugriff auf die Antrags-API via HTTP-Header an den Zustelldienst übermittelt werden. Mithilfe der beiden Tokens kann nachvollzogen werden, von welchem antragssendenden System ein Antrag an welchen Zustellpunkt übermittelt wird und ob das antragssendende System hierzu autorisiert ist.

Beispiel

POST /applications HTTP/1.1
Host: api.zustelldienst-01.example.com
token: XXX
online-service-token: XXX

Access Tokens werden entweder vom Online-Antragssservice mit Hilfe des bei der Registrierung erstellten Onlineservice-Schlüsselpaars oder vom Endgerät der Antragssteller:in mit Hilfe eines vorgangsspezifischen Schlüsselpaars signiert und DÜRFEN eine Gültigkeitsdauer von 2 Stunden NICHT überschreiten.

Jedes Onlineservice-Backend muss dazu in der Lage sein, Access Tokens für den Zugriff auf die Antrags-API zu erzeugen und an das Endgerät der Antragsteller:in (Browser/App) zu übermitteln. Hierbei SOLLTE der Onlinedienst eine geeignete Form von Rate-Limiting für die Ausstellung der Access Tokens implementieren. Beim Zugriff auf die Antrags-API wird ein Rate-Limiting sowohl pro Online-Antragsdienst, als auch pro Antragsvorgang durchgeführt. In den vom Online-Antragsdienst generierten Access Tokens DÜRFEN keine Informationen hinterlegt werden, die zur Identifizierung von Antragssteller:innen geeignet sind.

Payload des Access Tokens

Im Payload des signierten Access Tokens MÜSSEN mindestens die folgenden standartisierten Felder gesetzt sein:

Feld	Inhalt	Erläuterung
iat	Unix Timestamp	Zeitpunkt, wann der Token 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)
iss (Issuer)	ID des Onlineservice	Die ID des Onlineservice. Der angegebene Wert muss dem Feld sub des zugehörigen Onlineservice-Token entsprechen.
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.
scope	Zustellberechtigungs-Scope	Eingeschränkte Zustellberechtigung auf eine konkrete Destination-ID mit Präfix destination: (im Stile der Zustellberechtigungs-Scopes), für die der Token eine Antragseinreichung erlaubt. Der Zustellberechtigungs-Scope des zugehörigen Onlineservice-Token muss zur Antragseinreichung bei dieser Destination-ID berechtigen.
token_type	siehe unten	Der Token-Typ gibt an, welche Funktion der ausgestellte Access Token erfüllt (siehe nächster Abschnitt).

Beispiel-Payload eines Access Token

{
  "iat":"1620072619",
  "exp":"1620079819",
  "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
  "jti": "b898ea5b-a411-4ba9-9b4c-64127e13c913",
  "aud": "api.zustelldienst-01.example.com",
  "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
  "token_type": "create-submission"
}

Verwendung von Access Tokens

Im Folgenden wird der Aufbau der eingesetzten Access Tokens beschrieben. Die hier beschriebenen Implementierungsdetails sollen dem technischen Verständnis dienen und unterstützen bei der Implementierung von Software zur Generierung und Prüfung der Access Tokens. Die im Projekt FIT-Connect bereitgestellten Code-Beispiele und SDKs setzen die hier beschriebenen Vorgaben um und KÖNNEN genutzt werden, um die beschriebene Funktionalität einfach und sicher in antragssendenden Systemen zu implementieren.

Je nach Art des Zugriffs MÜSSEN unterschiedliche Vorgaben für Access Tokens eingehalten werden:

Art des Zugriffs	Vorgaben für Access Token
Initiale Antragseinreichung inkl. Vorgangseröffnung	Der Access Token wird durch das Onlineservice-Schlüsselpaar signiert. Im Payload des Tokens wird der Token-Typ auf token_type: "create-submission" festgelegt.

Dieser Token-Typ berechtigt ausschließlich zum Anlegen von neuen Antragsvorgängen.

Beispiel-Payload eines Access Token mit Token-Typ create-submission

{
  "iat":"1620072619",
  "exp":"1620079819",
  "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
  "jti": "84573d90-ad99-419b-b696-79e058eeff6d",
  "aud": "api.zustelldienst-01.example.com",
  "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
  "token_type": "create-submission"
}

Beim Anlegen von neuen Antragsvorgängen MUSS für jeden Antragsvorgang ein separates kryptographisches Schlüsselpaar erzeugt werden (nachfolgend: Schlüsselpaar des Antragsvorgangs). Das Schlüsselpaar SOLLTE auf dem Endgerät der Antragsteller:in erzeugt werden. Sofern mit FIT-Connect eine Ende-zu-Ende-Verschlüsselung von der Antragsteller:in bis in das antragsempfangende System auf Verwaltungsseite realisiert werden soll, so MUSS das Schlüsselpaar auf dem Endgerät der Antragsteller:in erzeugt werden. Der öffentliche Schlüssel (Public Key) dieses Schlüsselpaares wird bei der Antragseinreichung über den Endpunkt POST /applications (TODO: Link) im eröffneten Vorgang hinterlegt.

Anschließend ermöglicht das generierte Schlüsselpaar bzw. ein daraus generierter Access Token die Authentifizierung der Antragsteller:in:

Art des Zugriffs	Vorgaben für Access Token
Uneingeschränkter Zugriff auf einen bestimmten Vorgang (Einreichen von Antragsdaten, Hinterlegen von Anhängen, Lesen und Schreiben des Event Log)	Der Access Token wird durch das Antragsvorgangs-Schlüsselpaar signiert. Ein Zugriff auf den Vorgang ist nur möglich, wenn im Zustelldienst zuvor der zugehörige Public Key des Antragsvorgangs-Schlüsselpaar hinterlegt wurde. Im Payload des Tokens wird der Token-Typ auf token_type: access-case festgelegt.

Dieser Access Token wird mithilfe des Schlüsselpaares des Antragsvorgangs signiert. Im Zustelldienst wird die Signatur des Tokens mithilfe des bei der Antragserstellung hinterlegten Public Key geprüft. Der Access Token weist nach, dass der anfragende API-Client berechtigt ist, auf einen spezifischen Vorgang zuzugreifen. Mit Hilfe dieses Access Tokens können nun die Antragsdaten und Anhänge dem eröffneten Antrags hinzugefügt werden. Hierbei ist ein Zugriff auf die Antrags-API direkt durch das Endgerät der Antragsteller:in möglich.

Beispiel-Payload eines Access Token mit Token-Typ access-case

{
  "iat":"1620072619",
  "exp":"1620079819",
  "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
  "jti": "ba3ba9a1-19d3-446b-a504-af9250cbaecf",
  "aud": "api.zustelldienst-01.example.com",
  "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
  "token_type": "access-case"
}

Der Onlinedienst hat nach wie vor - sofern er die Vorgangsreferenz des Vorganges (caseId) kennt - jederzeit lesenden und schreibenden Zugriff auf Statusbenachrichtigungen zu einem konkreten Vorgang im zugehörigen Event Log. Hierzu stellt sich der Onlineservice selbst ein Access Token aus und kann anschließend mit Access Token und Onlineservice-Token auf das Event Log zugreifen:

Art des Zugriffs	Vorgaben für Access Token
Lesen und Schreiben des Event Log	Der Access Token wird durch das Onlineservice-Schlüsselpaar signiert. Im Payload des Tokens wird der Token-Typ auf token_type: "access-eventlog" festgelegt.

Mit Hilfe eines Access Tokens vom Typ access-eventlog können perspektivische auch andere berechtigte Systeme (z.B. Statusmonitor im Nutzer:innenkonto) auf den Status von Antragsvorgängen zugreifen).

Beispiel-Payload eines Access Token mit Token-Typ access-eventlog

{
  "iat":"1620072619",
  "exp":"1620079819",
  "iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
  "jti": "2c633a19-9e84-4b23-8caf-960580e8c883",
  "aud": "api.zustelldienst-01.example.com",
  "scope": "destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1",
  "token_type": "access-eventlog"
}

Kryptographische Vorgaben

Kryptographische Vorgaben für JSON Web Tokens

Alle generierten JWT-Tokens MÜSSEN den Vogaben aus RFC 7519 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

{
  "typ":"JWT",
  "alg":"PS512"
}

Kryptographische Vorgaben für das im Onlineservice-Token hinterlegte Schlüsselpaar ("Onlineservice-Schlüsselpaar")

Jedes antragssendende System MUSS vor der Registrierung im Self-Service-Portal ein Schlüsselpaar erzeugen und den öffentlichen Teil des Schüsselpaares (Public Key) bei der Registrierung im Self-Service angeben.

Das erzeugte Schlüsselpaar MUSS eine Schlüssellänge von 4096 Bit aufweisen. Der zugehörige Public Key im Format JSON Web Key (JWK) MUSS über die folgenden Attribute gemäß RFC 7515 verfügen:

Feld	Inhalt	Erläuterung
kty	"RSA"	Keytype gemäß RFC 7517, Abschnitt 4
key_ops	["verify"]	Schlüsselverwendung (Prüfung von digitalen Signaturen) gemäß RFC 7517, Abschnitt 4.3
alg	"PS512"	Vorgesehener Algorithmus zur Erstellung und Prüfung von Signaturen in Kombination mit diesem JWK. Vorgabe gemäß BSI TR-02102-1, Abschnitt 5.4.1
kid	Eindeutige ID des Keys	Eindeutige ID zur Referenzierung des JSON Web Key gemäß RFC 7515, Abschnitt 4.1.4 dar. Es wird empfohlen, hierfür eine UUID gemäß RFC 4122 zu verwenden.
n	Modulus des Public Key zum Zertifikat	Der Modulus des Public Key gemäß RFC 7518, Abschitt 6.3.1.1 ("Base64urlUInt" enkodiert)
e	"AQAB"	Der Exponent des Public Key gemäß RFC 7518, Abschitt 6.3.1.2)

Kryptographische Vorgaben für das vorgangsspezifische Schlüsselpaar ("Schlüsselpaar des Antragsvorgangs")

Bei der Antrangseinreichung MUSS für jeden Antragsvorgang ein separates kryptographisches Schlüsselpaar erzeugt werden (nachfolgend: Schlüsselpaar des Antragsvorgangs). Das Schlüsselpaar SOLLTE auf dem Endgerät der Antragsteller:in erzeugt werden. Sofern mit FIT-Connect eine Ende-zu-Ende-Verschlüsselung von der Antragsteller:in bis in das antragsempfangende System auf Verwaltungsseite realisiert werden soll, so MUSS das Schlüsselpaar auf dem Endgerät der Antragsteller:in erzeugt werden. Der öffentliche Schlüssel (Public Key) dieses Schlüsselpaares wird bei der Einreichung eines Antrags im Antragsvorgang hinterlegt und ermöglicht die spätere Authentifizierung der Antragsteller:in.

Das erzeugte Schlüsselpaar MUSS eine Schlüssellänge von 4096 Bit aufweisen. Der zugehörige Public Key im Format JSON Web Key (JWK) MUSS über die folgenden Attribute gemäß RFC 7515 verfügen:

Feld	Inhalt	Erläuterung
kty	"RSA"	Keytype gemäß RFC 7517, Abschnitt 4
key_ops	["verify"]	Schlüsselverwendung (Prüfung von digitalen Signaturen, Verschlüsselung von (symmetrischen) Schlüsseln) gemäß RFC 7517, Abschnitt 4.3
alg	"PS512"	Vorgesehener Algorithmus zur Erstellung und Prüfung von Signaturen in Kombination mit diesem JWK. Vorgabe gemäß BSI TR-02102-1, Abschnitt 5.4.1
kid	Eindeutige ID des Keys	Eindeutige ID zur Referenzierung des JSON Web Key gemäß RFC 7515, Abschnitt 4.1.4 dar. Es wird empfohlen, hierfür eine UUID gemäß RFC 4122 zu verwenden.
n	Modulus des Public Key zum Zertifikat	Der Modulus des Public Key gemäß RFC 7518, Abschitt 6.3.1.1 ("Base64urlUInt" enkodiert)
e	"AQAB"	Der Exponent des Public Key gemäß RFC 7518, Abschitt 6.3.1.2)