OAuth 2.0 & OpenID Connect SSO

Der OAuth-2.0-Authorization-Code-Flow ist der empfohlene und sicherste Flow für die meisten Anwendungen, einschließlich Webanwendungen und Single-Page-Applications (SPAs). Er nutzt PKCE (Proof Key for Code Exchange) für öffentliche Clients, um Angriffe durch Abfangen des Authorization Code zu verhindern.

Am besten geeignet für: Webanwendungen, SPAs, mobile Apps, Drittanbieter-Integrationen

Nutze Refresh Tokens, um neue Access Tokens zu erhalten, ohne dass sich der Nutzer erneut anmelden muss. Refresh Tokens sind 14 Tage gültig und können rotiert werden, um die Sicherheit zu erhalten.

Am besten geeignet für: Langlebige Sitzungen, Hintergrunddienste, Offline-Zugriff

Der OAuth-2.0-Resource-Owner-Password-Credentials-Flow wird aus Gründen der Abwärtskompatibilität mit Legacy-Integrationen unterstützt. Neue Integrationen sollten stattdessen den Authorization Code Flow verwenden.

Am besten geeignet für: Legacy-Anwendungen, interne Tools (für neue Entwicklungen nicht empfohlen)

GET /connect/authorize

Startet den OAuth-Autorisierungs-Flow. Leitet den Nutzer zur Anmeldung bei seinem Identity Provider weiter (Microsoft, Google oder E-Mail/Passwort).

Query-Parameter:

• client_id (erforderlich): Deine Anwendungs-ID
• redirect_uri (erforderlich): URL, an die nach der Authentifizierung weitergeleitet wird
• response_type (erforderlich): Muss 'code' sein
• scope (erforderlich): Durch Leerzeichen getrennte Liste von Scopes (openid, email, profile, offline_access, roles)
• code_challenge (erforderlich für SPA): PKCE Code Challenge
• code_challenge_method (erforderlich zusammen mit code_challenge): 'S256'
• state (empfohlen): Zufällige Zeichenfolge zum Schutz vor CSRF-Angriffen
• tenant_id (optional): Bestimmter Mandant, in dem authentifiziert werden soll

POST /connect/token

Tauscht einen Authorization Code gegen Access Token, ID Token und optionales Refresh Token.

Anfrageformat: application/x-www-form-urlencoded

Parameter:

• grant_type (erforderlich): 'authorization_code', 'refresh_token' oder 'password'
• code (erforderlich für Authorization Code Flow): Authorization Code von /authorize
• client_id (erforderlich): Deine Anwendungs-ID
• client_secret (erforderlich): Dein Anwendungs-Secret (vertraulich behandeln)
• redirect_uri (erforderlich): Muss mit der /authorize-Anfrage übereinstimmen
• code_verifier (erforderlich für SPA): PKCE Code Verifier
• refresh_token (für Refresh-Flow): Das auszutauschende Refresh Token
• username & password (für Password-Flow): Nutzeranmeldedaten

POST /connect/introspect

Prüft und liest den Inhalt eines Access Tokens oder Refresh Tokens aus.

GET /.well-known/openid-configuration

Standard-OIDC-Metadaten-Endpunkt. Liefert Discovery-Informationen einschließlich Endpunkten, öffentlichen Schlüsseln, unterstützten Scopes und Grant-Types.

Erstelle clientseitig einen Code Verifier und eine Code Challenge:

// 1. Generate random code verifier (43-128 characters)
const codeVerifier = generateRandomString(128);

// 2. Create code challenge via SHA256 hash
const codeChallenge = await crypto.subtle.digest('SHA-256',
  new TextEncoder().encode(codeVerifier)
);

// 3. Base64-URL encode the challenge
const codeChallengeB64 = base64UrlEncode(codeChallenge);

// Store codeVerifier in sessionStorage for Step 3
sessionStorage.setItem('pkce_verifier', codeVerifier);

Leite den Nutzer zur Anmeldung weiter:

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &code_challenge={pkce_challenge}
  &state={random_state}

Der Nutzer wird zu seinem Identity Provider weitergeleitet (Microsoft, Google oder E-Mail/Passwort), schließt die Authentifizierung ab und wird zurück zu deiner redirect_uri mit einem Authorization Code weitergeleitet.

Tausche von deinem Backend aus den Authorization Code ein:

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={auth_code}
&client_id={your_app_id}
&client_secret={your_app_secret}
&redirect_uri=https://your-app.com/callback
&code_verifier={pkce_verifier}

Bei Erfolg erhältst du:

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

Validiere die Signatur des ID Tokens mit dem öffentlichen Schlüssel von /.well-known/openid-configuration, prüfe die Issuer- und Audience-Claims und extrahiere die Nutzerinformationen.

Das ID Token (JWT) enthält die Identitätsinformationen des Nutzers:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Wichtige Claims:

• sub: Eindeutige Nutzer-ID (Guid)
• email: E-Mail-Adresse des Nutzers
• email_verified: Ob die E-Mail-Adresse verifiziert ist
• name, given_name, family_name: Name des Nutzers
• tenant_id: Aktiver Mandant/Organisation des Nutzers
• iss: Token-Aussteller (immer https://api.advanza.ai)
• aud: Vorgesehene Zielgruppe (deine Anwendungs-ID)
• iat: Ausstellungszeitpunkt des Tokens (Unix-Zeitstempel)
• exp: Ablauf des Tokens (Unix-Zeitstempel)

Das Access Token (JWT) enthält die Autorisierungsinformationen:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "name": "John Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "roles": ["Owner"],
  "scope": "openid email profile offline_access roles",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Wichtige Claims:

• sub: Nutzer-ID
• email, name: Nutzerinformationen
• tenant_id: Aktiver Mandant (für Multi-Tenancy-Routing verwenden)
• roles: Rollen des Nutzers im Mandanten
• scope: Gewährte Scopes
• exp: Ablauf (typischerweise 1 Stunde)

Access Token verwenden für: Im Authorization-Header einfügen (Authorization: Bearer {access_token}), wenn Advanza-APIs oder dein Backend aufgerufen werden.

Bei der ersten Anmeldung wird dem Nutzer ein Standardmandant zugewiesen. Der tenant_id Claim wird mit der ID dieses Mandanten befüllt.

Nutzer mit mehreren Mandantenmitgliedschaften können den Mandanten wechseln, indem sie den gewünschten tenant_id Parameter an den Authorization-Endpunkt übergeben:

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &tenant_id=12345678-1234-1234-1234-123456789012
  &code_challenge={pkce_challenge}

Nutze den tenant_id Claim, um Anfragen in deinem Backend an den richtigen Mandantenkontext weiterzuleiten:

// Extract tenant from token claims
const tenantId = tokenClaims.tenant_id;

// Route request to tenant context
const tenantContext = getTenantContext(tenantId);
const result = await performAction(tenantContext, action);