Endpoints OAuth2/OIDC

Los siguientes endpoints provienen del discovery OIDC del proveedor de identidad.

Menú de rutas

Grupo	Método	Ruta	Uso principal
Autorización	GET	/auth/public/authorize/	Iniciar flujo OAuth2/OIDC (authorization code).
Tokens	POST	/oauth2/token	Intercambiar code por tokens o renovar con refresh_token.
UserInfo	GET	/oidc/userinfo	Obtener claims del usuario autenticado.
Introspección	POST	/oauth2/introspect	Validar estado y metadatos de un access token.
Revocación	POST	/oauth2/revoke	Revocar access token o refresh token.
Claves públicas	GET	/.well-known/jwks.json	Obtener llaves públicas para verificación de JWT.
Cierre de sesión	GET/POST	/auth/logout/client	Finalizar sesión en el proveedor de identidad.

Flujo de integración de login (Authorization Code + PKCE)

Paso 1: redirección a autorización

Endpoint: GET /auth/public/authorize/

Parámetros mínimos:

• response_type=code
• client_id=<CLIENT_ID>
• redirect_uri=<URI_REGISTRADA>
• scope=openid profile email
• state=<ALEATORIO>
• code_challenge=<PKCE_CHALLENGE>
• code_challenge_method=S256

Ejemplo:

BASE_URL_IDP/auth/public/authorize/?response_type=code&client_id=mi_cliente&redirect_uri=https%3A%2F%2Fapp.midominio.com%2Fauth%2Fcallback&scope=openid%20profile%20email&state=RANDOM123&code_challenge=abc123...&code_challenge_method=S256

Paso 2: intercambio de código por tokens

Endpoint: POST /oauth2/token

Content-Type esperado: application/x-www-form-urlencoded

Payload base:

• grant_type=authorization_code
• code=<AUTHORIZATION_CODE>
• redirect_uri=<URI_REGISTRADA>
• client_id=<CLIENT_ID>
• code_verifier=<PKCE_VERIFIER>

Ejemplo:

curl -X POST 'BASE_URL_IDP/oauth2/token' \
	-H 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'grant_type=authorization_code' \
	--data-urlencode 'client_id=mi_cliente' \
	--data-urlencode 'code=AUTH_CODE' \
	--data-urlencode 'redirect_uri=https://app.midominio.com/auth/callback' \
	--data-urlencode 'code_verifier=PKCE_VERIFIER'

Paso 3: obtención de identidad de usuario

Endpoint: GET /oidc/userinfo

Header:

• Authorization: Bearer <access_token>

Ejemplo:

curl 'BASE_URL_IDP/oidc/userinfo' \
	-H 'Authorization: Bearer ACCESS_TOKEN'

Paso 4: renovación de token

Endpoint: POST /oauth2/token

Payload:

• grant_type=refresh_token
• refresh_token=<REFRESH_TOKEN>
• client_id=<CLIENT_ID>

Paso 5: introspección (backend a backend)

Endpoint: POST /oauth2/introspect

Uso recomendado:

• Validar tokens cuando no se usa validación local JWT.
• Obtener estado active y metadatos del token.

Paso 6: revocación y logout

• Revocación de token: POST /oauth2/revoke
• Logout del proveedor: /auth/logout/client

Recomendación de cierre de sesión:

1. Invalidar sesión local en tu aplicación.
2. Revocar token/refresh token cuando aplique.
3. Redirigir a endpoint de logout del IdP.

Rutas absolutas

• BASE_URL_IDP/auth/public/authorize/
• BASE_URL_IDP/oauth2/token
• BASE_URL_IDP/oidc/userinfo
• BASE_URL_IDP/oauth2/introspect
• BASE_URL_IDP/oauth2/revoke
• BASE_URL_IDP/.well-known/jwks.json
• BASE_URL_IDP/auth/logout/client

Flujo recomendado

1. Implementar authorization_code con PKCE.
2. Mantener secretos y refresh tokens fuera del frontend público.
3. Validar state y nonce para mitigar replay/CSRF.
4. Verificar firma y claims de tokens cuando aplique.
5. Aplicar rotación y revocación de tokens en logout.

Tutorial rápido con oauth2c en Linux

oauth2c permite probar flujos OAuth2/OIDC desde terminal sin escribir una aplicación de prueba completa. En este módulo puede usarse para validar los dos grant types que expone el discovery:

• authorization_code
• client_credentials

Instalación en Linux

go install github.com/cloudentity/oauth2c@latest

Variables de entorno sugeridas

export BASE_URL_IDP='https://backend.idp-test.eje.gob.bo'
export CLIENT_ID='mi_cliente'
export CLIENT_SECRET='mi_secreto'

Flujo 1: authorization_code

Usa este flujo para probar login interactivo de usuario con navegador.

Requisitos previos:

• El redirect_uri debe estar registrado para el cliente.
• Para pruebas locales, una opción común es http://localhost:9876/callback.

oauth2c "$BASE_URL_IDP" \
	--client-id "$CLIENT_ID" \
	--client-secret "$CLIENT_SECRET" \
	--response-types code \
	--response-mode query \
	--grant-type authorization_code \
	--auth-method client_secret_basic \
	--redirect-url http://localhost:9876/callback \
	--scopes openid,profile,email

Qué validar:

1. Que se abra el navegador y el IdP complete el login.
2. Que oauth2c reciba el callback y muestre el access_token.
3. Que el token permita consultar GET /oidc/userinfo o las APIs que correspondan al scope solicitado.

Flujo 2: client_credentials

Usa este flujo para probar integración máquina a máquina sin usuario final.

oauth2c "$BASE_URL_IDP" \
	--client-id "$CLIENT_ID" \
	--client-secret "$CLIENT_SECRET" \
	--grant-type client_credentials \
	--auth-method client_secret_basic \
	--scopes <SCOPES_AUTORIZADOS_PARA_ESE_CLIENTE>

Qué validar:

1. Que el proveedor emita un access_token sin interacción de usuario.
2. Que el token sea aceptado por el recurso para el cual fue emitido.
3. Que los scopes del cliente coincidan con los permitidos por la configuración del IdP.

Recomendaciones prácticas

• Empieza con authorization_code si quieres simular el recorrido de un usuario.
• Usa client_credentials solo cuando estés validando un cliente de servicio.
• Si el cliente no está registrado o el redirect_uri no coincide, el flujo fallará antes de obtener tokens.
• Si necesitas un entorno distinto, cambia solo BASE_URL_IDP.