OpenID Connect (Authorization Code + PKCE)
Der OIDC Authorization Code Flow mit PKCE, mit reinem HTTP und curl, damit Sie jeden Schritt verstehen, bevor Sie eine Bibliothek einsetzen.
Diese Anleitung führt durch den Authorization Code Flow mit PKCE (Autorisierungscode-Verfahren) und verwendet dabei nichts als HTTP, sodass Sie genau sehen, was jeder Schritt sendet und empfängt. Die Node- und React-Anleitungen tun dasselbe mit einer Bibliothek; lesen Sie diese hier zuerst.
Stellen Sie sicher, dass Sie eine Anwendung und eine Redirect-URI registriert haben, wie unter Bevor Sie beginnen beschrieben.
Der Flow auf einen Blick
- Ihre App leitet den Browser mit einer PKCE-Challenge an den Authorization-Endpunkt weiter.
- Der Benutzer meldet sich an; die Plattform leitet mit einem einmaligen
codezurück an Ihre Redirect-URI. - Ihre App tauscht den
code(plus PKCE-Verifier) am Token-Endpunkt gegen ein ID-Token und ein Access-Token. - Ihre App validiert das ID-Token und ruft optional den UserInfo-Endpunkt auf.
1. PKCE-Verifier und -Challenge erzeugen
Erzeugen Sie einen zufälligen Code-Verifier und leiten Sie daraus die SHA-256-Code-Challenge ab:
# code verifier: 43-128 chars of unreserved characters
CODE_VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)
# code challenge: base64url(SHA256(verifier))
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -binary -sha256 | openssl base64 | tr '+/' '-_' | tr -d '=\n')
echo "verifier: $CODE_VERIFIER"
echo "challenge: $CODE_CHALLENGE"import { createHash, randomBytes } from 'node:crypto';
const codeVerifier = randomBytes(48).toString('base64url'); // 64 chars
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
console.log('verifier: ', codeVerifier);
console.log('challenge:', codeChallenge);import base64, hashlib, secrets
code_verifier = secrets.token_urlsafe(48) # 64 chars
digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
print("verifier: ", code_verifier)
print("challenge:", code_challenge)import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Base64;
var random = new byte[48];
new SecureRandom().nextBytes(random);
var encoder = Base64.getUrlEncoder().withoutPadding();
var codeVerifier = encoder.encodeToString(random); // 64 chars
var codeChallenge = encoder.encodeToString(
MessageDigest.getInstance("SHA-256").digest(codeVerifier.getBytes(StandardCharsets.US_ASCII)));
System.out.println("verifier: " + codeVerifier);
System.out.println("challenge: " + codeChallenge);using System.Security.Cryptography;
using System.Text;
static string B64Url(byte[] bytes) =>
Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
var codeVerifier = B64Url(RandomNumberGenerator.GetBytes(48)); // 64 chars
var codeChallenge = B64Url(SHA256.HashData(Encoding.ASCII.GetBytes(codeVerifier)));
Console.WriteLine($"verifier: {codeVerifier}");
Console.WriteLine($"challenge: {codeChallenge}");import (
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"fmt"
)
random := make([]byte, 48)
rand.Read(random)
codeVerifier := base64.RawURLEncoding.EncodeToString(random) // 64 chars
sum := sha256.Sum256([]byte(codeVerifier))
codeChallenge := base64.RawURLEncoding.EncodeToString(sum[:])
fmt.Println("verifier: ", codeVerifier)
fmt.Println("challenge:", codeChallenge)function b64url(string $bytes): string {
return rtrim(strtr(base64_encode($bytes), '+/', '-_'), '=');
}
$codeVerifier = b64url(random_bytes(48)); // 64 chars
$codeChallenge = b64url(hash('sha256', $codeVerifier, true));
echo "verifier: $codeVerifier\n";
echo "challenge: $codeChallenge\n";use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
use rand::RngCore;
use sha2::{Digest, Sha256};
let mut random = [0u8; 48];
rand::thread_rng().fill_bytes(&mut random);
let code_verifier = URL_SAFE_NO_PAD.encode(random); // 64 chars
let code_challenge = URL_SAFE_NO_PAD.encode(Sha256::digest(code_verifier.as_bytes()));
println!("verifier: {code_verifier}");
println!("challenge: {code_challenge}");Bewahren Sie den Verifier für Schritt 3 auf. Erzeugen Sie außerdem einen zufälligen state (und, falls Sie ihn prüfen, eine nonce), um sich gegen Cross-Site-Request-Forgery und Replay-Angriffe zu schützen.
2. Benutzer an den Authorization-Endpunkt schicken
Öffnen Sie diese URL im Browser (hier zur Lesbarkeit umbrochen):
https://<your-domain>/authorize
?response_type=code
&client_id=<your-client-id>
&redirect_uri=https://app.example.com/callback
&scope=openid%20profile%20email%20offline_access
&state=<random-state>
&code_challenge=<CODE_CHALLENGE>
&code_challenge_method=S256scopemussopenidenthalten. Ergänzen Sieprofileundemailfür die Standard-Claims sowieoffline_access, wenn Sie ein Refresh-Token möchten.- Nach der Anmeldung des Benutzers leitet die Plattform weiter an
https://app.example.com/callback?code=<one-time-code>&state=<random-state>. - Prüfen Sie, ob der zurückgegebene
statemit dem gesendeten übereinstimmt, bevor Sie fortfahren.
3. Code gegen Tokens tauschen
Senden Sie den Code und den PKCE-Verifier per POST an den Token-Endpunkt.
Bei einem Confidential Client authentifizieren Sie sich mit dem Client-Secret (hier gezeigt: HTTP Basic):
curl -X POST https://<your-domain>/oauth/token \
-u '<your-client-id>:<your-client-secret>' \
-d grant_type=authorization_code \
-d redirect_uri=https://app.example.com/callback \
-d code=<one-time-code> \
-d code_verifier=$CODE_VERIFIERBei einem Public Client (ohne Secret) senden Sie die client_id als Formularfeld und stützen sich auf PKCE:
curl -X POST https://<your-domain>/oauth/token \
-d grant_type=authorization_code \
-d client_id=<your-client-id> \
-d redirect_uri=https://app.example.com/callback \
-d code=<one-time-code> \
-d code_verifier=$CODE_VERIFIERDie Antwort enthält die Tokens:
{
"access_token": "<jwt>",
"id_token": "<jwt>",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "<token>",
"scope": "openid profile email offline_access"
}Ein refresh_token ist nur enthalten, wenn Sie offline_access angefordert haben und die Anwendung eines erhalten darf.
4. ID-Token validieren
Das ID-Token ist ein JWT, das belegt, wer sich angemeldet hat. Validieren Sie es, bevor Sie ihm vertrauen:
- Verifizieren Sie die Signatur gegen die Signaturschlüssel der Plattform unter
/.well-known/jwks. - Prüfen Sie, dass
isszu Ihrer Instanz passt,audzu Ihrer Client-ID und dass das Token nicht abgelaufen ist (exp). - Wenn Sie eine
noncegesendet haben, prüfen Sie, dass sie übereinstimmt.
Der sub-Claim ist der stabile Benutzeridentifikator; die Scopes profile und email ergänzen Claims wie name und email.
5. UserInfo aufrufen (optional)
Für Claims über das ID-Token hinaus rufen Sie den UserInfo-Endpunkt mit dem Access-Token auf:
curl https://<your-domain>/userinfo \
-H 'Authorization: Bearer <access_token>'6. Benutzer abmelden (optional)
Um die Sitzung zu beenden, schicken Sie den Benutzer an den End-Session-Endpunkt:
https://<your-domain>/logout
?id_token_hint=<id_token>
&post_logout_redirect_uri=https://app.example.com/Registrieren Sie die post_logout_redirect_uri zuvor an Ihrer Anwendung, auf dieselbe Weise wie eine Redirect-URI.
Fehlerbehebung
redirect_uristimmt nicht überein. Dieredirect_uriin den Schritten 2 und 3 muss untereinander identisch sein und einem an der Anwendung registrierten Wert entsprechen, verglichen Zeichen für Zeichen (Schema, Host, Port, Pfad, abschließender Schrägstrich).invalid_grantam Token-Endpunkt. Der Code ist nur einmal verwendbar und kurzlebig; fordern Sie einen neuen an. Dieser Fehler erscheint auch, wenn dercode_verifiernicht zur gesendetencode_challengepasst.invalid_client. Die Client-Authentifizierung ist falsch: Ein Confidential Client muss sein Secret senden; ein Public Client darf das nicht und muss als Public Client (PKCE) registriert sein.
Nächste Schritte
- Node/Express-Backend macht dasselbe mit einer Bibliothek.
- Python/Flask-Backend macht dasselbe in Python.
- React-Single-Page-App macht es im Browser.