API del Credential IDP

Base URL:

Entorno	URL
Producción	https://identity-credentials-idp.pro.cloud-w.envs.redisbe.com
Preproducción	https://identity-credentials-idp.pre.cloud-w.envs.redisbe.com

Documentación interactiva (Swagger): GET <base-url>/swagger

Endpoints de infraestructura

GET /health

Devuelve el estado de salud del servicio, incluyendo la conexión a la base de datos.

Autenticación: ninguna.

Respuesta 200 OK:

{
  "status": "ok",
  "db": "connected"
}

---

GET /metrics

Expone métricas en formato Prometheus para monitorización con Grafana.

Autenticación: ninguna.

---

Endpoints OIDC estándar

El IDP implementa el protocolo OpenID Connect completo. Los siguientes endpoints son estándar y deben usarse siguiendo la especificación OpenID Connect Core 1.0.

GET /.well-known/openid-configuration

Discovery document OIDC. Devuelve la configuración del IDP: endpoints, scopes soportados, algoritmos de firma, métodos de autenticación y tipos de tokens.

Autenticación: ninguna.

Respuesta 200 OK: JSON con los campos estándar del OIDC Discovery, incluyendo:

{
  "issuer": "https://identity-credentials-idp.pro.cloud-w.envs.redisbe.com",
  "authorization_endpoint": ".../accounts/authorize",
  "token_endpoint": ".../accounts/token",
  "userinfo_endpoint": ".../accounts/userinfo",
  "jwks_uri": ".../accounts/jwks",
  "scopes_supported": ["openid", "profile", "email", "openid-vp-lear"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "id_token_signing_alg_values_supported": ["RS256"],
  ...
}

Solo RS256 para id_token

El campo id_token_signing_alg_values_supported solo incluye RS256. Esto se debe a una limitación de la librería AllAuth que no soporta algoritmos EC para firma de id_token. Consulta el issue de AllAuth para el estado de esta limitación.

---

GET /accounts/authorize

Endpoint de autorización OAuth2. El cliente OIDC (Keycloak) redirige aquí al usuario para iniciar la autenticación.

Parámetros de query (estándar OAuth2/OIDC):

Parámetro	Obligatorio	Descripción
client_id	✅	ID del cliente registrado en el IDP.
redirect_uri	✅	URI de retorno del cliente (debe coincidir con la configuración del cliente en el IDP).
response_type	✅	Debe ser code.
scope	✅	Scopes solicitados (p. ej. openid profile email openid-vp-lear).
state	✅ (recomendado)	Valor opaco para prevención CSRF.
nonce	❌	Valor para prevenir ataques de replay en id_token.

Respuesta: redirección al formulario de presentación del QR (interfaz web del IDP).

---

POST /accounts/token

Intercambia un código de autorización por access_token, id_token y refresh_token.

Autenticación: Basic Auth con client_id:client_secret o parámetros en body según la configuración del cliente.

Body (form-urlencoded):

grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&client_id=<client_id>

Respuesta 200 OK:

{
  "access_token": "<JWT>",
  "id_token": "<JWT firmado con RS256>",
  "refresh_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

El id_token incluye los claims mapeados según el scope y los mappers configurados para el scope activo. Ejemplo de claims para el scope openid-vp-lear:

{
  "sub": "empleado@empresa.es",
  "email": "empleado@empresa.es",
  "given_name": "Ana",
  "family_name": "López Fernández",
  "name": "Ana López Fernández",
  "preferred_username": "empleado@empresa.es",
  "organization": "Empresa S.A.",
  "organization_identifier": "ES-B12345678",
  "user_identifier": "E-00123",
  "power": "[{\"type\": \"domain\", \"domain\": \"ISBE\", ...}]"
}

Nota: el claim power se serializa como JSON string (resultado de str(power) en el mapper).

---

GET /accounts/userinfo

Devuelve los claims del usuario autenticado según los scopes solicitados en la autorización.

Autenticación: Authorization: Bearer <access_token>

Respuesta 200 OK: JSON con los claims correspondientes al access_token.

---

---

GET /idp/api/auth/requests

Consulta el estado de una sesión de verificación. El navegador del usuario hace polling a este endpoint mientras espera que el wallet complete la autenticación.

Autenticación: ninguna (endpoint público, accesible solo con el código de sesión).

Parámetros de query:

Parámetro	Tipo	Descripción
session	string	Código de sesión generado por el IDP al mostrar el QR.

Respuesta 200 OK:

{
  "status": "PENDING"
}

Los posibles valores de status son:

Valor	Descripción
PENDING	El wallet aún no ha presentado la credencial. El navegador debe seguir haciendo polling.
SUCCESS	La credencial fue verificada correctamente. El navegador debe completar el flujo OAuth2.
FAILED	La verificación falló (credencial inválida, expirada o emisor no acreditado).