Configure o login único e o login por dispositivo

O que você está configurando

A Atlasberg já tinha login único para o portal e o console. O login por dispositivo o estende até o terminal do desenvolvedor: a pessoa entra com a identidade corporativa, o terminal recebe um token pessoal, e o gateway troca esse token pela chave virtual do time a cada requisição. Este tutorial monta as duas metades.

[Figura: Tela Identidade e SSO do console com a aba Provedor (OIDC) aberta - Configurações > Identidade e SSO. Quatro abas: Provedor (OIDC), Grupos e times, Login local, Dispositivos. Os três selos de estado à direita dizem o que está ligado.]

Nenhum segredo passa pela tela: O client secret só como nome de variável; a senha local só entra, hasheada com PBKDF2, e nunca sai. Salvar valida antes de gravar e aplica ao vivo. Sessões abertas continuam válidas: uma mudança de scope não desloga a empresa inteira.

• Aba: Provedor (OIDC) | O que faz: Issuer, client id, redirect, scopes, claims, CA corporativa, cookie, duração da sessão, overage do Entra. Testar conexão roda a descoberta OIDC e lista os endpoints. O segredo do cliente entra como o NOME de uma variável de ambiente, nunca como valor.
• Aba: Grupos e times | O que faz: Regras de grupo do diretório para time do gateway, com prioridade, e o time padrão de quem entra sem grupo mapeado. Embaixo, o bloco de sincronização com o diretório.
• Aba: Login local | O que faz: Contas de usuário e senha do appliance (rede fechada e conta de emergência do console): criar, trocar senha, conceder ou retirar acesso ao console, remover.
• Aba: Dispositivos | O que faz: Liga e desliga o fluxo, validade do token e do código, intervalo de consulta, teto por pessoa. Embaixo, a tabela de todos os tokens emitidos com revogar um e revogar todos de uma pessoa.

Passo a passo

• Campo: Login por dispositivo habilitado | Padrão: ligado | Limites e efeito: Desligar derruba todos os tokens na hora e fecha as rotas do fluxo.
• Campo: Validade do token (horas) | Padrão: 168 | Limites e efeito: De 1 a 2160. Sete dias equilibra conforto e a saída de alguém da empresa.
• Campo: Validade do código (minutos) | Padrão: 10 | Limites e efeito: De 1 a 30. Tempo para a pessoa ir do terminal ao portal.
• Campo: Intervalo de consulta (segundos) | Padrão: 5 | Limites e efeito: Mínimo 1. O terminal que consulta antes recebe slow_down.
• Campo: Tokens ativos por pessoa | Padrão: 5 | Limites e efeito: Mínimo 1. Acima do teto, o mais antigo é revogado.

1. Registre o gateway no provedor de identidade

No Entra ID, no Keycloak ou no AD FS, crie um aplicativo do tipo web com a redirect URL que a tela sugere, no formato https://llm.empresa.com/api/atlasberg/sso/callback. Anote o client id e o client secret. No Entra, se a organização tem pessoas em mais de duzentos grupos, ligue depois a opção de consultar o diretório (overage).

2. Coloque o segredo no appliance, não na tela

O client secret entra como variável de ambiente do container, por exemplo ATLASBERG_SSO_CLIENT_SECRET. No Docker, pelo --env ou pelo arquivo de ambiente do compose; no Kubernetes, por um Secret montado como variável. Na tela informa-se apenas o nome da variável. Um valor literal é recusado. A leitura mostra o nome e se a variável está definida, nunca o conteúdo.

3. Aba Provedor (OIDC)

Marque Login único (OIDC) habilitado. Issuer: Entra é https://login.microsoftonline.com/<tenant>/v2.0, Keycloak é https://kc.interno/realms/empresa; a descoberta roda em /.well-known/openid-configuration. Client ID e o nome da variável do segredo. Redirect URL: clique em Usar sugerido e registre exatamente esse valor no provedor. Scopes: openid profile; no Keycloak acrescente groups. Se o provedor usa certificado interno, o caminho do PEM montado no container. Testar conexão: verde significa que o gateway alcançou o provedor e leu os endpoints. Salvar e aplicar: o login pelo SSO fica disponível no portal na mesma hora.

4. Aba Grupos e times

Cada grupo do diretório casa com um time do gateway. O time decide a chave virtual, o orçamento e as políticas que a pessoa recebe. Há dois jeitos: colocar o GUID do grupo no campo SourceID do time, em Governança, e o casamento é automático; ou escrever a regra aqui, com prioridade, que vence a regra automática. Quem entra sem grupo mapeado cai no time padrão, ou em nenhum time, e nesse caso autentica mas tem a inferência recusada até um administrador vincular um.

5. Aba Login local

Necessária em rede fechada sem provedor, e recomendada em qualquer caso como conta de emergência do console. Crie a conta com usuário, nome, senha de pelo menos doze caracteres e a opção Acesso ao console. A senha é hasheada com PBKDF2 antes de tocar o disco e nunca é exibida. Trocar senha, retirar o acesso ao console e remover estão na mesma tabela. Remover uma conta revoga os tokens pessoais dela.

6. Aba Dispositivos

Marque Login por dispositivo habilitado e ajuste a política se os padrões não servirem. Salvar e aplicar. Desligar depois derruba todos os tokens na hora e fecha as rotas do fluxo.

7. Distribua a CLI

Três caminhos, e eles convivem. Quem tem Node instala com npm install -g @atlasberg/cli (ou roda npx @atlasberg/cli sem instalar). Em rede fechada, o desenvolvedor baixa a CLI em Meus dispositivos no portal, para o sistema dele, e coloca o arquivo no PATH com o nome atlasberg. Em empresas com gerenciamento de estações, o mesmo binário pode ir pelo pacote padrão da TI: ele não tem dependência e não precisa de instalação. O próprio gateway serve as builds em /api/atlasberg/sso/downloads/<arquivo>, para Linux (x86_64 e arm64), macOS (Intel e Apple Silicon) e Windows. Depois disso, o roteiro do desenvolvedor é o Tutorial 3: atlasberg login, confirmar no portal, eval "$(atlasberg env)".

Política de dispositivos

docker run -d --name atlasberg ... \
  -e ATLASBERG_SSO_CLIENT_SECRET='<client secret>' \
  -e ATLASBERG_PROXIES_CONFIAVEIS='10.0.0.0/8' \
  atlasberg-proxy:<versão>

O mesmo, pelo arquivo

Tudo acima também pode ser versionado como <app-dir>/sso.json. Editado à mão, exige reiniciar o gateway; editado pela tela, é aplicado ao vivo. As contas locais criadas pela tela são gravadas como salt, hash e iterações, nunca como senha.

{
  "enabled": true,
  "issuer": "https://login.microsoftonline.com/<tenant>/v2.0",
  "client_id": "<app-id>",
  "client_secret": "env.ATLASBERG_SSO_CLIENT_SECRET",
  "redirect_url": "https://llm.empresa.com/api/atlasberg/sso/callback",
  "scopes": ["openid", "profile"],
  "directory_graph": { "enabled": true },
  "group_teams": [{ "group_id": "<guid-do-grupo>", "team_id": "time-eng", "priority": 10 }],
  "default_team": "",
  "local_login": { "enabled": true, "console_group": "atlasberg-console", "accounts": [] },
  "device_flow": { "enabled": true, "token_ttl_hours": 168, "code_ttl_minutes": 10,
                   "poll_interval_seconds": 5, "max_tokens_per_user": 5 }
}

Sincronize a árvore de times com o diretório

Na aba Grupos e times, o bloco Sincronização com o diretório. Precisa de uma credencial de aplicativo separada da do login: no Entra ID, um aplicativo com Group.Read.All e User.Read.All; no Keycloak, um client com service account e os papéis view-users e query-groups. O segredo entra como nome de variável de ambiente, igual ao do SSO.

O que não prometer: Sem a sincronização, a saída de uma pessoa do diretório só é sentida no token quando ele expira, em sete dias por padrão, ou quando alguém revoga. Com a sincronização, em até uma hora. AD FS puro não tem API de leitura de grupos: sincronização só com Entra ID ou Keycloak. A CLI guarda o token em arquivo com permissão restrita, não no keychain do sistema.

• Arquivar nunca apaga: o time é renomeado com [arquivado] e as chaves são desativadas, porque o histórico de custo e a trilha precisam continuar resolvendo o nome. Se o grupo voltar, o time é reativado.
• A mesma credencial confere, a cada ciclo, quem foi desligado no diretório e revoga os tokens pessoais dessa pessoa.
• Quem entra com um grupo que ainda não tem time recebe o time criado ali, no primeiro login.
• Com o control plane congelado por licença vencida, as mudanças de times esperam; a revogação de quem saiu continua rodando.

1. Crie o time modelo

Em Governança, um time com os orçamentos, o limite de taxa e a chave com os provedores que todo time novo deve herdar.

2. Defina o filtro

O prefixo dos grupos que viram times (só esses entram), tipo ia-, ou a lista de ids.

3. Escolha a unidade

Departamento ou empresa dos membros, por maioria, ou a cadeia de grupos pai no Keycloak. Ou não atribuir.

4. Prévia

O gateway lê o diretório e mostra o que criaria, renomearia e arquivaria, sem mudar nada.

5. Salvar e Sincronizar agora

Depois disso o ciclo roda sozinho no intervalo escolhido, sessenta minutos por padrão, e a última execução fica visível na tela com os contadores e os erros.

Rede, proxies e TLS

• As rotas novas vivem sob /api/atlasberg/sso/ e /api/atlasberg/identidade/, no mesmo processo e na mesma porta. O portal precisa ser alcançável pelo navegador do colaborador e pelo terminal do desenvolvedor na mesma URL pública, com TLS.
• O cookie de sessão é Secure e SameSite=Strict: em produção o gateway tem de estar atrás de HTTPS, seja pelo ingress, seja pelo edge.
• Atrás de um balanceador, defina ATLASBERG_PROXIES_CONFIAVEIS com os CIDRs do edge. Só com a conexão vindo de um deles o gateway lê X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host. Sem isso, a empresa inteira aparece com um IP só: um limite por origem vira um limite para todo mundo e a tela de aprovação mostra o endereço do balanceador. No Kubernetes, o chart expõe identity.trustedProxies.
• O terminal imprime o endereço que o gateway conhece como seu. Ordem de preferência: a origem da redirect URL do SSO, depois o que o proxy confiável informar, depois o host da própria conexão.

Rotina de operação

• Situação: Alguém saiu da empresa | O que fazer: Remover a pessoa do grupo no diretório para as sessões novas, e na aba Dispositivos clicar em Revogar todos desta pessoa para os terminais. Se a conta era local, remover a conta faz as duas coisas.
• Situação: Laptop perdido | O que fazer: A própria pessoa revoga em Meus dispositivos, ou o administrador revoga aquele token pelo nome do dispositivo e pela origem.
• Situação: Suspeita de abuso | O que fazer: Desligar o login por dispositivo na tela derruba todos os tokens de uma vez, sem mexer nas sessões do portal.
• Situação: Licença vencida | O que fazer: Revogar um token ou todos os de uma pessoa continua funcionando com o control plane congelado. Editar a configuração de identidade congela junto com o resto.
• Evento: auth.device.started | Quando: Um terminal pediu um código. Ator não autenticado, origem nos detalhes.
• Evento: auth.device.approved | Quando: A pessoa aprovou. Ator é a pessoa; time e dispositivo nos detalhes.
• Evento: auth.device.denied | Quando: A pessoa negou.
• Evento: auth.token.issued | Quando: O terminal coletou o token. Identificador público do token nos detalhes.
• Evento: auth.token.revoked | Quando: Revogação, com o motivo: pessoa, administrador, teto, logout ou diretório.
• Evento: config.change (recurso sso) | Quando: Toda gravação pela tela de identidade, com a seção alterada e quem alterou.

O que a trilha de auditoria registra

Autenticar com o token numa requisição de IA não gera evento próprio, de propósito: é o caminho normal da inferência, já coberto pelos eventos de admissão e métricas, e um evento por requisição deixaria um token roubado inflar a trilha.

Faça tudo com um agente de IA

Se preferir delegar, cole o prompt abaixo no Claude Code ou em outro agente de IA com acesso ao terminal. Ele foi escrito para perguntar tudo o que precisa antes de mexer em qualquer coisa, mostrar um plano, esperar a sua confirmação e só então executar. Ele nunca pede o valor de uma chave de provedor e nunca grava segredo em arquivo do repositório.

Para desenvolvedores: entre pelo terminal

O que a pessoa vê: o comando, o código, o portal, as variáveis.

Referência: Configurações no console

Todas as telas do menu Configurações, inclusive Identidade e SSO.

Você é meu administrador da Atlasberg Platform e vai configurar o login único (OIDC), o mapeamento de grupos para times e o login por dispositivo, seguindo https://atlasberg.com/docs/tutoriais/configurar-sso e a referência em https://atlasberg.com/docs/api/gestao. Trabalhe pela API de identidade do gateway com curl. Nunca invente valores: pergunte.

Antes de qualquer alteração, me pergunte, uma pergunta por vez:
1. A URL pública do gateway (exemplo: https://llm.empresa.com) e como autenticar na API de gestão (usuário e senha de administrador). Nunca repita a senha nem a grave em arquivo.
2. O provedor de identidade: Entra ID, Keycloak ou AD FS. O issuer (Entra: https://login.microsoftonline.com/<tenant>/v2.0; Keycloak: https://<host>/realms/<realm>).
3. O client id do aplicativo registrado no provedor e o NOME da variável de ambiente do appliance que guarda o client secret (exemplo: ATLASBERG_SSO_CLIENT_SECRET). Não me peça o valor do segredo. Se a variável ainda não estiver definida no container, me diga como definir (Docker --env ou Kubernetes Secret) e espere eu confirmar que reiniciei.
4. Os scopes (padrão openid profile; no Keycloak acrescentar groups) e, se o provedor usa certificado interno, o caminho do PEM da CA montado no container.
5. As regras de grupo para time: para cada grupo do diretório (GUID no Entra, nome ou id no Keycloak), qual time do gateway recebe as pessoas dele. Se o time ainda não existe, avise que ele precisa ser criado em Governança > Times antes. E qual é o time padrão para quem entra sem grupo mapeado, ou nenhum.
6. Se quero login local habilitado (recomendado como conta de emergência do console) e o nome do grupo que dá acesso ao console (padrão atlasberg-console). As contas locais e as senhas eu mesmo crio na tela Login local; você não vai manusear senhas.
7. A política de dispositivos: ligado ou desligado, validade do token em horas (padrão 168, de 1 a 2160), validade do código em minutos (padrão 10), intervalo de consulta em segundos (padrão 5) e tokens ativos por pessoa (padrão 5).
8. Se há balanceador ou edge na frente do gateway e, se sim, os CIDRs dele para ATLASBERG_PROXIES_CONFIAVEIS.
9. Se quero sincronizar a árvore de times com o diretório (só Entra ID ou Keycloak): client id do aplicativo de leitura, nome da variável do segredo, prefixo dos grupos que viram times (exemplo: ia-), id do time modelo e intervalo em minutos (padrão 60).

Quando tiver tudo, mostre a configuração final em tabela e peça confirmação. Só então execute, conferindo cada status e parando no primeiro erro:
a) GET /api/atlasberg/identidade/config e guarde a resposta: ela tem as seções provedor, grupos, login_local, dispositivos e diretorio, e é esse formato que o PUT espera. Nunca envie um segredo literal; o campo client_secret_env recebe só o nome da variável.
b) POST /api/atlasberg/identidade/config/testar com {"issuer":"...","ca_cert_path":"...","client_secret_env":"..."} e me mostre os endpoints descobertos. Se falhar, pare e me mostre o erro.
c) PUT /api/atlasberg/identidade/config com a resposta do passo a) alterada: provedor.enabled true, issuer, client_id, client_secret_env, redirect_url igual a <gateway>/api/atlasberg/sso/callback, scopes, ca_cert_path se houver; grupos.group_teams como lista de {"group_id":"...","team_id":"<id do time>","priority":10} e grupos.default_team; login_local.enabled e console_group; dispositivos com enabled, token_ttl_hours, code_ttl_minutes, poll_interval_seconds e max_tokens_per_user; diretorio conforme o item 9, ou intacto. Confira com um novo GET que ficou como planejado.
d) Me diga exatamente o que registrar no provedor de identidade: a redirect URL do passo c) e, no Entra, a opção de overage se houver pessoas em mais de duzentos grupos.
e) Se houver balanceador, me lembre de definir ATLASBERG_PROXIES_CONFIAVEIS no container e reiniciar; explique que sem isso todos os usuários aparecem com o IP do balanceador.
f) Sincronização, se eu tiver pedido: POST /api/atlasberg/identidade/diretorio/previa e me mostre o que seria criado, renomeado e arquivado; só depois da minha confirmação, POST /api/atlasberg/identidade/diretorio/sincronizar.
g) Testes: POST /api/atlasberg/sso/device/code com {"client_name":"teste"} tem de devolver um user_code no formato XXXX-XXXX; GET /api/atlasberg/sso/downloads mostra se as builds da CLI estão disponíveis para os desenvolvedores. Não é possível testar o login pelo provedor sem um navegador: me peça para entrar no portal e confirmar que o botão do SSO aparece e o login funciona.
h) Entregue um resumo do que ficou configurado, o que eu ainda preciso fazer (contas locais na tela, registro no provedor, distribuição da CLI) e a rotina de operação do tutorial (saída de pessoa, laptop perdido, suspeita de abuso).

Regras: se um endpoint responder diferente do esperado, mostre a resposta e pergunte antes de contornar. Não desligue o login local sem me avisar. Não altere nada fora da seção de identidade.

Sobre a Atlasberg Platform

A Atlasberg Platform é a camada de controle entre uma empresa e todos os modelos de IA: cada requisição é autenticada com uma chave virtual, filtrada por política e DLP, roteada para o provedor certo e gravada numa trilha de auditoria encadeada por hash. Expõe uma API compatível com a OpenAI, então as aplicações só trocam a URL base.

O mesmo artefato roda na Atlasberg Cloud, na sua VPC, on-premises ou totalmente air-gapped, e é cobrado por capacidade e módulos, nunca por assento.

Esta página faz parte da documentação oficial. Para falar com o time de engenharia, escreva para [email protected] ou use https://atlasberg.com/pt-br/contato. A resposta vem em até um dia útil.