SSO do Devin air-gapped com seu IdP

Esta documentação se refere às implantações federais do Devin. Voltar para a Documentação do Devin

Por padrão, o acesso ao build air-gapped é controlado apenas pelo arquivo de licença. Você também pode exigir que cada usuário faça login no seu próprio provedor de identidade OIDC. O SSO (Single Sign-On) funciona como uma camada adicional à licença: a licença continua sendo obrigatória, e o fluxo de login é executado no emissor que você configurar.

Criar o arquivo de autenticação


Caminho padrão	`/etc/devin/auth.json`
Caminho padrão (Windows)	`C:\ProgramData\Devin\auth.json`
Override	`DEVIN_AUTH_FILE=<path>`

O arquivo define exatamente um modo. Se o arquivo não existir, o produto se comporta como se ele contivesse "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	Obrigatório	Significado
`schema_version`	sim	Deve ser `0`.
`mode`	sim	`"sso"` para exigir login ou `"license"` para acesso somente por licença (o padrão quando o arquivo não existe).
`issuer`	sim (sso)	A URL do emissor OIDC. Deve usar `https://` (`http://` simples só é aceito para hosts de loopback), sem query string, fragmento ou credenciais embutidas. A descoberta é feita em `<issuer>/.well-known/openid-configuration`.
`client_id`	sim (sso)	O client que você registra no IdP.
`scopes`	não	O padrão é `openid profile email`. Se definido, deve incluir `openid`. `offline_access` é solicitado automaticamente quando o IdP o anuncia, para que seja concedido um token de atualização.
`groups_claim`	não	Claim do ID token que contém a associação a grupos. O padrão é `groups`.
`required_group`	não	Se definido, o login é recusado a menos que esse valor esteja presente na claim de grupos.
`additional_endpoint_hosts`	não	Hosts adicionais nos quais o documento de descoberta do IdP pode anunciar endpoints. Deixe vazio, a menos que seja necessário; consulte Os endpoints descobertos devem permanecer no emissor.

Campos desconhecidos são rejeitados. No modo license, apenas schema_version e mode são permitidos.

Se o seu IdP usa um certificado emitido por uma CA privada, defina DEVIN_CA_BUNDLE com o caminho de um pacote PEM para que a CLI confie nele; consulte Rede e certificados.

Registre o cliente no seu IdP

A CLI executa o fluxo de código de autorização do OIDC com PKCE (S256) como um cliente público; não há segredo do cliente. O cliente que você registrar deve atender aos seguintes requisitos:

Ser um cliente público (sem segredo do cliente) com o ID definido em client_id, por exemplo devin-cli, com a concessão de código de autorização ativada e o método PKCE S256.
Ter http://127.0.0.1/callback registrado como URI de redirecionamento válido. A CLI escuta em uma porta de loopback aleatória (http://127.0.0.1:<port>/callback) no fluxo pelo navegador e usa o endereço fixo http://127.0.0.1/callback no fluxo manual. Conforme a RFC 8252, o IdP deve ignorar a porta de loopback; se o seu não fizer isso, registre um curinga correspondente.
Se você quiser usar required_group, o ID token deve conter a claim de associação a grupos indicada em groups_claim (groups por padrão).
O IdP deve retornar um ID token na renovação (a maioria faz isso quando o escopo openid é concedido), e o tempo de vida do ID token para este cliente deve ser curto. Consulte Como a revogação se propaga para entender o motivo.

Faça login em um terminal na estação de trabalho:

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.

Em um host sem interface gráfica ou via SSH, use o fluxo manual. A CLI exibe uma URL que você deve abrir em um navegador em qualquer máquina; após fazer login, o navegador é redirecionado para uma URL 127.0.0.1 que não vai carregar. Copie essa URL completa (incluindo os parâmetros de consulta) e cole-a no 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:

O Devin Desktop usa o mesmo login por meio do agente integrado; se o usuário não estiver conectado, ele precisará fazer login nas configurações do Devin antes de começar a trabalhar.

Verificar o status e sair

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.

Se o login em cache estiver ausente ou não puder mais ser renovado, a saída será Status: not logged in (<reason>), seguida de Run \devin auth login` to sign in.`

devin auth logout

Logged out: local SSO tokens deleted.

O logout é apenas local: ele exclui o cache de tokens e não se comunica com o IdP.

O que a CLI valida

O ID token é validado localmente: a assinatura com base no JWKS do IdP, iss, aud, a expiração (com tolerância de 120 segundos para diferenças de relógio), o nonce do login e a restrição por grupo. Os ID tokens e os tokens de atualização ficam em cache no armazenamento local de credenciais, com permissões restritas ao proprietário (0600), e são renovados silenciosamente junto ao IdP. Quando o SSO está configurado e não há um login válido (e a renovação silenciosa falha), a CLI é encerrada na inicialização com um erro que orienta o usuário a executar devin auth login. A CLI nunca segue redirecionamentos HTTP do IdP: um 3xx do endpoint de descoberta, de JWKS ou de token faz o login falhar com um erro que indica o endpoint. Portanto, issuer deve apontar para as URLs efetivamente disponibilizadas pelo IdP.

Os endpoints descobertos devem estar no mesmo host do emissor

O authorization_endpoint, o token_endpoint e o jwks_uri obtidos via descoberta devem ter o mesmo esquema, host e porta que o issuer (portas padrão são consideradas equivalentes). Um endpoint em qualquer outro host é rejeitado, e o login falha com um erro como:

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

Algumas topologias de IdP disponibilizam endpoints legitimamente a partir de mais de um host. O caso mais comum em ambientes on-premises é o Keycloak com hostname-backchannel-dynamic=true, em que token_endpoint e jwks_uri são reescritos para o nome do host interno pelo qual a CLI se conectou. Se, e somente se, você tiver confirmado na própria configuração do IdP que o host adicional é intencional, adicione-o:

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

As entradas são host (qualquer porta) ou host:port, comparadas sem diferenciar maiúsculas de minúsculas. Não há suporte a curingas nem como desativar a verificação. A lista de permissões nunca flexibiliza o TLS: um endpoint http:// continua sendo recusado quando o emissor é https://. Não adicione um host só porque ele aparece em um erro de login; o erro indica que a verificação está funcionando.

Como a revogação se propaga

A restrição por grupo é feita sobre o ID token em cache. Por isso, remover um usuário do required_group (ou desativá-lo) no IdP só passa a valer na próxima atualização do token dele: no máximo quando o ID token atual expirar, mais os 120 segundos de tolerância de defasagem de relógio. Se a revogação rápida for importante, mantenha curta a validade do ID token deste cliente. Se uma resposta de atualização não trouxer um novo ID token, o ID token em cache continua em uso, mas apenas por até 24 horas após o exp desse token. Depois disso, o usuário precisa entrar novamente, mesmo que o IdP ainda aceite o token de atualização.

Revalidação em sessões em execução

Enquanto o Devin Desktop (ou qualquer cliente do agente incluído) estiver em execução, o agente verifica novamente o login a cada 60 segundos e força a atualização do token junto ao IdP pelo menos a cada 15 minutos. Se uma verificação falhar, o agente registra um evento de auditoria sso_revalidation_failed com o código IDP, deixa de aceitar novos trabalhos e é encerrado; o usuário precisa fazer login novamente e reiniciar.

O que é auditado

A atividade de SSO é gravada no registro de auditoria local como eventos auth. Todo evento que tenha um token validado disponível inclui a identidade SSO em actor (sso_issuer, sso_subject, sso_user, sso_groups).

`action`	Quando
`sso_login`	Login concluído (`devin auth login` ou Desktop).
`sso_login_denied`	Login recusado após a resposta do IdP: o grupo obrigatório está ausente (`error_code: "IDP004"`) ou o ID token retornado falhou na validação ou não foi enviado (`IDP005`). `actor` contém a identidade atestada pelo IdP; nada é armazenado em cache.
`sso_refresh`	Tokens renovados junto ao IdP.
`sso_logout`	`devin auth logout` ou logout no Desktop.
`sso_revalidation_failed`	Um agente em execução perdeu o login e está sendo encerrado; `error_code` contém o código `IDP`.

Códigos de erro do IDP

Código	Significado	O que fazer
`IDP001`	O arquivo de autenticação está ilegível ou é inválido.	Corrija `/etc/devin/auth.json` (ou o caminho definido em `DEVIN_AUTH_FILE`); a mensagem indica o campo com problema.
`IDP002`	Não há login em cache para o emissor configurado.	Execute `devin auth login`.
`IDP003`	O login é inválido ou expirou e não pôde ser renovado automaticamente (inclusive no caso de uma resposta `invalid_grant` do IdP).	Execute `devin auth login` novamente.
`IDP004`	O login foi feito, mas o usuário não é membro de `required_group`.	Adicione o usuário ao grupo no IdP ou corrija `required_group` / `groups_claim`.
`IDP005`	Não foi possível acessar o IdP ou ele retornou um erro.	Verifique a conectividade de rede, a confiança TLS (`DEVIN_CA_BUNDLE`) e os logs do próprio IdP.
`IDP006`	O cache local de tokens SSO está ilegível, malformado ou não é privado do usuário atual.	Execute `devin auth login`; um novo login reescreve o cache.

O catálogo completo está na página Códigos de erro.

​Criar o arquivo de autenticação

​Registre o cliente no seu IdP

​Entrar

​Verificar o status e sair

​O que a CLI valida

​Os endpoints descobertos devem estar no mesmo host do emissor

​Como a revogação se propaga

​Revalidação em sessões em execução

​O que é auditado

​Códigos de erro do IDP

Criar o arquivo de autenticação

Registre o cliente no seu IdP

Entrar

Verificar o status e sair

O que a CLI valida

Os endpoints descobertos devem estar no mesmo host do emissor

Como a revogação se propaga

Revalidação em sessões em execução

O que é auditado

Códigos de erro do IDP