Introducción

Base URL por entorno

En este módulo se usa BASE_URL_IDP como referencia común para todos los endpoints.

• Entorno de test: https://backend.idp-test.eje.gob.bo
• Entorno de producción: https://backend.idp.eje.gob.bo

Regla de uso:

• Reemplazar BASE_URL_IDP por la URL del entorno objetivo (test o producción).

Esta guía explica cómo integrar autenticación de usuarios con OAuth2 y OpenID Connect (OIDC) contra:

• Discovery OIDC: BASE_URL_IDP/.well-known/openid-configuration
• Documentación API: BASE_URL_IDP/api/docs

Cuándo usar OAuth2 y cuándo OIDC

• Usa OAuth2 cuando tu objetivo principal es autorización para consumir una API con access_token.
• Usa OIDC cuando, además de autorización, necesitas identidad de usuario autenticado (id_token y/o userinfo).

En login de aplicaciones web, normalmente se usan ambos: OAuth2 para tokens de acceso y OIDC para identidad.

Flujo recomendado para login

Para aplicaciones web y SPA con backend, se recomienda:

1. authorization_code.
2. PKCE (S256).
3. Intercambio de código en backend o BFF (evitar exponer secretos en frontend).
4. Sesión de aplicación basada en cookie segura (HttpOnly, Secure, SameSite).

Roles del protocolo

• Authorization Server / IdP: emite tokens y autentica usuarios.
• Client: tu aplicación (frontend, backend o BFF).
• Resource Server: APIs protegidas que validan tokens.
• Resource Owner: usuario final.

Datos que debe definir el equipo integrador

• scope mínimo requerido (openid, profile, email y, si aplica, scopes de directorio oficiales).

Referencias normativas

• OAuth 2.0: RFC 6749.
• PKCE: RFC 7636.
• OpenID Connect Core 1.0.
• OpenID Connect Discovery 1.0.