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
- Su aplicación redirige el navegador al endpoint de autorización con un challenge PKCE.
- El usuario inicia sesión; la plataforma redirige de vuelta a su redirect URI con un
codede un solo uso. - Su aplicación canjea el
code(más el verifier PKCE) en el endpoint de token por un ID token y un access token. - 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=S256scopedebe incluiropenid. Añadaprofileyemailpara los claims estándar, yoffline_accesssi 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
statedevuelto 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_VERIFIEREn 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_VERIFIERLa 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
isscoincide con su instancia, queaudcoincide 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_urino coincide. Laredirect_uride 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_granten 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 elcode_verifierno se corresponde con elcode_challengeque 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
- Backend Node / Express hace esto mismo con una biblioteca.
- Backend Python / Flask hace lo mismo en Python.
- Aplicación de página única en React lo hace en el navegador.