Skip to main content

​
Resumen

La autenticación con JWT permite llamar a la API de Corgea mediante tokens Bearer emitidos directamente por el proveedor de identidad (IdP), como Microsoft Entra ID u Okta, en lugar de utilizar un token de API de Corgea asociado a un usuario. Este es el método recomendado para integraciones entre sistemas —como pipelines de CI/CD, escáneres automatizados o herramientas internas— cuando necesitas:
  • Asociar los tokens a una entidad de servicio o un registro de aplicación, en lugar de a una cuenta de usuario concreta
  • Controlar la vigencia y el ámbito del token desde el IdP
  • Revocar tokens de forma centralizada desde el IdP sin modificar Corgea
Los tokens de API de Corgea siempre están asociados a usuarios individuales. Si un usuario deja la organización o se desactiva su cuenta, cualquier automatización que utilice su token deja de funcionar. La autenticación JWT elimina esta dependencia de las cuentas de usuario.

​
Cómo funciona

  1. Tu sistema solicita un token de acceso al IdP mediante las credenciales del cliente (ID y secret del cliente).
  2. El IdP devuelve un JWT firmado que contiene claims como iss (emisor) y aud (audiencia).
  3. Tu sistema envía el token como token Bearer en la cabecera Authorization al llamar a la API de Corgea.
  4. Corgea valida la firma del token con las claves públicas del IdP y comprueba que los claims iss, aud y appid/cid coincidan con la configuración registrada.

​
Utilizar JWT con la CLI de Corgea

Puedes usar un token de acceso JWT directamente con el flujo de inicio de sesión de la CLI:
O configúralo mediante la variable de entorno:

​
Configurar la autenticación JWT en Corgea

Navega a Configuración → Integraciones y haz clic en + Añadir en la sección de autenticación de JWT.
Añadir formulario de configuración de autenticación JWT en Corgea
Rellena los siguientes campos:
Utiliza jwt.io para decodificar un token de acceso del IdP y comprobar los valores exactos de iss, aud y appid/cid antes de completar el formulario.
Valores específicos de cada proveedor:
  • Emisor de Entra ID: https://sts.windows.net/{your-tenant-id}/
  • Audiencia de Entra ID: el URI del ID de aplicación de tu aplicación (por ejemplo, api://{client_id}) — establecida mediante Expose an API en Entra
  • Emisor de Okta: https://{domain}.okta.com/oauth2/default
  • Audiencia de Okta: api://default (o la audiencia del servidor de autorización personalizado)

​
Configuración de ID Microsoft Entra

1

Registra una aplicación en Entra

En Azure Portal, ve a Microsoft Entra ID → Registros de aplicaciones → Nuevo registro. Asigna a la aplicación un nombre descriptivo, como corgea-cicd, y regístrala.
2

Expone una API y establece el URI del ID de la aplicación

Ve a Exponer una API en el registro de la aplicación. Establece o confirma el URI del ID de aplicación; este valor se convierte en el claim aud de los tokens emitidos para la aplicación.
Expose an API en Microsoft Entra
Copia el URI del ID de la aplicación, por ejemplo api://5d63c8f0-c9a8-4195-90ee-a9e27e4510b8. Lo introducirás como Audiencia en Corgea.
3

Crear un secreto para el cliente

Ve a Certificados y secretos → Nuevo secreto de cliente. Añade una descripción y establece una fecha de caducidad, luego haz clic en Añadir.
Añadir un secreto de cliente en Microsoft Entra
Copia inmediatamente el Valor del secret, pues solo se muestra una vez. Guárdalo de forma segura, por ejemplo en el almacén de secrets de CI/CD.
4

Solicitar un token de acceso

Tu sistema solicita un token a Entra usando el flujo de credenciales del cliente:
La respuesta contiene un access_token. Envíalo como token Bearer al llamar a Corgea:
Sustituye https://www.corgea.app por https://your_instance.corgea.app si utilizas un despliegue privado.
5

Registrar la configuración en Corgea

En el formulario Añadir configuración de autenticación JWT de Corgea, introduce:
  • Emisor: https://sts.windows.net/{your-tenant-id}/
  • Audiencia: el URI del ID de la aplicación del Paso 2 (por ejemplo, api://5d63c8f0-...)
  • ID de aplicación permitido: el ID de la aplicación (cliente) desde el registro de tu aplicación
Haz clic en Añadir para guardar.

​
Pruebas con Postman

Si prefieres una interfaz gráfica a curl, puedes probar directamente en Postman la solicitud del token y la llamada a la API. Importar un comando de curl Postman puede convertir cualquiera de los comandos curl anteriores en una solicitud. Haz clic en Importar en la esquina superior izquierda y pega el comando; Postman completará automáticamente el método, la URL, las cabeceras y el cuerpo.
Importando un comando de curl en Postman
Solicitar un token de acceso Rellena tenant-id, client_id, client_secret y scope en los campos del cuerpo y envía la solicitud. Después, copia el valor access_token de la respuesta.
Solicitar un token de acceso en Postman usando las credenciales del cliente
Llama a la API de Corgea con el token Crea una solicitud al endpoint de Corgea. En la pestaña Autorización, selecciona Token Bearer como tipo y pega el access_token.
Llamando a la API de Corgea con un token portador en Postman
Si tu empresa restringe el acceso saliente a la red, quizá debas configurar un proxy. En Postman, ve a Configuración → Proxy y añade el proxy corporativo. Para curl, establece la variable de entorno HTTPS_PROXY o pasa --proxy https://your-proxy:port.

​
Verificar el token

Utiliza jwt.io para decodificar un token de acceso antes de configurar Corgea. Pega el token en el depurador e inspecciona el payload decodificado para confirmar los valores de iss, aud y appid.
Descifrar un token JWT en jwt.io para verificar las reclamaciones de ISS y AUD
Los campos resaltados aud e iss son exactamente los que Corgea comprueba al validar las solicitudes entrantes.

​
Resolución de problemas

  • 401 No autorizado: Decodifica el token en jwt.io y confirma que iss, aud y appid coincidan exactamente con los valores de la configuración de autenticación JWT de Corgea.
  • Token rechazado tras la rotación: Si has rotado el secret del cliente, actualízalo en el entorno de CI/CD. No es necesario modificar la configuración de Corgea, porque valida los claims del token, no el secret.
  • Varios entornos: Crea una configuración de autenticación JWT distinta en Corgea para cada aplicación o entorno —por ejemplo, staging y producción— mediante registros de aplicación con ID de cliente diferentes.

​
Problemas de conectividad de red

Si la solicitud de token o la llamada a la API falla con un error de conexión, utiliza estos comandos para investigar si un firewall o proxy está bloqueando el tráfico.
Si falla la prueba de conexión TCP o traceroute se detiene en un salto interno, pide al equipo de redes o seguridad que permita el tráfico HTTPS saliente (puerto 443) hacia login.microsoftonline.com y www.corgea.app.