Zum Hauptinhalt springen

Authentifizierung

Nachfolgend wird der Abruf von Access Tokens beim OAuth-Dienst sowie der Zugriff auf die FIT-Connect Submission API mittels Access Tokens beschrieben.

Hinweis

Als Voraussetzungen hierfür ist es notwendig, Accounts für API-Clients im Self-Service-Portal zu registrieren.

Abruf von Access Tokens beim OAuth-Dienst

Hinweis

Die URL der Submission API und die OAuth-Token-URL finden sich im Artikel Betriebsumgebungen.

Fast alle Anfragen an die FIT-Connect Submission API müssen authentifiziert werden. Hierfür ist ein Access Token notwendig, das beim OAuth-Dienst über die hierfür vorgesehene OAuth-Token-URL abgerufen werden kann. Für den Abruf von Access Tokens ist die Konfiguration eines API-Client im Self-Service-Portal nötig. Bei der Konfiguration eines API-Client werden client_id und client_secret erzeugt.

Da ein Token max. 30 Minuten gültig ist, muss dieses regelmäßig erneuert werden.

Abfrage von Access Tokens mit allen zugewiesenen Scopes

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch einen Aufruf der SDK-Methode ClientFactory.GetSenderClient(...) automatisch mit abgedeckt:

var sender = ClientFactory
.GetSenderClient(FitConnectEnvironment.Testing, clientId, clientSecret, logger)

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples der FITKO hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".


Wenn keine spezifischer Scope angefragt wird (siehe nächster Abschnitt), enthält der Access Token alle Scopes, die zu diesem Zeitpunkt beim Client im Self-Service-Portal hinterlegt wurden.

Abfrage von Access Tokens mit spezifischen Scopes

Es ist möglich den Scope des Access Tokens zu beschränken. Hier im Beispiel hat der angelegte OAuth Client weitreichende Berechtigungen: send:region:DE. Wir beschränken allerdings diesen konkreten Access Token auf send:region:DE01010.

$ export OAUTH_URL=https://auth-testing.fit-connect.fitko.dev/token
$ export CLIENT_ID=<client_id>
$ export CLIENT_SECRET=<client_secret>
$ curl \
-H "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=send:region:DE01010" \
-X POST "$OAUTH_URL"
{
"access_token": "eyJraWQi...",
"expires_in": 1800,
"scope": "send:region:DE01010",
"token_type": "Bearer"
}

Wie in der Anfrage zu erkennen ist, wurde der Token entsprechend beschränkt. Dies funktioniert nur wenn der angefragte scope innerhalb der Berechtigungen des API-Clients liegen.

Weiterführende Details zu den Scopes finden sich hier:

Zugriff auf die API mittels Access Token

Access Tokens werden vom OAuth-Dienst erzeugt und DÜRFEN NIEMALS an dritte Systeme (mit Ausnahme des Zustelldienstes zum Zwecke der Authentifizierung) weitergegeben werden.

Beim Zugriff auf die Submission API muss ein Access Token im Authorization-Header mit Bearer-Authentifizierungsschema gemäß RFC 6750 an den Zustelldienst übermittelt werden:

Beispiel

POST /v1/submissions HTTP/1.1
Host: submission-api-testing.fit-connect.fitko.dev
Authorization: Bearer ey...
Hinweis

Die URL der Submission API findet sich im Artikel Betriebsumgebungen.