Oauth2 Flow

OAuth 2.0 ist ein offenes Standardprotokoll zur sicheren Autorisierung von Anwendungen, ohne dass Benutzer ihre Zugangsdaten direkt weitergeben müssen. Stattdessen erhält eine Anwendung Zugriff auf eine API, indem sie Tokens verwendet.

​

Grundkonzepte von OAuth 2.0

• Authorization Server: Verifiziert die Identität des Benutzers und gibt Access Tokens aus.
• Resource Server: Der Server, der die geschützten Ressourcen bereitstellt (z. B. eine API).
• Client: Die Anwendung, die auf die API zugreifen möchte.
• Resource Owner: Der Benutzer, der entscheidet, ob eine Anwendung Zugriff auf seine Ressourcen erhält.
• Access Token: Ein temporäres Token, das für den Zugriff auf die API verwendet wird.
• Refresh Token (optional): Ein langfristiges Token, das zur Erneuerung eines Access Tokens genutzt wird.

​

Grant Types

Je nach Anwendungsszenario gibt es unterschiedliche Grant Types, die festlegen, wie ein Client ein Access Token erhält. Folgende Grant Types sind durch Fynn unterstützt:

​

Authorization Code Flow (mit oder ohne PKCE)

Der Authorization Code Flow ist ein OAuth2-Prozess, der für Webanwendungen entwickelt wurde, um Benutzer sicher zu authentifizieren und Zugriff auf geschützte Ressourcen zu gewähren. Dieser Flow wird besonders für serverseitige Anwendungen empfohlen, da die sensiblen Zugangsdaten nicht direkt im Frontend gespeichert werden.

• Einsatzbereich: Webanwendungen & mobile Apps
• Sicherheit: Sehr hoch (Tokens werden nur im Backend verwaltet)

Ablauf des Authorization Code Flow

1. Weiterleitung zur Autorisierungsanfrage: Die Anwendung leitet den Benutzer auf die Anmeldeseite des Autorisierungsservers weiter. Hier gibt die Anwendung an, welche Berechtigungen (Scopes) sie benötigt.
2. Benutzerauthentifizierung und Zustimmung: Der Benutzer meldet sich beim Autorisierungsserver an und wird gefragt, ob er der Anwendung den gewünschten Zugriff gewähren möchte.
3. Erhalt des Autorisierungscodes: Nach erfolgreicher Authentifizierung wird der Benutzer zurück zur Anwendung geleitet. Dabei wird ein einmaliger Autorisierungscode übergeben.
4. Austausch des Codes gegen ein Zugriffstoken: Die Anwendung sendet den erhaltenen Code zusammen mit einem geheimen Schlüssel an den Autorisierungsserver. Falls die Anfrage gültig ist, stellt der Server ein Access Token aus.
5. Zugriff auf geschützte Ressourcen: Mit dem erhaltenen Access Token kann die Anwendung nun auf geschützte APIs zugreifen und im Namen des Benutzers Daten abrufen oder Aktionen durchführen.

​

Proof Key for Code Exchange (PKCE)

PKCE (Proof Key for Code Exchange) ist eine Erweiterung des Authorization Code Flow, die speziell für öffentliche Clients wie Single-Page- und Mobile-Apps entwickelt wurde. Es verhindert, dass der Autorisierungscode durch Angriffe (z. B. Code Interception) missbraucht wird.

Funktionsweise von PKCE:

• Der Client generiert einen zufälligen Code Verifier (eine lange, zufällige Zeichenkette).
• Daraus wird eine Code Challenge abgeleitet (eine transformierte Version des Verifiers, meist als SHA-256 Hash).
• Beim Austausch des Autorisierungscodes gegen ein Access Token muss der Client den ursprünglichen Code Verifier mit senden.
• Der Server überprüft die Challenge und stellt das Access Token nur aus, wenn die Werte übereinstimmen.

Da kein geheimer Schlüssel gespeichert werden muss, ist PKCE besonders für Clients ohne sichere Speicherung (z. B. Browser-Anwendungen) wichtig.

​

Erweiterungen des Authorization Code Flow

1. Refresh Token für langfristigen Zugriff: Damit sich ein Benutzer nicht ständig neu authentifizieren muss, kann zusätzlich ein Refresh Token angefordert werden. Dies ermöglicht es der Anwendung, ohne erneute Benutzereingabe neue Access Tokens zu erhalten. Hierfür ist der Scope offline notwendig.
2. ID Token für Benutzerinformationen (OpenID Connect): Falls die Anwendung auch Informationen über den angemeldeten Benutzer benötigt, kann ein ID Token angefordert werden. Dieses wird als JWT (JSON Web Token) ausgestellt und enthält beispielsweise die Benutzer-ID, E-Mail-Adresse oder weitere Identitätsattribute. Hierfür ist der Scope openid notwendig.
3. Scopes zur Steuerung der Berechtigungen: Der Autorisierungsprozess kann durch verschiedene Scopes gesteuert werden. Diese definieren, welche Daten oder Funktionen der Benutzer der Anwendung freigibt.

​

Beispiel

Szenario: Eine Webanwendung möchte den Benutzer authentifizieren und erhält Zugriff auf eine geschützte API.

1. Benutzer wird zur Autorisierung weitergeleitet

Die Anwendung leitet den Benutzer zum Autorisierungsserver weiter:

GET https://oauth2.coreapi.io/oauth2/auth
    ?response_type=code
    &client_id=client123
    &redirect_uri=https://my-app.com/callback
    &scope=openid offline entitlements.read
    &state=randomString

2. Benutzer meldet sich an Der Benutzer wird zum Login-Formular von Fynn weitergeleitet. Nach der Anmeldung fragt Fynn, ob die Anwendung Zugriff erhalten darf.

Wenn der Benutzer zustimmt, gibt der Server einen Autorisierungscode zurück:

GET https://my-app.com/callback?code=AUTH_CODE&state=randomString

3. Anwendung tauscht den Code gegen ein Access Token Die Anwendung sendet nun eine POST-Anfrage an den Autorisierungsserver:

POST https://oauth2.coreapi.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=client123
&client_secret=superSecret
&grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://my-app.com/callback

Der Server gibt ein Access Token, Refresh Token und JWT Token (OpenID), je nach angegebenen Scopes, zurück:

{
    "access_token": "...",
    "expires_in": 3600,
    "refresh_token": "...",
    "id_token": "...",
    "scope": "...",
    "token_type": "Bearer"
}

​

Refresh Token

Wenn das Access Token abläuft, kann die Anwendung ein neues Token mit einem Refresh Token anfordern:

POST https://oauth2.coreapi.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=client123
&client_secret=superSecret
&grant_type=refresh_token
&refresh_token=abcd1234
&scope=offline openid entitlements.read

Der Server gibt ein Access Token, Refresh Token und JWT Token (OpenID), je nach angegebenen Scopes, zurück:

{
    "access_token": "...",
    "expires_in": 3600,
    "refresh_token": "...",
    "id_token": "...",
    "scope": "...",
    "token_type": "Bearer"
}

​

Scopes

Scopes definieren, welche Berechtigungen eine Anwendung innerhalb eines Zugriffs erhält. Sie begrenzen den Zugriff auf spezifische APIs und Funktionen. Folgende Scopes werden aktuell unterstützt:

Scopes werden sowohl bei der Autorisierungsanfrage als auch bei der Anlage des Oauth2 Clients angegeben.

​

OpenID Connect

OpenID Connect erweitert die Authentifizierungsfunktionen von OAuth, indem es Komponenten wie ein ID-Token einführt, das als JSON Web Token (JWT) ausgegeben wird.

OpenID Connect ermöglicht eine standardisierte Authentifizierung, indem es auf OAuth 2.0 aufbaut und sicherstellt, dass Anwendungen die Identität eines Benutzers vertrauenswürdig verifizieren können.

Um OpenID Connect zu verwenden, muss der Scope openid hinzugefügt werden. Anschließend wird beim Abruf der Tokens ebenfalls ein ID Token zurückgegeben.

​

ID Token

Das ID-Token ist konzeptionell mit einem Personalausweis vergleichbar, da es eine Reihe von JSON-Claims über den Benutzer enthält, wie zum Beispiel:

• sub (Subject) – Eindeutige Kennung des Benutzers
• name – Vollständiger Name des Benutzers
• email – E-Mail-Adresse des Benutzers
• iat (Issued At) – Zeitpunkt, zu dem das Token ausgestellt wurde
• exp (Expiration) – Ablaufzeit des Tokens
• iss (Issuer) – Identitätsanbieter (IdP), der das Token ausgestellt hat
• aud (Audience) – Die Zielanwendung, für die das Token bestimmt ist

{
  iss: "https://oauth2.coreapi.io",
  sub: "some-identity-id",
  aud: "some-client-id",
  exp: 1311281970,
  iat: 1311280970,
  nonce: "KxSty13b2L",
  name: "Jane Doe",
  given_name: "Jane",
  family_name: "Doe",
  email: "jane@example.org",
  email_verified: true,
}

​

Validierung ID Token (JWK)

Der ID Token kann mit Hilfe der JWK Keys validiert werden. Der notwendige Endpunkt hierfür lautet: https://oauth2.coreapi.io/.well-known/jwks.json, https://oauth2.preview.coreapi.io/.well-known/jwks.json.

​

OpenID Connect Logout

Folgende Flows werden aktuell unterstützt:

​

OpenID Connect Front-Channel Logout 1.0

Hierfür benötigen wir eine Logout URI. Teile uns diese bitte mit.

Funktionsweise:

• Wenn sich ein Benutzer abmeldet, leitet Fynn den User-Agent (Browser) an die registrierte Logout URI weiter.
• Die OAuth2-Client-Anwendung kann den Benutzer dann auch in deinem eigenen System abmelden, z. B. durch:
  • Löschen eines Authentifizierungs-Cookies
  • Invalidieren der Benutzersitzung

​

OpenID Connect Back-Channel Logout 1.0

Hierfür benötigen wir eine `Logout URI“. Teile uns diese bitte mit.

Beim Abmelden eines Benutzers wird eine HTTP-POST-Anfrage mit dem Content-Type application/x-www-form-urlencoded und einem logout_token an die konfigurierte URL gesendet.

Das logout_token ist ein JWT, das mit demselben Schlüssel signiert ist, der auch für die Signierung von OpenID Connect ID-Tokens verwendet wird. Daher sollte das logout_token mithilfe des öffentlichen Schlüssels für ID-Tokens validiert werden, welcher über /.well-known/jwks.json abgerufen werden kann.

Das logout_token enthält die folgenden Claims:

• iss (Issuer) – Identifikator des ausstellenden OpenID-Providers: https://oauth2.coreapi.io oder https://oauth2.preview.coreapi.io
• aud (Audience) – Die Client-ID des OAuth2-Clients, für den dieses Logout-Token bestimmt ist.
• iat (Issued At) – Zeitpunkt, zu dem das Token ausgestellt wurde. Kann verwendet werden, um das Alter des Tokens zu bestimmen.
• jti (JWT ID) – Eindeutige Kennung des JWTs, um Replay-Angriffe zu verhindern. Das Token sollte nur einmal verwendet werden.
• events – Enthält den Eintrag http://schemas.openid.net/event/backchannel-logout. Dies deklariert, dass das JWT ein Logout-Token ist. Der entsprechende Wert MUSS ein JSON-Objekt sein und SOLLTE sein (leeres JSON-Objekt).
• sid (Session ID) – Eine Sitzungs-ID, die eine bestimmte Sitzung mit einem ID-Token verknüpft. Diese wird beim Logout-Aufruf als Parameter übergeben.