Saltar al contenido principal

Troubleshooting

Errores en el Credential Issuer​

401 Unauthorized — "invalid token"​

Síntoma: La llamada al Issuer devuelve {"error": "Unauthorized", "detail": "invalid token"}.

Causa: El token Bearer incluido en la cabecera Authorization no es válido, ha expirado, o la clave pública usada para verificarlo no coincide con la configurada en KEYCLOAK_JWKS_URI.

Solución:

  1. Comprueba que el token no ha expirado (exp claim en el payload JWT).
  2. Verifica que KEYCLOAK_JWKS_URI apunta al endpoint JWKS del realm Keycloak correcto para el entorno que estás usando.
  3. Obtén un nuevo token del realm de Keycloak y reintenta la llamada.

400 Bad Request — "Missing required data or invalid powers"​

Síntoma: La llamada a POST /issuance/representative o POST /issuance/employee devuelve un error sobre claims faltantes en el token.

Causa: El token de Keycloak no incluye todos los claims necesarios. El Issuer requiere al menos: organization_identifier, organization, user_identifier, email.

Solución:

  1. Comprueba que el cliente Keycloak tiene configurados los mappers de atributos que incluyen organization_identifier, organization, user_identifier y email en el access_token.
  2. Verifica que el usuario autenticado en Keycloak tiene esos atributos rellenos en su perfil o que el IDP de credenciales los mapea correctamente desde la VC presentada.

400 Bad Request — "The requested powers are not authorized for the organization"​

Síntoma: Los poderes enviados en el body del POST son rechazados por el Issuer.

Causa: Los poderes solicitados en el body de la petición no están autorizados por la Management API de ISBE para la organización del solicitante.

Solución:

  1. Consulta a ISBE los poderes autorizados para tu organización.
  2. Asegúrate de que el body de la petición solo incluye poderes que formen un subconjunto de los autorizados.
  3. Verifica que MANAGEMENT_API_URL en la configuración del Issuer apunta al entorno correcto.

El QR expira antes de que el usuario lo escanee​

Síntoma: El usuario intenta escanear el QR con su wallet y se devuelve un error de código expirado.

Causa: El tiempo de expiración del preauth code (QR_EXPIRATION_TIME, por defecto 300 segundos) ha transcurrido.

Solución:

  1. El usuario debe solicitar una nueva emisión de credencial para obtener un QR fresco.
  2. Si el problema es recurrente, el administrador del Issuer puede aumentar el valor de QR_EXPIRATION_TIME en la configuración.

La credencial aparece como pending indefinidamente​

Síntoma: El registro IssuedCredential en la base de datos permanece en estado pending aunque el usuario haya escaneado el QR.

Causa posible 1: No se recibió la confirmación de emisión al endpoint /issuance/notifications del Issuer (error de red, timeout, API Key incorrecta).

Causa posible 2: El servicio detectó un error al verificar la VC (firma inválida, VC expirada, emisor no acreditado en el TIR).

Solución:

  1. Contacta con el soporte de ISBE para revisar los logs del servicio de emisión.
  3. Si la VC presentada tiene problemas criptográficos, el usuario debe obtener una nueva credencial del emisor correspondiente.

Errores en el Credential IDP​

El usuario ve "FAILED" en la pantalla del QR​

Síntoma: El polling devuelve {"status": "FAILED"} y la página muestra un error al usuario.

Causa: El servicio de verificación rechazó la credencial presentada por el wallet. Posibles motivos:

  • La VC presentada ha expirado (validUntil superado).
  • La firma de la VC no es válida (clave rotada o corrupta en el DID Document).
  • El emisor de la VC no está acreditado en el TIR del entorno al que se intenta acceder.
  • El tipo de VC presentado no coincide con el OID_CREDENTIAL configurado en el IDP (IsbePortalLearCredential por defecto).

Solución:

  1. Comprueba que la VC del wallet está vigente y fue emitida por el Issuer ISBE del entorno correcto.
  2. Verifica que el DID del emisor de la VC tiene una acreditación activa en el TIR consultando GET <TIR>/v1/issuers/<DID>/attributes.
  3. Si la VC está caducada, solicita una nueva al Credential Issuer.

POST /accounts/token devuelve error de OIDC​

Síntoma: Keycloak no puede intercambiar el código de autorización por tokens: el endpoint /accounts/token devuelve un error.

Causa: La redirect_uri de Keycloak no coincide con las Redirect URIs configuradas en el cliente OIDC del IDP, o el client_id / client_secret son incorrectos.

Solución:

  1. Verifica la configuración del IDP en Keycloak: la Redirect URI debe ser https://<keycloak-domain>/broker/<alias-idp>/endpoint.
  2. Verifica que el cliente OIDC en el panel de administración del IDP tiene registrada exactamente esa URL en Redirect URIs.
  3. Comprueba que Client ID y Client Secret (si aplica) coinciden entre Keycloak y el IDP.

Los atributos del usuario no llegan correctamente a Keycloak​

Síntoma: El token de Keycloak no incluye los atributos esperados (p. ej. organization_identifier no está presente).

Causa: Los mappers del scope activo en el IDP no están correctamente configurados, o los mappers de Keycloak para atributos del IDP externo no están definidos.

Solución:

  1. Revisa los mappers del scope en el panel de administración del IDP (/admin/). La sintaxis correcta es clave = ruta.al.campo (p. ej. organization_identifier = credentialSubject.mandate.mandator.organizationIdentifier).
  2. En Keycloak, revisa la sección "Mappers" del IDP externo: debe haber un mapper por cada atributo que quieras que llegue al access token final.

El QR no se muestra o la página carga indefinidamente​

Síntoma: Al redirigir a la pantalla de QR del IDP, la página no carga correctamente o muestra un error de servidor.

Causa posible 1: El servicio de verificación no está disponible.

Causa posible 2: Error en la base de datos del IDP (DATABASE_URL incorrecta o PostgreSQL no accesible).

Solución:

  1. Verifica el endpoint GET /health del IDP: debe devolver estado de salud de la BD.
  2. Contacta con el soporte de ISBE si el problema persiste.
  3. Revisa los logs del IDP buscando excepciones en la inicialización de la sesión de verificación.

Errores de esquema y validación​

La VC no supera la validación de schema​

Síntoma: Al presentar una VC, el servicio de verificación devuelve un error indicando que la VC no es válida según el JSON Schema.

Causa: Algún campo de la VC no cumple los requisitos del schema (credentialSchema.id). Causas frecuentes:

  • mandate.power es un array vacío (se requiere al menos un elemento).
  • mandate.mandatee.employeeId está ausente (campo obligatorio).
  • @context no incluye https://www.w3.org/ns/credentials/v2 como primer elemento.
  • El array type no incluye todos los tipos de la cadena de herencia.

Solución:

  1. Descarga el JSON Schema del campo credentialSchema.id de la VC.
  2. Valida el payload del JWT de la VC contra ese schema usando una herramienta de validación JSON Schema (p. ej. ajv, jsonschema).
  3. Corrige los campos que no cumplen el schema y reemite la credencial.

termsOfUse.id apunta a una acreditación inexistente​

Síntoma: El verificador indica que no puede encontrar la acreditación del emisor en el TIR.

Causa: El campo termsOfUse.id de la VC apunta a una URL del TIR que no existe o corresponde a un entorno distinto.

Solución:

  1. Consulta el TIR del entorno correcto (GET <TIR>/v1/issuers/<DID>/attributes) para obtener el hash de la acreditación vigente.
  2. Reemite la credencial con el termsOfUse.id correcto.
  3. Si la acreditación del emisor no aparece en el TIR, contacta con el equipo ISBE para regularizar la situación.