Skip to Content

Hosted Login (Authorization Code + PKCE)

Auris Hosted Login ist die empfohlene Authentifizierungsmethode für Web- und Mobile-Anwendungen. Sie nutzt den OAuth2 Authorization Code Flow mit PKCE (Proof Key for Code Exchange, RFC 7636), um Benutzer sicher zu authentifizieren, ohne Client-Secrets im Frontend-Code preiszugeben.

Die gehostete Login-Seite wird vollständig von Auris verwaltet und umfasst E-Mail/Passwort-Authentifizierung, Social Login, Magic Links, SMS OTP und WebAuthn – alles in einem einzigen Flow. Sie respektiert die Branding-Konfiguration deines Tenants und unterstützt mehrere Sprachen.

PKCE-Schutz wird standardmäßig für alle Auris Authorization Code Flows erzwungen. Die plain-Challenge-Methode ist nicht erlaubt – nur S256 wird akzeptiert.


Funktionsweise

PKCE-Parameter generieren

Deine Anwendung generiert einen kryptografisch zufälligen code_verifier (43–128 Zeichen) und leitet daraus einen code_challenge mit SHA-256-Hashing ab: code_challenge = BASE64URL(SHA256(code_verifier)).

Zur gehosteten Login-Seite weiterleiten

Deine Anwendung leitet den Browser des Benutzers zum Auris-Autorisierungs-Endpunkt weiter, mit code_challenge, client_id, redirect_uri, state und optional scope, locale, login_hint, prompt und screen_hint.

Benutzer authentifiziert sich

Der Benutzer schließt die Authentifizierung auf der gehosteten Auris-Seite ab. Falls Multi-Faktor-Authentifizierung erforderlich ist (nach Rolle, Risiko-Score oder Tenant-Richtlinie), wird der Benutzer im selben gehosteten Flow zur Eingabe eines zweiten Faktors aufgefordert.

Autorisierungscode empfangen

Bei erfolgreicher Authentifizierung leitet Auris zurück zu deiner redirect_uri weiter, mit einem kurzlebigen Autorisierungs-code und dem ursprünglichen state-Parameter zur CSRF-Validierung.

Code gegen Tokens tauschen

Deine Anwendung sendet den code und den code_verifier (nicht die Challenge) an den Auris-Token-Endpunkt. Auris verifiziert, dass SHA256(code_verifier) mit der gespeicherten code_challenge übereinstimmt, und stellt ein access_token, refresh_token und id_token aus.


Voraussetzungen

Bevor du Hosted Login implementierst, benötigst du eine in der Auris Console registrierte Anwendung:

  1. Gehe zu Console → Applications und klicke auf Create Application
  2. Wähle den Anwendungstyp Web
  3. Füge unter Allowed Callback URLs deine redirect_uri hinzu (z. B. http://localhost:3000/callback)
  4. Notiere deine Client ID – du verwendest sie in der SDK-Konfiguration
  5. Verwende kein Client Secret in Frontend-Anwendungen – PKCE ersetzt es

Die zur Laufzeit verwendete redirect_uri muss genau mit einer der in der Console registrierten URIs übereinstimmen. Auris lehnt jede Weiterleitung zu einer nicht registrierten URI ab.


Implementierung

import { AurisProvider, useAuris } from '@auris/react' // App-Root mit AurisProvider umhüllen function App() { return ( <AurisProvider domain="auth.yourdomain.com" clientId="your-client-id" redirectUri="http://localhost:3000/callback" > <MyApp /> </AurisProvider> ) } // Login-Button-Komponente function LoginButton() { const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuris() if (isLoading) return <p>Lädt...</p> if (isAuthenticated) { return ( <div> <p>Willkommen, {user.name}</p> <button onClick={() => logout({ returnTo: window.location.origin })}> Abmelden </button> </div> ) } return <button onClick={loginWithRedirect}>Anmelden</button> } // Callback-Seite — verarbeitet die Weiterleitung von Auris zurück // Platziere dies unter deinem redirectUri-Pfad import { useEffect } from 'react' import { useAuris } from '@auris/react' import { useNavigate } from 'react-router-dom' function CallbackPage() { const { handleRedirectCallback } = useAuris() const navigate = useNavigate() useEffect(() => { handleRedirectCallback().then(() => { navigate('/dashboard') }) }, []) return <p>Anmeldung wird abgeschlossen...</p> } // AuthGuard — Routen schützen, die Authentifizierung erfordern import { AuthGuard } from '@auris/react' function ProtectedPage() { return ( <AuthGuard> <h1>Diese Seite erfordert Authentifizierung</h1> </AuthGuard> ) }

Anpassungsoptionen

Die folgenden Query-Parameter können an loginWithRedirect() übergeben werden, um das Hosted-Login-Erlebnis anzupassen:

ParameterTypBeschreibung
localestringUI-Sprache überschreiben. Unterstützt: en, it, de, fr, es
login_hintstringE-Mail-Feld mit einer bekannten Adresse vorausfüllen
promptlogin | nonelogin erzwingt erneute Authentifizierung. none gibt einen Fehler zurück, wenn keine aktive Sitzung vorhanden ist
screen_hintsignupÖffnet direkt das Registrierungsformular anstatt des Login-Formulars
connectionstringEinen bestimmten SSO-Connection-Alias erzwingen (umgeht das Login-Formular)
// Beispiele await auris.loginWithRedirect({ login_hint: '[email protected]', screen_hint: 'signup', locale: 'de', }) // Erneute Authentifizierung erzwingen (bestehende Sitzung ignorieren) await auris.loginWithRedirect({ prompt: 'login' }) // Sitzung stumm prüfen (gibt Fehler zurück, wenn nicht authentifiziert) await auris.loginWithRedirect({ prompt: 'none' })

Token-Verwaltung

Access Token

Der Access Token ist ein JWT, signiert mit RS256 (oder HS256 wenn konfiguriert). Er enthält Standard-Claims (iss, sub, exp, iat) sowie Auris-spezifische Claims (roles, type und alle für die Anwendung konfigurierten benutzerdefinierten Claims).

Access Tokens sind für die auf deinem Tenant konfigurierte Dauer gültig (Standard: 60 Minuten).

Refresh Token

Refresh Tokens sind langlebig und ermöglichen das Abrufen neuer Access Tokens ohne Benutzerinteraktion. Das SDK verwaltet die Erneuerung automatisch, wenn autoRefresh: true gesetzt ist.

// Manuelle Token-Erneuerung const newToken = await auris.refreshToken() // Access Token abrufen — wird automatisch erneuert wenn abgelaufen (wenn autoRefresh: true) const accessToken = await auris.getAccessToken()

Token-Speicherung

Standardmäßig speichert das SDK Tokens in localStorage. Für Anwendungen, die höhere Sicherheit erfordern, kannst du einen cookie-basierten Speicher-Adapter verwenden:

import { AurisClient, CookieStorage } from '@auris/js' const auris = new AurisClient({ domain: 'auth.yourdomain.com', clientId: 'your-client-id', redirectUri: 'http://localhost:3000/callback', storage: new CookieStorage({ secure: true, sameSite: 'Lax' }), })

Sicherheitsüberlegungen

PKCE S256-Erzwingung — Auris akzeptiert nur S256 als Code-Challenge-Methode. Die plain-Methode wird am Autorisierungs-Endpunkt abgelehnt.

Redirect-URI-Validierung — Die redirect_uri in der Token-Austausch-Anfrage muss genau mit der in der Console registrierten URI übereinstimmen. Teilübereinstimmungen und Wildcards sind nicht zulässig.

State-Parameter — Das SDK generiert für jede Autorisierungsanfrage einen kryptografisch zufälligen state-Wert und validiert ihn beim Callback. Dies verhindert CSRF-Angriffe. Deaktiviere die State-Validierung nicht.

Kurzlebige Autorisierungscodes — Autorisierungscodes laufen nach 5 Minuten ab und können nur einmal verwendet werden. Jeder Versuch, einen Code erneut zu verwenden, führt zu einer Ablehnung und zur Ungültigmachung aller für diese Sitzung bereits ausgestellten Tokens.

Einmaliger Code-Einsatz — Der Code-Austausch erfolgt in einer atomaren Transaktion. Wenn ein Code zweimal eingelöst wird (z. B. durch doppeltes Absenden), wird die zweite Anfrage abgelehnt und die beim ersten Austausch ausgestellten Tokens werden widerrufen.


API-Endpunkte

POST/api/oauth/authorize

Startet den Authorization Code Flow. Validiert client_id, redirect_uri, PKCE-Parameter und erstellt eine OAuth-Sitzung. Gibt die URL der gehosteten Login-Seite zurück.

POST/api/auth/token

Tauscht einen Autorisierungscode gegen Tokens (grant_type=authorization_code). Verarbeitet auch client_credentials- und refresh_token-Grant-Types.

GET/.well-known/openid-configuration

OIDC-Discovery-Dokument. Enthält alle Endpunkt-URLs, unterstützte Grant-Types, Signatur-Algorithmen und Claim-Typen.

GET/.well-known/jwks.json

JSON Web Key Set (JWKS). Enthält öffentliche Schlüssel zur Verifizierung von Access-Token-Signaturen. Wird für 1 Stunde gecacht.


Umgebungsvariablen

# Erforderlich für die Next.js-Integration NEXT_PUBLIC_AURIS_DOMAIN=auth.yourdomain.com NEXT_PUBLIC_AURIS_CLIENT_ID=your-client-id NEXT_PUBLIC_APP_URL=http://localhost:3000 # Optional — für serverseitige JWT-Verifizierung ohne Netzwerkaufruf AURIS_JWKS_URL=https://auth.yourdomain.com/.well-known/jwks.json

Verwandte Anleitungen