> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO do Devin air-gapped com seu IdP

> Exija login no Devin Desktop e na CLI air-gapped por meio do seu próprio provedor de identidade OIDC: arquivo de autenticação, configurações do cliente, restrição por grupo, eventos de auditoria e códigos IDP.

> [!NOTE]
>
> Esta documentação se refere às implantações federais do Devin. [Voltar para a Documentação do Devin](/pt-BR/get-started/devin-intro)

Por padrão, o acesso ao build air-gapped é controlado apenas pelo [arquivo de licença](/pt-BR/federal/air-gapped/license). 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"`.

```json /etc/devin/auth.json theme={null}
{
  "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](#discovered-endpoints-must-stay-on-the-issuer). |

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

> [!TIP]
>
> 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](/pt-BR/federal/air-gapped/network-and-certificates).

## 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:

1. 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`.
2. 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.
3. 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).
4. 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](#how-revocation-propagates) para entender o motivo.

## Entrar

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

```sh theme={null}
devin auth login
```

```text theme={null}
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.

```sh theme={null}
devin auth login --force-manual-token-flow
```

```text theme={null}
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

```sh theme={null}
devin auth status
```

```text theme={null}
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.\`

```sh theme={null}
devin auth logout
```

```text theme={null}
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:

```text theme={null}
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:

```json theme={null}
"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](/pt-BR/federal/air-gapped/on-disk-formats#audit-log) 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](/pt-BR/federal/air-gapped/error-codes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.