Skip to Content

OpenID Connect (Authorization Code + PKCE)

El flujo OIDC Authorization Code con PKCE de principio a fin, con HTTP puro y curl, para que entienda cada paso antes de recurrir a una biblioteca.

Esta guía recorre el flujo Authorization Code con PKCE sin usar nada más que HTTP, de modo que pueda ver exactamente qué envía y qué recibe cada paso. Las guías de Node y React hacen lo mismo con una biblioteca; lea esta primero.

Asegúrese de haber registrado una aplicación y una redirect URI como se describe en Antes de empezar.

El flujo de un vistazo

  1. Su aplicación redirige el navegador al endpoint de autorización con un challenge PKCE.
  2. El usuario inicia sesión; la plataforma redirige de vuelta a su redirect URI con un code de un solo uso.
  3. Su aplicación canjea el code (más el verifier PKCE) en el endpoint de token por un ID token y un access token.
  4. Su aplicación valida el ID token y, opcionalmente, llama al endpoint UserInfo.

1. Crear un verifier y un challenge PKCE

Genere un code verifier aleatorio y derive de él su 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}");

Conserve el verifier para el paso 3. Genere además un state aleatorio (y una nonce, si la comprueba) para protegerse frente a cross-site request forgery y ataques de repetición.

2. Enviar al usuario al endpoint de autorización

Abra esta URL en el navegador (aquí con saltos de línea para facilitar la lectura):

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 debe incluir openid. Añada profile y email para los claims estándar, y offline_access si quiere un refresh token.
  • Tras el inicio de sesión del usuario, la plataforma redirige a https://app.example.com/callback?code=<one-time-code>&state=<random-state>.
  • Compruebe que el state devuelto coincide con el que envió antes de continuar.

3. Canjear el código por tokens

Envíe por POST el código y el verifier PKCE al endpoint de token.

En un cliente confidential, autentíquese con el client secret (aquí se muestra 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

En un cliente public (sin secreto), envíe el client_id como campo de formulario y apóyese en 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 respuesta contiene los tokens:

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

Solo se incluye un refresh_token si ha solicitado offline_access y la aplicación puede recibir uno.

4. Validar el ID token

El ID token es un JWT que demuestra quién ha iniciado sesión. Valídelo antes de confiar en él:

  • Verifique la firma frente a las claves de firma de la plataforma en /.well-known/jwks.
  • Compruebe que iss coincide con su instancia, que aud coincide con su client ID y que el token no ha caducado (exp).
  • Si envió una nonce, compruebe que coincide.

El claim sub es el identificador estable del usuario; los scopes profile y email añaden claims como name y email.

5. Llamar a UserInfo (opcional)

Para obtener claims más allá del ID token, llame al endpoint UserInfo con el access token:

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

6. Cerrar la sesión del usuario (opcional)

Para finalizar la sesión, envíe al usuario al endpoint de end session:

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

Registre antes la post_logout_redirect_uri en su aplicación, igual que registra una redirect URI.

Solución de problemas

  • La redirect_uri no coincide. La redirect_uri de los pasos 2 y 3 debe ser idéntica entre sí y coincidir con un valor registrado en la aplicación, comparado carácter a carácter (esquema, host, puerto, ruta, barra final).
  • invalid_grant en el endpoint de token. El código es de un solo uso y de vida corta; solicite uno nuevo. Este error también aparece si el code_verifier no se corresponde con el code_challenge que envió.
  • invalid_client. La autenticación del cliente es incorrecta: un cliente confidential debe enviar su secreto; un cliente public no debe hacerlo y debe estar registrado como cliente public (PKCE).

Siguientes pasos

En esta página