SSO de Devin aislado de la red con tu IdP

Esta documentación corresponde a los despliegues federales de Devin. Volver a la documentación de Devin

De forma predeterminada, el acceso a la compilación aislada de la red se controla únicamente mediante el archivo de licencia. Además, puedes exigir que cada usuario inicie sesión con tu propio proveedor de identidad OIDC. El SSO (inicio de sesión único) se añade como una capa adicional sobre la licencia: la licencia sigue siendo obligatoria y el flujo de inicio de sesión se ejecuta contra el emisor que configures.

Crear el archivo de autenticación


Ruta predeterminada	`/etc/devin/auth.json`
Ruta predeterminada (Windows)	`C:\ProgramData\Devin\auth.json`
Anulación	`DEVIN_AUTH_FILE=<path>`

El archivo selecciona un único modo. Si el archivo no existe, el producto se comporta como si contuviera "mode": "license".

/etc/devin/auth.json

{
  "schema_version": 0,
  "mode": "sso",
  "issuer": "https://sso.example.com",
  "client_id": "devin-cli",
  "scopes": ["openid", "profile", "email"],
  "groups_claim": "groups",
  "required_group": "devin-users",
  "additional_endpoint_hosts": []
}

Campo	Obligatorio	Significado
`schema_version`	sí	Debe ser `0`.
`mode`	sí	`"sso"` para exigir inicio de sesión, o `"license"` para acceso solo con licencia (el valor predeterminado cuando no existe el archivo).
`issuer`	sí (sso)	La URL del emisor OIDC. Debe usar `https://` (`http://` sin cifrar solo se acepta para hosts de loopback) y no puede incluir cadena de consulta, fragmento ni credenciales incrustadas. El descubrimiento se realiza en `<issuer>/.well-known/openid-configuration`.
`client_id`	sí (sso)	El cliente que registras en el IdP.
`scopes`	no	El valor predeterminado es `openid profile email`. Si se define, debe incluir `openid`. `offline_access` se solicita automáticamente cuando el IdP lo anuncia, de modo que se conceda un token de actualización.
`groups_claim`	no	Claim del token de ID que contiene la pertenencia a grupos. El valor predeterminado es `groups`.
`required_group`	no	Si se define, se rechaza el inicio de sesión a menos que este valor aparezca en el claim de grupos.
`additional_endpoint_hosts`	no	Hosts adicionales en los que el documento de descubrimiento del IdP puede anunciar endpoints. Déjalo vacío salvo que lo necesites; consulta Discovered endpoints must stay on the issuer.

Los campos desconocidos se rechazan. En el modo license solo se permiten schema_version y mode.

Si tu IdP usa un certificado emitido por una CA privada, configura DEVIN_CA_BUNDLE con la ruta a un paquete PEM para que la CLI confíe en él; consulta Red y certificados.

Registra el cliente en tu IdP

La CLI ejecuta el flujo de código de autorización de OIDC con PKCE (S256) como cliente público, por lo que no hay secreto de cliente. El cliente que registres debe cumplir estos requisitos:

Debe ser un cliente público (sin secreto de cliente) con el ID que indiques en client_id, por ejemplo devin-cli, con la concesión de código de autorización habilitada y el método PKCE S256.
http://127.0.0.1/callback debe estar registrado como URI de redirección válido. La CLI escucha en un puerto de loopback aleatorio (http://127.0.0.1:<port>/callback) para el flujo del navegador y usa la dirección fija http://127.0.0.1/callback para el flujo manual. Según el RFC 8252, el IdP debería ignorar el puerto de loopback; si el tuyo no lo hace, registra un comodín que coincida.
Si quieres usar required_group, el token de ID debe incluir el claim de pertenencia a grupo indicado en groups_claim (groups de forma predeterminada).
El IdP debe devolver un token de ID al actualizarse (la mayoría lo hace cuando se concede el ámbito openid), y la vida útil del token de ID para este cliente debe ser corta. Consulta Cómo se propaga la revocación para saber por qué.

Inicia sesión desde una terminal en la estación de trabajo:

devin auth login

Opening your browser to sign in with your identity provider...
If the browser does not open, visit:

  https://sso.example.com/authorize?client_id=devin-cli&...

(Use `devin auth login --force-manual-token-flow` on headless machines.)
Logged in as jsmith via https://sso.example.com.
Token expires at 2026-03-02 15:04:05 UTC.

En un host sin interfaz gráfica o a través de SSH, usa el flujo manual. La CLI muestra una URL que debes abrir en un navegador desde cualquier máquina; después de iniciar sesión, el navegador te redirigirá a una URL de 127.0.0.1 que no llegará a cargarse. Copia esa URL completa (incluidos sus parámetros de consulta) y pégala en la terminal.

devin auth login --force-manual-token-flow

Open this URL in a browser (on any machine) and sign in:

  https://sso.example.com/authorize?client_id=devin-cli&...

After signing in, the browser is redirected to a 127.0.0.1 URL that will not load — copy that full URL (including its query parameters) and paste it here.
Paste the full redirect URL:

Devin Desktop usa el mismo inicio de sesión a través del agente integrado; si un usuario no ha iniciado sesión, se le pedirá que lo haga en la configuración de Devin antes de empezar a trabajar.

Comprobar el estado y cerrar sesión

devin auth status

Auth mode: SSO (issuer: https://sso.example.com)
Status: logged in
User: jsmith
Subject: 6f1c2a0e-...
Groups: devin-users
Token expires at 2026-03-02 15:04:05 UTC.

Si el inicio de sesión almacenado en caché no existe o ya no se puede renovar, la salida es Status: not logged in (<reason>), seguida de Run \devin auth login` to sign in.`

devin auth logout

Logged out: local SSO tokens deleted.

El cierre de sesión solo tiene efecto local: elimina la caché de tokens y no se comunica con el IdP.

Qué valida la CLI

El token de ID se valida localmente: la firma con el JWKS del IdP, iss, aud, la expiración (con una tolerancia de desfase de reloj de 120 segundos), el nonce del inicio de sesión y el control de pertenencia a grupos. Los tokens de ID y de actualización se guardan en caché en el almacén local de credenciales con permisos exclusivos para el propietario (0600) y se renuevan automáticamente con el IdP, sin intervención del usuario. Si SSO está configurado y no hay un inicio de sesión válido (y la renovación automática falla), la CLI se cierra al iniciarse y muestra un error que indica al usuario que ejecute devin auth login. La CLI nunca sigue redirecciones HTTP del IdP: si el endpoint de descubrimiento, de JWKS o de tokens devuelve un 3xx, el inicio de sesión falla con un error que indica qué endpoint lo provocó, por lo que issuer debe apuntar a las URL que el IdP expone realmente.

Los endpoints descubiertos deben estar en el mismo emisor

Los valores authorization_endpoint, token_endpoint y jwks_uri obtenidos mediante el descubrimiento deben tener el mismo esquema, host y puerto que issuer (los puertos predeterminados se consideran equivalentes). Cualquier endpoint alojado en otro host se rechaza, y el inicio de sesión falla con un error similar a este:

IdP discovery document advertises jwks_uri 'https://keycloak.corp.internal:8443/realms/devin/protocol/openid-connect/certs'
on host 'keycloak.corp.internal:8443', which is not the configured issuer's host 'sso.corp.example:443';
refusing to trust it. If this IdP really serves that endpoint from a different host,
add "keycloak.corp.internal" to `sso.additional_endpoint_hosts` in the auth file

Algunas topologías de IdP sirven legítimamente endpoints desde más de un host. El caso más habitual en entornos on-premises es Keycloak con hostname-backchannel-dynamic=true, donde token_endpoint y jwks_uri se reescriben con el nombre de host interno a través del cual se conectó la CLI. Si, y solo si, has comprobado en la propia configuración del IdP que el host adicional es intencionado, agrégalo:

"additional_endpoint_hosts": ["keycloak.corp.internal"]

Las entradas son host (cualquier puerto) o host:port, y se comparan sin distinguir entre mayúsculas y minúsculas. No se admiten comodines ni hay forma de desactivar la comprobación. La lista de permitidos nunca flexibiliza TLS: un endpoint http:// se sigue rechazando con un emisor https://. No agregues un host solo porque aparezca en un error de inicio de sesión; ese error significa que la comprobación está funcionando.

Cómo se propaga la revocación

El control de pertenencia a grupos se evalúa sobre el token de ID almacenado en caché, por lo que quitar a un usuario de required_group (o deshabilitarlo) en el IdP surte efecto en la siguiente actualización de su token: como máximo, cuando caduque el token de ID actual, más los 120 segundos de tolerancia de desfase de reloj. Si necesitas que la revocación sea rápida, configura una vida útil corta del token de ID para este cliente. Si una respuesta de actualización no incluye un nuevo token de ID, se sigue usando el token de ID almacenado en caché, pero solo hasta 24 horas después del exp de ese token. Pasado ese plazo, el usuario debe volver a iniciar sesión aunque el IdP siga aceptando el token de actualización.

Revalidación en sesiones en ejecución

Mientras Devin Desktop (o cualquier cliente del agente integrado) está en ejecución, el agente vuelve a comprobar el inicio de sesión cada 60 segundos y fuerza una actualización del token con el IdP al menos cada 15 minutos. Si una comprobación falla, el agente registra un evento de auditoría sso_revalidation_failed con el código IDP, deja de aceptar trabajo nuevo y se cierra; el usuario debe volver a iniciar sesión y reiniciarlo.

Qué se audita

La actividad de SSO se escribe en el registro de auditoría local como eventos auth. Todo evento que disponga de un token validado incluye la identidad SSO en actor (sso_issuer, sso_subject, sso_user, sso_groups).

`action`	Cuándo
`sso_login`	Inicio de sesión completado (`devin auth login` o Desktop).
`sso_login_denied`	Inicio de sesión rechazado tras la respuesta del IdP: falta el grupo obligatorio (`error_code: "IDP004"`), o el token de ID devuelto no superó la validación o no se recibió (`IDP005`). `actor` incluye la identidad avalada por el IdP; no se almacena nada en caché.
`sso_refresh`	Tokens renovados con el IdP.
`sso_logout`	`devin auth logout` o cierre de sesión en Desktop.
`sso_revalidation_failed`	Un agente en ejecución perdió su sesión y se está cerrando; `error_code` incluye el código `IDP`.

Códigos de error de IDP

Código	Significado	Qué hacer
`IDP001`	El archivo de autenticación no se puede leer o no es válido.	Corrija `/etc/devin/auth.json` (o la ruta de `DEVIN_AUTH_FILE`); el mensaje indica el campo problemático.
`IDP002`	No hay ningún inicio de sesión en caché para el emisor configurado.	Ejecute `devin auth login`.
`IDP003`	El inicio de sesión no es válido o ha caducado, y no se pudo renovar de forma transparente (incluida una respuesta `invalid_grant` del IdP).	Vuelva a ejecutar `devin auth login`.
`IDP004`	La sesión se inició, pero el usuario no es miembro de `required_group`.	Agregue el usuario al grupo en el IdP o corrija `required_group` / `groups_claim`.
`IDP005`	No se pudo acceder al IdP o este devolvió un error.	Compruebe la conectividad de red, la confianza TLS (`DEVIN_CA_BUNDLE`) y los registros del propio IdP.
`IDP006`	La caché local de tokens de SSO no se puede leer, tiene un formato incorrecto o no es privada del usuario actual.	Ejecute `devin auth login`; al volver a iniciar sesión, la caché se reescribe.

Puede consultar el catálogo completo en la página Códigos de error.

​Crear el archivo de autenticación

​Registra el cliente en tu IdP

​Iniciar sesión

​Comprobar el estado y cerrar sesión

​Qué valida la CLI

​Los endpoints descubiertos deben estar en el mismo emisor

​Cómo se propaga la revocación

​Revalidación en sesiones en ejecución

​Qué se audita

​Códigos de error de IDP

Crear el archivo de autenticación

Registra el cliente en tu IdP

Iniciar sesión

Comprobar el estado y cerrar sesión

Qué valida la CLI

Los endpoints descubiertos deben estar en el mismo emisor

Cómo se propaga la revocación

Revalidación en sesiones en ejecución

Qué se audita

Códigos de error de IDP