Skip to Content

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

  1. Ihre App leitet den Browser mit einer PKCE-Challenge an den Authorization-Endpunkt weiter.
  2. Der Benutzer meldet sich an; die Plattform leitet mit einem einmaligen code zurück an Ihre Redirect-URI.
  3. Ihre App tauscht den code (plus PKCE-Verifier) am Token-Endpunkt gegen ein ID-Token und ein Access-Token.
  4. 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=S256
  • scope muss openid enthalten. Ergänzen Sie profile und email für die Standard-Claims sowie offline_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 state mit 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_VERIFIER

Bei 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_VERIFIER

Die 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 iss zu Ihrer Instanz passt, aud zu Ihrer Client-ID und dass das Token nicht abgelaufen ist (exp).
  • Wenn Sie eine nonce gesendet 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_uri stimmt nicht überein. Die redirect_uri in 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_grant am Token-Endpunkt. Der Code ist nur einmal verwendbar und kurzlebig; fordern Sie einen neuen an. Dieser Fehler erscheint auch, wenn der code_verifier nicht zur gesendeten code_challenge passt.
  • 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

Auf dieser Seite