# OpenID Connect (Authorization Code + PKCE)

Le flux OIDC Authorization Code avec PKCE de bout en bout, en HTTP brut et avec curl, pour comprendre chaque étape avant de recourir à une bibliothèque.

Ce guide parcourt le **flux Authorization Code avec PKCE** en n'utilisant rien d'autre que HTTP, afin que vous voyiez exactement ce que chaque étape envoie et reçoit. Les guides Node et React font la même chose avec une bibliothèque ; lisez celui-ci d'abord.

Assurez-vous d'avoir enregistré une application et une redirect URI comme décrit sous [Avant de commencer](https://dts-identity.com/fr/docs/quickstarts.md#before-you-start).

## Le flux en un coup d'œil

1. Votre application redirige le navigateur vers l'**endpoint d'autorisation**, avec une challenge PKCE.
2. L'utilisateur se connecte ; la plateforme redirige vers votre **redirect URI** avec un `code` à usage unique.
3. Votre application échange le `code` (accompagné du verifier PKCE) sur le **token endpoint** contre un ID token et un access token.
4. Votre application valide l'ID token et, facultativement, appelle l'**endpoint UserInfo**.

## 1. Créer un verifier et une challenge PKCE

Générez un **code verifier** aléatoire, puis dérivez-en la **code challenge** SHA-256 :

```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}");
```

Conservez le verifier pour l'étape 3. Générez également un `state` aléatoire (et, si vous le vérifiez, un `nonce`) pour vous protéger contre la falsification de requête intersites et le rejeu.

## 2. Envoyer l'utilisateur vers l'endpoint d'autorisation

Ouvrez cette URL dans le navigateur (découpée ici sur plusieurs lignes pour la lisibilité) :

```
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` doit contenir `openid`. Ajoutez `profile` et `email` pour les claims standard, et `offline_access` si vous souhaitez un refresh token.
- Après la connexion de l'utilisateur, la plateforme redirige vers
  `https://app.example.com/callback?code=<one-time-code>&state=<random-state>`.
- **Vérifiez que le `state` renvoyé correspond** à celui que vous avez envoyé avant de continuer.

## 3. Échanger le code contre des tokens

Envoyez le code et le verifier PKCE en POST au token endpoint.

Pour un client **confidentiel**, authentifiez-vous avec le client secret (HTTP Basic ici) :

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

Pour un client **public** (sans secret), envoyez le `client_id` comme champ de formulaire et appuyez-vous sur 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
```

La réponse contient les tokens :

```json
{
  "access_token": "<jwt>",
  "id_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<token>",
  "scope": "openid profile email offline_access"
}
```

Un `refresh_token` n'est présent que si vous avez demandé `offline_access` et que l'application est autorisée à en recevoir un.

## 4. Valider l'ID token

L'**ID token** est un JWT qui prouve qui s'est connecté. Validez-le avant de lui faire confiance :

- Vérifiez la signature à l'aide des clés de signature de la plateforme, disponibles sous `/.well-known/jwks`.
- Contrôlez que `iss` correspond à votre instance, que `aud` correspond à votre client ID et que le token n'est pas expiré (`exp`).
- Si vous avez envoyé un `nonce`, vérifiez qu'il correspond.

Le claim `sub` est l'identifiant utilisateur stable ; les scopes `profile` et `email` ajoutent des claims tels que `name` et `email`.

## 5. Appeler UserInfo (facultatif)

Pour des claims au-delà de l'ID token, appelez l'endpoint UserInfo avec l'access token :

```bash
curl https://<your-domain>/userinfo \
  -H 'Authorization: Bearer <access_token>'
```

## 6. Déconnecter l'utilisateur (facultatif)

Pour mettre fin à la session, envoyez l'utilisateur vers l'endpoint end-session :

```
https://<your-domain>/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=https://app.example.com/
```

Enregistrez d'abord la `post_logout_redirect_uri` sur votre application, de la même manière que vous enregistrez une redirect URI.

## Dépannage

- **`redirect_uri` ne correspond pas.** La `redirect_uri` des étapes 2 et 3 doit être identique de part et d'autre et correspondre à une valeur enregistrée sur l'application, la comparaison se faisant caractère par caractère (schéma, hôte, port, chemin, barre oblique finale).
- **`invalid_grant` sur le token endpoint.** Le code est à usage unique et de courte durée ; demandez-en un nouveau. Cette erreur apparaît également lorsque le `code_verifier` ne correspond pas à la `code_challenge` envoyée.
- **`invalid_client`.** L'authentification du client est incorrecte : un client confidentiel doit envoyer son secret ; un client public ne doit pas le faire et doit être enregistré comme client public (PKCE).

## Étapes suivantes

- [Backend Node / Express](https://dts-identity.com/fr/docs/quickstarts/node-express.md) réalise la même chose avec une bibliothèque.
- [Backend Python / Flask](https://dts-identity.com/fr/docs/quickstarts/python-flask.md) fait de même en Python.
- [Application monopage React](https://dts-identity.com/fr/docs/quickstarts/react-spa.md) le fait dans le navigateur.
