Skip to Content

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.

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 :

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

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) :

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 :

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 :

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

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

Sur cette page