Authentifizierung
Nachfolgend wird der Abruf von Access Tokens beim OAuth-Dienst sowie der Zugriff auf die FIT-Connect Submission API mittels Access Tokens beschrieben.
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
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
- .NET (SDK)
- curl
- Java (Spring)
- C#
- JavaScript
// TBD
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".
// TBD
// TBD
$ 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" \
-X POST "$OAUTH_URL"
{
"access_token": "eyJraWQi...",
"expires_in": 1800,
"scope": "send:region:DE01010",
"token_type": "Bearer"
}
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...
Die URL der Submission API findet sich im Artikel Betriebsumgebungen.