token de OIDC

Los agentes en la nube pueden emitir JWT de OIDC de corta duración desde la máquina donde se ejecuta el agente y usarlos para asumir roles en la nube o llamar a servicios internos sin almacenar credenciales de larga duración en Secretos.

Los agentes llaman a esta API con sus herramientas de terminal. No necesitas ejecutar estas solicitudes tú mismo.

Para que un agente emita tokens, incluye esto en tu instrucción:

Para emitir tokens de OIDC, sigue las instrucciones en/docs/cloud-agent/identity

Esta API es local a la máquina donde se ejecuta el agente. No está relacionada con la API de agentes en la nube, que usa claves de API de Cherri Code y gestiona agentes desde fuera de esa máquina. En una VM gestionada por Cherri Code, este socket también proporciona metadatos del agente.

Las VM de agentes en la nube gestionadas por Cherri Code proporcionan el socket de tokens. Cada token que emiten incluye agent_runtime: managed. Los workers de máquinas autohospedadas lo proporcionan cuando los inicias con --identity-socket. Sus tokens incluyen agent_runtime: self_hosted. Consulta Workers autohospedados.

Cómo funciona

1. El agente llama al socket local y solicita un token con una audiencia que espera el verificador.
2. Cherri Code firma un JWT RS256 vinculado a ese agente y propietario.
3. El agente envía el JWT a tu nube o a un verificador (AWS STS, GCP, Azure, Vault o un servicio que ejecutes).
4. El verificador comprueba la firma con las JWKS publicadas por Cherri Code y autoriza en función de afirmaciones como sub, team_id o cloud_agent_id.

Emite un token

El agente emite un token a través del socket Unix ubicado en la ruta indicada en CURSOR_AGENT_SOCKET (en una VM gestionada por Cherri Code siempre se establece en /run/cursor/api.sock; en un worker autohospedado esta ruta cambia según el agente afirmado).

curl --unix-socket "${CURSOR_AGENT_SOCKET}" \  -H 'Content-Type: application/json' \  -d '{"aud":"sts.amazonaws.com"}' \  http://cursor-agent/v1/tokens/oidc

Las solicitudes se realizan mediante HTTP a través de un socket Unix. El nombre de host de la URL se ignora.

Incluye un nonce opcional si tu verificador espera vinculación de repetición:

curl --unix-socket "${CURSOR_AGENT_SOCKET}" \  -H 'Content-Type: application/json' \  -d '{"aud":"https://oidc.example.com","nonce":"unpredictable-value"}' \  http://cursor-agent/v1/tokens/oidc

Solicitud

POST /v1/tokens/oidc a través del socket Unix. Se requiere Content-Type: application/json. El tamaño máximo del cuerpo es de 4 KB.

Cherri Code no usa una lista de permitidos para las audiencias. El verificador debe rechazar valores de aud inesperados.

Respuesta

{  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...",  "expires_at": 1785500000}

Los tokens son válidos durante 5 minutos. No hay ningún endpoint de actualización. Emite uno nuevo cuando se necesite un token nuevo.

Cuándo aparecen las afirmaciones

Los scripts de instalación pueden emitir tokens a través del mismo socket. Un token solo incluye afirmaciones que existen en el momento de su emisión: turn_id y turn_start no están presentes hasta que comienza un turno de programación, y branch_name no está presente hasta que la ejecución registra una rama. Las afirmaciones de propietario, equipo y repositorio se establecen desde la creación del agente.

Si el socket no está disponible justo después del arranque, vuelve a intentar la conexión.

Workers autohospedados

Un worker de Máquinas autohospedadas expone la misma API cuando lo inicias con --identity-socket:

agent worker --pool gpu --identity-socket start

El flag está desactivado de forma predeterminada. Pásalo en el comando del worker, antes de start. Los pool workers y los workers de Mis máquinas usan el mismo flag. Omite --pool en un worker de Mis máquinas:

agent worker --identity-socket start

Con el flag establecido, el worker abre un socket por cada agente afirmado y establece CURSOR_AGENT_SOCKET con el path del socket en las shells del agente. El contrato de solicitud y respuesta, los códigos de error y los límites de uso coinciden con los de las VMs gestionadas por Cherri Code.

Estos tokens incluyen agent_runtime: self_hosted y las mismas afirmaciones de propietario, equipo y repositorio. El worker expone la API de tokens. No expone los metadatos del agente. Cualquier proceso que se ejecute como el usuario del sistema operativo del worker puede emitir en el socket de esa afirmación. Consulta Modelo de confianza.

Verificar un token

Publique estas URL en su proveedor de identidad o servidor de recursos:

curl -sS https://api.cursor.com/.well-known/openid-configurationcurl -sS https://api.cursor.com/keys

El descubrimiento sigue OpenID Connect Discovery 1.0. Los tokens se emiten en la VM del agente, por lo que el documento de descubrimiento no incluye authorization_endpoint ni token_endpoint.

Comprueba, como mínimo:

• La firma con RS256 y el kid de JWKS
• Que iss sea https://api.cursor.com
• Que aud sea la audiencia que espera tu servicio
• nbf / exp con un pequeño margen de desfase horario (nbf es 5 segundos anterior a iat)
• sub u otras afirmaciones de identidad que use tu política

El descubrimiento incluye x_cursor_audience_bound: true. Cada token se emite para el aud proporcionado por quien realiza la llamada. No aceptes un token emitido para otra audiencia. El descubrimiento también publica x_cursor_sub_claims_supported, los nombres de las afirmaciones que una solicitud de emisión puede proyectar en sub con sub_claim.

Afirmaciones JWT

Encabezado: alg=RS256, typ=JWT y kid.

repo_url es el repositorio principal. Para restringir un agente a repositorios específicos, fije el conjunto completo con repo_urls.

Modelo de confianza

El token identifica la ejecución del agente en la nube, no un proceso específico en la máquina. Cualquier proceso que pueda acceder al socket puede emitir un token: el agente, el código que ejecuta y los hooks. Restrinja los permisos a los que concedería a esa ejecución en su conjunto.

No puede elegir para qué agente es el token. Cherri Code completa las afirmaciones con datos de esta ejecución, por lo que un proceso en la máquina no puede emitir un token para otro agente.

En un worker autohospedado, el agente y el proceso del worker se ejecutan con el mismo usuario del sistema operativo. Cualquier proceso que se ejecute con ese usuario puede emitir un token para la ejecución afirmada. Restrinja el rol a lo que concedería a ese usuario en la máquina.

Límites de uso y errores

Cada agente afirmado puede emitir 30 tokens por minuto, en ráfagas de hasta 10. El socket acepta como máximo 8 conexiones a la vez. En una VM gestionada por Cherri Code, esas 8 conexiones se comparten con los metadatos del agente. Almacene en caché un token hasta que caduque en lugar de emitir uno por llamada.

Reintenta 429, 503, 500, 502 y 504 con una espera progresiva. Considera 403 un error fatal: este agente no tiene permiso para emitir tokens.

Los cuerpos de error incluyen un código legible por máquina. Los errores de solicitud no válida (400, 404, 405, 413 y 415) también incluyen una cadena usage que reitera el contrato completo de la solicitud. Los errores de límite de uso y saturación solo incluyen el código:

{ "error": "invalid_aud", "usage": "POST /v1/tokens/oidc ..." }

{ "error": "rate_limited" }

Ejemplo de AWS IAM

Usa OIDC si quieres que AWS confíe en JWT firmados por Cherri Code con AssumeRoleWithWebIdentity. Para el flujo más sencillo de asunción de roles gestionado por Cherri Code (ID externo + CURSOR_AWS_ASSUME_IAM_ROLE_ARN), consulta Uso de roles de AWS IAM.

1. Crea un proveedor de identidad OIDC de IAM con la URL https://api.cursor.com.
2. Establece la audiencia en sts.amazonaws.com (u otra audiencia que requiera tu rol).
3. Configura la relación de confianza del rol solo para los sujetos y equipos que quieras autorizar.

Ejemplo de política de confianza:

{  "Version": "2012-10-17",  "Statement": [    {      "Effect": "Allow",      "Principal": {        "Federated": "arn:aws:iam::123456789012:oidc-provider/api.cursor.com"      },      "Action": "sts:AssumeRoleWithWebIdentity",      "Condition": {        "StringEquals": {          "api.cursor.com:aud": "sts.amazonaws.com"        },        "StringLike": {          "api.cursor.com:sub": "user:*"        }      }    }  ]}

Restrinja esto con un sub exacto, como user:42 para un usuario o service_account:<id> para un agente que se ejecuta como una cuenta de servicio. Las políticas de confianza de AWS solo comprueban aud y sub, así que limite la confianza a un equipo emitiendo con "sub_claim":"team_id" y haciendo coincidir el sujeto proyectado:

"StringEquals": {  "api.cursor.com:aud": "sts.amazonaws.com",  "api.cursor.com:sub": "team_id:123"}

Una política de confianza ve los mismos aud y sub en un token gestionado por Cherri Code y en uno autohospedado. No puede poner agent_runtime en sub.

Siga las instrucciones vigentes de AWS IAM OIDC para crear el proveedor y configurar las huellas digitales.

El agente emite un token con "aud":"sts.amazonaws.com" (más "sub_claim":"team_id" cuando su política de confianza coincida con el sujeto del equipo) y pase el JWT a STS. Si usa listas de permitidos de red, permita sts.amazonaws.com (y cualquier host regional de STS que use).

Otros verificadores

Los mismos tokens funcionan con cualquier verificador compatible con OIDC:

• GCP Workload Identity Federation
• Azure credenciales federadas / Entra ID
• Vault autenticación JWT/OIDC
• API internas que validan JWT con RS256

Configura el proveedor con la URL de descubrimiento, exige tu audiencia y autoriza según afirmaciones como sub, team_id o cloud_agent_id. Para restringir un agente a repositorios específicos, fija el conjunto completo con repo_urls; repo_url nombra solo el repositorio principal.

La emisión solo usa el socket local. El intercambio del JWT con AWS, GCP, Azure o tu servicio sigue requiriendo acceso de red saliente a esos hosts.

Páginas relacionadas

• Metadatos del agente para metadatos de ejecución de clave-valor en el socket de una VM gestionada por Cherri Code
• Secretos y red para consultar los secretos del panel de control y los controles de tráfico saliente
• Configuración del agente en la nube para la asunción de roles de AWS gestionados por Cherri Code
• Resumen de seguridad para consultar el modelo de aislamiento y acceso
• Cuentas de servicio cuando los agentes se ejecutan con una cuenta de servicio del equipo