# 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](https://dts-identity.com/de/docs/quickstarts.md#before-you-start) 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:

```bash tab="Shell" tab-group="lang"
# 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"
```

```js tab="Node.js" tab-group="lang"
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);
```

```python tab="Python" tab-group="lang"
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)
```

```java tab="Java" tab-group="lang"
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);
```

```csharp tab="C#" tab-group="lang"
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}");
```

```go tab="Go" tab-group="lang"
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)
```

```php tab="PHP" tab-group="lang"
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";
```

```rust tab="Rust" tab-group="lang"
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):

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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

- [Node/Express-Backend](https://dts-identity.com/de/docs/quickstarts/node-express.md) macht dasselbe mit einer Bibliothek.
- [Python/Flask-Backend](https://dts-identity.com/de/docs/quickstarts/python-flask.md) macht dasselbe in Python.
- [React-Single-Page-App](https://dts-identity.com/de/docs/quickstarts/react-spa.md) macht es im Browser.
