Authentifizierung_von_Usern.md

Authentifizierung von Usern an Zustelldiensten

Jeder Onlineantragsdienst muss bei FIT-Connect registriert sein, um FIT-Connect Formulare darstellen und übermitteln zu können. Bei der Registrierung von Onlinediensten wird festgelegt, welche Anträge die Onlinedienste auf welchen Domains ausspielen dürfen. Im Rahmen dieses Prozesses wird für jeden Onlinedienst außerdem ein Public Key hinterlegt. Nach der Anmeldung erhält jeder Onlineantragsdienst OAuth2-Credentials für den Authentifizierungstyp "Client-Credentials".

Eine Registrierung eines Onlinedienstes ist über das Self-Service-Portal der FITKO möglich. (TODO: link) Dort müssen folgende Informationen über einen Onlinedienst hinterlegt werden:

• Freigegebene Domains, von denen der Onlinedienst Formulare übermittelt.
• Erlaubte Zustellberechtigungs-Scopes, an die Anträge übermittelt werden dürfen.
• Ein Public Key des Onlinedienstes, die er für die Erstellung von JWTs benutzt.

Wenn ein Onlinedienst einem User ermöglichen möchte, einen Antrag zu übermitteln, muss er mithilfe seiner Client-Credentials beim FIT-Connect-Authentifizierungsserver einen JWT-Access-Token (Onlinedienst-Token) abrufen. Dieser Onlinedienst-Token enthält den Public-Key, der für den Onlinedienst bei der Anmeldung festgelegt wurde, im signierten Datensatz.

Nun muss der Onlinedienst auf Basis des zum Public Key gehörenden Private Key einen weiteren JWT Token (User-Token) erzeugen, der Informationen dazu enthält, das der Onlinedienst dem User erlaubt, einen Antrag an eine spezifische Destinationen zu übermitteln.

Wenn der User nun einen Antrag an den Onlinedienst übermittelt, muss dieser sowohl den User-Token als auch den Onlinedienst-Token im Header mitübermitteln. Mithilfe der beiden Tokens kann das FIT-Connect API-Gateway nachvollziehen, von wo ein Antrag zu welcher Destination übermittelt wird und kann somit überprüfen, ob der User/Onlinedienst dafür autorisiert ist.

Warum ist die anonyme Authentifizierung notwendig?

Im Rahmen von FIT-Connect soll das massenhafte absenden (spammen) von Anträgen über Ratelimiting verhindert werden und es sollen nur vertrauenswürdige Webseiten, die dem FIT-Connect-Standards entsprechen, die Möglichkeit bekommen, Anträge über FIT-Connect zu übermitteln. Um diese Maßnahmen umsetzen und einen User über mehrere Requests hinweg sicher identifizieren zu können, ist eine Form der anonymen Authentifizierung notwendig.

Generierung der JWT-Tokens

Jedes Backend eines FIT-Connect Onlineantragsdienstes muss über ein System verfügen, welches JWT-Tokens für diese Instanz erzeugen und an den Browser des Users übermitteln kann. Es sollte dabei eine geeignete Form von Rate-Limiting, für die Ausstellung der Public Keys passend zum Usecase des Onlinedienstes implementieren. Es sollte die Menge der mit einem JWT-Token freigegebenen Destinationen minimieren. Es dürfen in denen vom Onlineservice generierten JWT-Tokens keinen Informationen hinterlegt werden, die zur Identifikation des Users führen könnten.

Anforderungen an die Keypairs

Der Onlinedienst muss zur Registrierung bei FIT-Connect neben den Angaben dazu, welche Destinationen er unter welchen Domains verwendenden möchte, auch noch einen Public Key eines Keypairs, das nach folgenden Standards erzeugt wurde, übermitteln:

Feld	Inhalt	Erläuterung
Hashingalgorithmus	SHA-512	Algorithmus der zur digitalen Signatur des Keys verwendet werden muss an. Dieser muss im Fall von FIT-Connect immer SHA-512 sein. (vgl. BSI TR-02102-1 Tabelle 4.1)
Keylänge	4096	Länge des zugrundeliegenden RSA-Keys. Diese entspricht der Empfehlung des BSIs für ab dem Jahr 2023. (vgl. BSI TR-02102-1 Tabelle 3.1)
Signaturstandard	RSASSA-PSS	Entspricht dem Standard beschrieben in RFC 4056 und vom BSI empfohlen in BSI TR-02102-1 Abschnitt 5.4.1.

Bei der Erstellung und Signierung des Keys sind alle Regeln und Standards aus BSI TR-02103 zu beachten.

Anforderung an die JWT-Tokens

Die vom Onlinedienst generierten JWT-Tokens müssen nach RFC 7519 über folgende Attribute verfügen:

Header

Entsprechend RFC 7519 Abschnnitt 8:

Feld	Inhalt	Erläuterung
typ	JWT	Es handelt sich um einen JWT-Token.
alg	RS512	Der JWT Token verwendet RSASSA-PSS und SHA-512.

Beispiel

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

Body des User-JWT-Tokens

Entsprechend den standartisierten Feldern:

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 sollte max. 2 Stunden gültig sein vgl BSI APP.3.1).
scope	Liste von Destination-IDs	Eine Liste der Destination-IDs (im Stile der Zustellberechtigungs-Scopes geprefixed), für die der JWT eine Übermittlung erlaubt.
sid	UUID4 der Session	Eine unique ID zur Identifizierung der Session (muss garantiert für jede Übermittlung anders sein)
iss	ID des Onlinedienstes	Wird bei der Anmeldung des Onlinedienstes festgelegt und dient zur Identifizierung am API-Gateway
domains	Liste von Domains	Eine Liste der Domains, von denen der Onlineservice Anträge übermitteln kann. Sie muss einem Subset der Domains entsprechen, die im domains Feld des Onlinedienst-JWT angegeben wurden. (Subdomains müssen explizit angegeben werden)
clientType	user-sender	Gibt an, das es sich um denn abgeleiteten User Token eines Onlineservices handelt, mit dem Anträge eingereicht werden können.

Beispiel

{  
	"iat":"1620072619",  
	"exp":"1620079819",
	"scope": ["destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1"],
	"sid": "8d4dcbfd-a528-4e9b-abc3-477c4cc857aa",
	"iss": "639c5be8-eb9c-4741-834e-4ad11629898a",
  "clientType": "user-sender",
}

Body des Onlinedienst-JWT-Tokens

Entsprechend den standartisierten Feldern: