OAuth-Clients: Technische Details, URLs und Code-Ausschnitte

Hier haben wir alle technischen Details, URLs und Code-Ausschnitte zum Authentifizierungsablauf für OAuth-Clients für Dich zusammengefasst.

Arbeite mit einer Bibliothek: Implementiere diese Abläufe auf keinen Fall selbst, sondern nutze eine Bibliothek, die Dich bei der Umsetzung unterstützt. OAuth-Client-Libraries sind für alle gängigen Programmiersprachen und Frameworks verfügbar. So reduziert sich Dein Implementierungsaufwand auf ein Minimum. Wenn Du eine Bibliothek nutzt, kannst Du Deine OAuth-Clients integrationsseitig oft mit wenigen Angaben einrichten (z.B. OAuth-URLs, Grant Type, Client-ID & Secret).

OAuth-spezifische URLs

Inxmail bietet einen OpenID Connect Discovery Endpunkt. Der Endpunkt ist öffentlich zugänglich und liefert als Response ein JSON Objekt, das allgemeine Informationen über Aufbau und Konfiguration des User-Management von Inxmail enthält. Unter anderem sind auch alle relevanten OAuth-Endpunkte enthalten.

Hinweis: Das User-Management von Inxmail stellt alle Tokens als signierte JWT-Tokens bereit. Der JWKS-Endpunkt stellt die öffentlichen Schlüssel zur Verfügung, um die Signatur eines Tokens zu verifizieren.

Authorization Code Grant Flow

Einleiten des Authorization Code Grant

Der Authorization Code Grant wird durch den Aufruf der Authorization-URL (Authorization Request) eingeleitet.

Beispiel:

1
2
3
4
5
6
https://my.inxmail.de/auth/realms/nxp/protocol/openid-connect/auth
    ?response_type=code
    &scope=offline_access 
    &client_id=<client_id>
    &redirect_uri=<redirect_uri>
    &state=<custom state>

Details und Links

Parameter	Beschreibung und Links
response_type	Verwendeter Authorization Code Grant. Muss den Wert 'code' beinhalten.
client_id	Client-ID der Integration. Du erhältst die Client-ID beim Anlegen Deines OAuth-Clients in Inxmail.
state	Optional: Verwende den state-Parameter, um den state zwischen Authorization Request und Authorization Response abzufragen.
redirect_uri	Redirect-URL der Integration. Hierlege dieselbe Redirect-URL, die Du auch in Deinem OAuth-Client in Inxmail hinterlegt hast.
scope	Verwendete OAuth-Scopes. Muss den Wert 'offline_access' beinhalten, damit ein langlebiges Refresh Token angefordert werden kann.

Abschluss des Authorization Code Grant

Der Authorization Code Grant wird abgeschlossen, indem (nach erfolgreicher Inxmail User-Authentifizierung) auf die Redirect-URL (Parameter 'redirect_uri') weitergeleitet wird, die im Authorization Request der Integrationsanwendung hinterlegt ist (Authorization Response).

Beispiel:

https://<redirect_uri des Authorization Request>
    ?code=<code>
    &state=<state des Authorization Request>

Details und Links

Parameter	Beschreibung und Links
code	Kurzlebige, durch den Authorization Server generierte Zeichenfolge. Der code-Parameter wird verwendet, um über einen Token Request ein Refresh Token anzufordern.
state	Unveränderter Inhalt des state-Parameters aus dem Authorization Request.

State zwischen Authorization-Request und Authorization Response erhalten

Bevor das Inxmail User-Management (nach erfolgreicher User-Authentifizierung) den Redirect auf die Redirect-URL sendet, wird der state-Parameter unverändert an die Redirect-URL angehängt. Du kannst den state-Parameter dafür verwenden, um anwendungsspezifische Daten einer Integration zwischen Authorization Request und Authorization Response zu erhalten. Wenn Du mehrere state-Werte abfragen möchtest, musst Du sie innerhalb des state-Parameters kodieren (z.B. über ein eindeutiges Trennzeichen). Du kannst den state-Parameter nicht mehrfach angeben.

Um Deine Integration vor CSRF Attacken zu schützen, empfehlen wir Dir, dass Du dem state-Parameter zusätzlich einen pro Authorization Request eindeutigen Wert (CSRF Token) mitgibst und ihn in der zugehörigen Authorization Response verifizierst.

Refresh-Token anfordern

Mit dem code-Parameter, der in der Authorization Response geliefert wird, ist es möglich über einen Token Request (POST) ein Refresh Token für die Integration anzufordern. Da der code-Parameter nur eine begrenzte Lebensdauer besitzt, sollte der Token Request unmittelbar nach oder während der Authorization Response ausgeführt werden.

https://my.inxmail.de/auth/realms/nxp/protocol/openid-connect/token
    ?grant_type=authorization_code
    &client_id=<client_id>
    &client_secret=<client_secret>
    &redirect_uri=<redirect_uri>
    &code=<code>

Details und Links

Parameter	Beschreibung
grant_type	Verwendeter Grant-Type: Muss den Wert 'authorization_code' beinhalten.
client_id	Client-ID der Integration. Du erhältst die Client-ID beim Anlegen Deines OAuth-Clients in Inxmail.
client_secret	Client-Secret der Integration. Du erhältst das Client-Secret beim Anlegen Deines OAuth-Clients in Inxmail.
code	Unveränderter Inhalt des code-Parameters aus der Authorization Response.
redirect_uri	Redirect URI der Integration. Muss dem Wert des redirect_uri-Parameters entsprechen, der im vorhergehenden Authorization Request mitgeliefert wurde.

Die Response des Token Request enthält unter anderem ein Refresh Token, das von der Integrationsanwendung gespeichert werden kann, um später neue Access Tokens für Deine·n Inxmail Benutzer·in anzufordern.

Beispiel:

1
2
3
4
5
{
    "access_token":"<access_token>",
    "refresh_token":"<refresh_token>",
    ...
}

Access Token: Die Token Response enthält ein aktuelles Access Token, das Du sofort benutzen kannst.

Refresh Token Flow

Access Token mittels Refresh Token anfordern

Sobald der Integrationsanwendung ein Refresh Token zur Verfügung steht, ist die Applikation in der Lage eigenständig (d.h. ohne weitere User-Interaktion) ein neues Access Token für eine·n Benutzer·in anzufordern.

Beispiel:

https://my.inxmail.de/auth/realms/nxp/protocol/openid-connect/token
    ?grant_type=refresh_token
    &client_id=<client_id>
    &client_secret=<client_secret>
    &refresh_token=<refresh_token>

Details und Links

Parameter	Beschreibung
grant_type	Verwendeter Grant Type. Muss den Wert 'refresh_token' beinhalten.
client_id	Client-ID der Integration. Du erhältst die Client-ID beim Anlegen Deines OAuth-Clients in Inxmail.
client_secret	Client-Secret der Integration. Du erhältst das Client-Secret beim Anlegen Deines OAuth-Clients in Inxmail.
refresh_token	Refresh Token, für das ein neues Access Token angefordert werden soll.

Die Response des Token Request enthält unter anderem ein aktuelles Access Token, das Dein·e Benutzer·in für einen authentifizierten Aufruf der Inxmail API nutzen kann.

Beispiel:

{
    "access_token":"<access_token>",
    ...
}

Weitere Infos