Pular para o conteúdo

Recursos

Identidade e acesso

Quem está logado, o que essa pessoa pode fazer e como a primeira conta passa a existir. Esta página descreve o Adendo v0.5 do CONTRACT.md tal como o services/rust/orbit-api o implementa: usuários locais, sessões, papéis sobre um conjunto fechado de permissões e uma linha de auditoria para cada mudança (veja audit.md). As pessoas também podem entrar pelo Google (Adendo v0.8) ou por qualquer provedor OpenID Connect (Adendo v0.19); veja "Single sign-on".

Duas credenciais, duas funções

Toda chamada ao orbit-api leva duas coisas, e cada uma responde a uma pergunta diferente.

CredencialQuem a guardaO que ela provaPor onde trafega
Bearer de serviço ORBIT_AUTH_TOKENSó o servidor do webQue a chamada veio pelo web (Adendo v0.2)Authorization: Bearer ... em toda chamada repassada pelo proxy
Token de sessãoO navegador, dentro de um cookie HttpOnlyQual pessoa está pedindoCookie orbit_session do navegador até o web; X-Orbit-Session do web até o orbit-api

O orbit-api confere primeiro o bearer, depois a sessão e, por fim, a única permissão que a rota exige. Sem sessão, a resposta é 401 unauthorized; uma sessão cujo papel não tem a permissão recebe 403 forbidden, com a permissão nomeada na mensagem e um evento access.denied na trilha de auditoria. Com ORBIT_AUTH_MODE=disabled (só para demos locais) não há bearer para conferir, e a sessão continua sendo verificada.

As rotas que respondem sem sessão, a lista completa (PUBLIC em services/rust/orbit-api/src/api.rs): GET /healthz, GET /readyz, GET /api/v1/auth/state, POST /api/v1/auth/login, POST /api/v1/auth/setup, POST /api/v1/contact e os pares de single sign-on POST /api/v1/auth/sso/start e /callback (Google) e POST /api/v1/auth/sso/oidc/start e /callback. Qualquer outra rota, inclusive uma que ninguém escreveu ainda, exige sessão. GET /api/v1/version e GET /api/v1/nocturne/models exigem sessão, mas nenhuma permissão.

Do lado do navegador, uma página do Deck pedida sem o cookie é redirecionada para /login (/pt-BR/login em português) com ?next= apontando para a página, e o layout do Deck confere a sessão de novo contra o orbit-api antes de renderizar qualquer coisa. Um servidor web sem ORBIT_API_URL não tem como autenticar ninguém: ele serve o console como uma demonstração anônima e somente leitura, com as permissões do papel viewer, e as páginas de administração avisam que precisam do orbit-api.

O primeiro administrador

O orbit-api cria a primeira conta na inicialização, e só enquanto não existe nenhum usuário. Ele tenta três fontes, nesta ordem.

1. ORBIT_ADMIN_USER e ORBIT_ADMIN_PASSWORD_VERIFIER. Defina as duas ou nenhuma: com só uma delas, o serviço se recusa a iniciar. O verificador é a string PBKDF2 que o apps/web/scripts/hash-password.mjs imprime, nunca a própria senha:

bash
openssl rand -base64 24 > admin-password && chmod 600 admin-passwordORBIT_ADMIN_PASSWORD_VERIFIER="$(node apps/web/scripts/hash-password.mjs < admin-password)"

O script recusa qualquer coisa com menos de 15 caracteres e grava 600.000 iterações; o orbit-api aceita um verificador com 210.000 iterações ou mais e, na inicialização, recusa um que esteja malformado. O nome de usuário precisa casar com [a-z0-9][a-z0-9._-]{0,31}. Onde os dois valores entram depende do caminho de instalação: no Secret do release, para o Helm e os manifestos puros (install/helm.md, install/kubectl.md), e no .env, para o compose (install/docker-compose.md). O par é lido a cada inicialização e ignorado assim que existe algum usuário (o log avisa isso); mudá-lo depois não muda nada.

2. Os usuários de demonstração, quando ORBIT_DEMO_DATA=true e nenhum par de administrador está definido: admin, editor e viewer, um por papel embutido, com uma senha única por instalação: ORBIT_DEMO_PASSWORD, que o chart Helm sorteia no Secret dele na instalação, ou uma aleatória que o orbit-api sorteia quando ela está vazia. O orbit-api a imprime uma vez, numa linha WARN com o campo demo_password, na inicialização que cria as contas; a página de login lista as contas ativas sem ela. Para lê-la de novo, use kubectl -n sreorbit get secret sreorbit-secrets -o jsonpath='{.data.ORBIT_DEMO_PASSWORD}' | base64 -d no Helm, ou docker compose logs orbit-api | grep demo_password no compose. Uma conta que uma versão anterior criou com a senha pública recebe esta na próxima inicialização. Elas existem para demonstrar os papéis; depois de criados, são contas comuns, então um diretório de dados que começou com dados de demonstração continua com eles mesmo depois que ORBIT_DEMO_DATA passa a false. Exclua-os, ou comece a produção com um diretório de dados vazio.

3. Um código de configuração de uso único, quando nenhum dos dois se aplica (uma instalação ao vivo sem par de administrador). O orbit-api o escreve no log uma única vez, na inicialização, como uma linha WARN com um campo setup_code:

bash
kubectl -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_code

No compose, docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml logs orbit-api | grep setup_code. Abra /login: enquanto não existe nenhum usuário, a página oferece "criar o primeiro administrador", que pede esse código, um nome de usuário, um nome e uma senha, cria a conta com o papel admin e já faz o seu login. O código tem 12 caracteres em grupos de quatro (hífens e espaços são ignorados quando você o digita), vive só na memória do processo e morre com ele: uma reinicialização antes de o administrador existir imprime um código novo, e, depois que o administrador existe, não há código nenhum. Cinco códigos errados vindos do mesmo endereço disparam uma espera que vai dobrando até 15 minutos. O mesmo passo pelo shell, contra o orbit-api exposto por port-forward como em "Entrar pelo shell", mais abaixo, com setup.json contendo setupCode, username, name e password:

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \  --data @setup.json localhost:8080/api/v1/auth/setup

A resposta é 201 com o novo usuário, 401 para um código errado e 409 quando já existe algum usuário.

Como entrar

No navegador: /login. Pelo shell, grave as credenciais em um arquivo que só você consegue ler (o printf é um builtin do shell, então a senha nunca aparece no ps):

bash
umask 077printf '{"username":"%s","password":"%s"}\n' admin 'REPLACE_WITH_THE_PASSWORD' > login.json

Troque REPLACE_WITH_THE_PASSWORD pela senha dessa conta: o conteúdo de admin-password para o administrador definido por variável de ambiente, a senha de demonstração da instalação para um usuário de demonstração, ou a senha digitada ao criar o primeiro administrador. Uma senha que contenha " ou \ precisa de escape de JSON.

Entrar pelo shell

Pelo web, do mesmo jeito que o navegador faz. A rota do web define o cookie e tira o token do corpo da resposta, então use um cookie jar. Quando a Basic auth própria do web está ligada (o default do chart; veja security.md), acrescente -u "admin:$(cat web-password)" às duas chamadas, em que admin é o WEB_AUTH_USER que você colocou no Secret e web-password é o arquivo cujo hash você gravou em WEB_AUTH_VERIFIER. YOUR_REAL_HOSTNAME é o seu ingress.host:

bash
curl -fsS -c orbit.cookies -H 'content-type: application/json' --data @login.json \  https://YOUR_REAL_HOSTNAME/api/v1/auth/logincurl -fsS -b orbit.cookies https://YOUR_REAL_HOSTNAME/api/v1/auth/me

Direto contra o orbit-api, para scripts e agentes dentro do cluster: a resposta do login traz o token, e toda chamada seguinte o envia como X-Orbit-Session, ao lado do bearer:

bash
kubectl -n sreorbit port-forward svc/sreorbit-orbit-api 8080:8080 &SESSION="$(curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \  --data @login.json localhost:8080/api/v1/auth/login | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')"curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" localhost:8080/api/v1/auth/me

$ORBIT_AUTH_TOKEN é o bearer que você gerou na instalação; no loop do k3d, leia-o do Secret do release, como mostra o install/local-k3d.md.

O que uma recusa significa

RespostaPor quê
401 unauthorizedUsuário ou senha errados. A mensagem é a mesma para um nome de usuário desconhecido, e o login leva o mesmo tempo nos dois casos, então uma recusa não revela quais contas existem.
403 forbiddenA senha estava certa e a conta está desativada.
429 rate_limited + Retry-AfterHá uma espera em andamento. Nada é conferido até ela acabar.
401 mfa_requiredA senha estava certa e a conta entra com código também: envie-o como code. Nada é contado.
401 mfa_wrongO código estava errado ou já foi usado. Conta como login com falha.

As falhas são contadas por nome de usuário e por endereço de cliente antes de qualquer senha ser conferida. Cada nome de usuário tem direito a 5 falhas livres e, depois delas, a uma espera que começa em 1 s e vai dobrando até 1 minuto; cada endereço de cliente tem direito a 20, e depois a esperas de até 15 minutos. A cota por endereço só se aplica quando um proxy de borda identificou o cliente (veja "Como o IP do cliente é determinado" em audit.md); sem ele, todo visitante chega com o endereço do web e só a cota por nome de usuário vale, para que um visitante não consiga trancar todos os outros do lado de fora. Além disso, as rotas de login aceitam 30 requisições por minuto por cliente identificado, e 300 por minuto divididas entre todos os que não foram identificados. Um login correto zera a contagem do nome de usuário, 30 minutos sem falha a apagam, e uma reinicialização do orbit-api apaga todas as contagens.

Entrada em duas etapas

Um papel com users.manage ou settings.manage entra com a senha e um código de 6 dígitos de um app autenticador (TOTP, RFC 6238: HMAC-SHA1, passos de 30 segundos, os códigos que 1Password, Bitwarden, Google Authenticator e Authy mostram). Qualquer outra conta também pode ativar. Uma conta de demonstração nunca tem: todos que leem a senha da demonstração a compartilham.

  • Cadastro. Na primeira vez que uma conta assim entra com a senha, o Deck abre /login/secure e mais nada: o orbit-api responde 403 mfa_enrollment_required a essa sessão em tudo, menos GET /api/v1/auth/me, sair e as duas chamadas abaixo. POST /api/v1/auth/mfa/setup sorteia uma chave nova de 20 bytes e a responde uma vez, em base32 e como link otpauth://. POST /api/v1/auth/mfa/confirm com {"code":"123456"} ativa: esta sessão conta como uma que deu código, e todas as outras sessões da conta terminam. Um papel que ganha uma das duas permissões depois recebe a mesma página na próxima requisição.
  • Entrar. Com o segundo fator ativo, POST /api/v1/auth/login recebe code ao lado de username e password. Sem ele, uma senha certa responde 401 mfa_required e não conta nada; um código errado, ou já usado, responde 401 mfa_wrong e conta como login com falha para o nome de usuário e o endereço, então ninguém adivinha códigos mais rápido que senhas. Cada código vale uma vez: o orbit-api guarda o último passo de tempo aceito.
  • Perdeu o celular. Um administrador desativa por PATCH /api/v1/users/{id} com {"mfa": false} (auditado como user.mfa_reset); todas as sessões dessa conta terminam, e o próximo login cadastra de novo. A regra do subconjunto vale: você só redefine uma conta cujo papel não tem nada que o seu não tenha. Desativar o seu próprio pede a sua senha e um código (veja Senhas abaixo).
  • A chave guardada. O orbit-api a sela com ORBIT_SEAL_KEY (AES-256-GCM, a mesma selagem dos segredos de banco e de SSO) quando essa chave existe, e a guarda como veio caso contrário. O chart sorteia a ORBIT_SEAL_KEY na instalação quando secrets.sealKey está vazia e mantém a que o Secret em uso guarda a cada upgrade, então uma instalação padrão sela todas as chaves. Uma chave guardada como veio antes de a instalação ter ORBIT_SEAL_KEY é selada no primeiro início com uma. Ela nunca sai do armazenamento depois da resposta do cadastro e nunca chega à trilha de auditoria. Guarde a ORBIT_SEAL_KEY com os seus outros segredos e faça backup dela: sob outra chave, ou sem nenhuma, uma chave selada deixa de ser lida, e toda conta com segundo fator recebe 401 no login, administradores inclusive. Voltar a chave antiga as recupera. Se ela se perder, uma conta que ainda entra e tem users.manage desativa o fator das outras; tenha uma conta assim (um administrador por SSO, cujo login não pede fator local) antes de trocar a chave.
  • Sessões de SSO trazem os fatores do próprio provedor de identidade: logins por Google e OIDC pulam esta etapa. Exija MFA no provedor.
  • Tokens de API de uma conta cujo papel precisa do segundo fator só funcionam depois que ele está ativo, ou quando a conta entra por SSO.
  • Rollback. Uma versão anterior a esta ignora a chave e deixa a conta entrar só com a senha; ela descarta a chave na primeira vez que regrava esse usuário, então a conta cadastra de novo quando você voltar a atualizar.

Single sign-on

Também é possível entrar por um provedor de identidade; o usuário e a senha locais continuam existindo para o admin de emergência. Cada provedor fica desligado até que um admin o configure em Admin > Integrations (settings.manage) ou que as variáveis de ambiente o semeiem, e o /login só oferece a entrada por ele enquanto ele consegue autenticar alguém. O Google é o Adendo v0.8: um Workspace, os domínios dele e um único papel para o primeiro login. O restante desta seção trata do provedor genérico do Adendo v0.19.

Qualquer provedor OpenID Connect

Um provedor por vez, ao lado do Google: Okta, Microsoft Entra ID, Keycloak, Auth0 ou qualquer outro que publique um documento de discovery. O que o admin define:

ConfiguraçãoDefaultObservações
URL do emissor (issuer)nenhumSomente https, sem parâmetros de consulta, fragmento ou credenciais. O orbit-api lê <issuer>/.well-known/openid-configuration, não segue nenhum redirecionamento e recusa um documento cujo issuer não seja exatamente esta string (o do Auth0 termina em /, o do Entra ID em /v2.0).
Client ID e secretnenhumUm client web confidencial no fluxo authorization code. O secret é somente escrita: nenhuma leitura o devolve, e a trilha de auditoria registra apenas que ele mudou.
Escoposopenid email profileopenid é obrigatório. Inclua o escopo com que o seu provedor envia os grupos (groups no Okta).
Nome de exibiçãoSSOO /login mostra "Entrar com" seguido deste nome; a trilha de auditoria identifica o provedor por ele.
Domínios de e-mail permitidosqualquer umQuando definidos, o domínio do e-mail precisa estar na lista.
Claim de e-mailemailUma claim de primeiro nível com o endereço. Quando o ID token traz email_verified, ela precisa ser true; sem ela, a pessoa ainda pode receber uma conta nova, mas nenhuma conta existente é vinculada a ela.
Claim de gruposgroupsUma lista de strings de primeiro nível (uma string sozinha também serve).
Grupo para papelnenhumLinhas em ordem: a primeira cujo grupo inclua a pessoa define o papel, admin inclusive, desde que o admin que salva a configuração tenha todas as permissões desse papel.
Papel quando nenhum grupo correspondeviewerUm papel que não gerencie usuários nem configurações, ou recusar, que nega o login.

Cadastre https://<your console>/api/v1/auth/sso/oidc/callback como URI de redirecionamento (a página de configuração a mostra com o host pelo qual você chegou até ela). Rode o Testar antes de ligar o provedor: ele lê o documento de discovery e as chaves de assinatura e depois experimenta o client ID e o secret no token endpoint com um código que não pode existir, de modo que um invalid_grant prova as credenciais. O teste não salva nada. O secret salvo só vai para o emissor salvo, com o client ID salvo: para testar outro emissor ou outro client, digite o secret dele. Todo teste grava settings.test na trilha de auditoria, com o emissor, o client ID e o resultado de cada verificação.

O fluxo. A rota GET /api/v1/auth/sso/oidc/start do web pede ao orbit-api que abra um fluxo (state, nonce e um verificador PKCE S256, de uso único, válido por 10 minutos), guarda o vínculo dele no mesmo cookie HttpOnly que o fluxo do Google usa e manda o navegador para o provedor. O provedor devolve o navegador para /api/v1/auth/sso/oidc/callback; o web entrega o state, o vínculo e o código ao orbit-api, que troca o código usando o verificador (client_secret_post quando o discovery o lista, client_secret_basic nos demais casos) e confere o ID token:

  • assinado em RS256, PS256 ou ES256 por uma chave do JWKS do provedor, nunca none nem um HMAC; chaves RSA de 2.048 bits ou mais, chaves EC em P-256, e uma chave que o JWKS prende a um algoritmo só serve para ele;
  • o JWKS é lido com limite de 1 MiB e timeout de 10 s e fica em cache pelo max-age dele (de 5 minutos a um dia); um kid desconhecido o busca de novo no máximo a cada 30 s, então uma rotação de chaves é percebida e uma enxurrada de kids inventados não é;
  • iss exatamente o emissor configurado; aud contém o client ID, e azp precisa ser o client ID quando há várias audiências ou sempre que estiver presente;
  • exp, nbf e iat dentro de 60 s de tolerância de relógio e emitidos durante o fluxo; o nonce precisa ser o do próprio fluxo;
  • depois, o e-mail, o email_verified, o domínio e os grupos, como na tabela.

Contas. Entra a conta vinculada ao subject do provedor (sso: "oidc:<sub>"); na falta dela, a única conta local com o e-mail (sem diferenciar maiúsculas ASCII, que não seja conta de demo nem esteja vinculada a outro provedor) é vinculada, mas só quando o ID token diz email_verified: true (senão, email_unverified) e o titular da conta definiu esse e-mail, ou o salvou, com a própria senha e um código. Um e-mail que outro administrador digitou na conta de alguém não vincula nada (email_unproven) até o titular salvá-lo com essa prova no próprio painel lateral em /deck/admin/users. Na falta dessa, uma conta nova é criada, com o nome de usuário tirado da parte local do e-mail. Com um mapeamento de grupos, o papel que ele define é gravado na conta a cada login: um grupo removido no provedor retira o papel no login seguinte, e um evento user.role_change registra isso. Sem mapeamento, o papel padrão vale só para contas novas e os admins mudam papéis no Deck, como no Google. Se a mudança de papel não deixasse nenhum usuário ativo com users.manage, o login é recusado em vez disso (last_admin). A configuração guarda as permissões do admin que a salvou, e nenhum login por ela cai numa conta cujo papel tenha mais do que isso (beyond_provider): quem gerencia configurações, mas não tudo, não consegue apontar o console para um provedor de identidade próprio e entrar como admin. Configurações salvas antes desta regra, e as que vêm do ambiente, não têm esse limite. A sessão é a comum: 24 horas, revogável.

Recusas e a trilha. Cada login grava auth.login com method: "oidc", o nome do provedor, o emissor e o papel. Cada recusa grava auth.login_failed com os mesmos campos e um reason: invalid_state, expired, off, cancelled, provider_error, exchange_failed, invalid_token (com o check que falhou: format, algorithm, key, signature, issuer, audience, expired, not_before, issued_at, nonce ou subject), unavailable, no_email, email_unverified, domain_not_allowed, no_group, disabled ou um conflito de conta (linked_elsewhere, ambiguous_email, email_unproven, demo_account, role_missing, default_role_missing, default_role_unsafe, last_admin, beyond_provider). Quem é recusado volta para /login?oidc=<why>, com a explicação no seu idioma. As duas rotas são contadas em orbit_http_requests_total, por status, como POST /api/v1/auth/sso/oidc/start e POST /api/v1/auth/sso/oidc/callback.

Semeando pelas variáveis de ambiente. Enquanto o armazenamento não tem configuração de OIDC, o orbit-api lê as ORBIT_SSO_OIDC_* (configuration.md); a partir do primeiro salvamento no console, valem as configurações do console. O client secret fica no Secret (secrets.ssoOidcClientSecret no chart). Um client secret salvo no console, de OIDC ou do Google, fica no armazenamento selado com ORBIT_SEAL_KEY (AES-256-GCM, a mesma chave das conexões de banco de dados) quando essa variável está definida; um que uma versão anterior guardou em claro é selado no próximo salvamento da página dele. Depois de um rollback para uma versão sem selagem, o login por esse provedor também para: ela envia o texto selado como segredo, então digite o segredo de novo na página do provedor depois do rollback. Um salvamento que muda o issuer ou o client ID pede o client secret de novo: o guardado só vai para o issuer e o client para os quais foi digitado. Sem ORBIT_SEAL_KEY, o armazenamento o guarda como foi digitado. Se você trocar a chave, o login por esse provedor para até um admin digitar o segredo de novo. Para ler o que está em vigor, com a SESSION de um admin obtida como em "Entrar pelo shell":

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \  localhost:8080/api/v1/settings/sso/oidc

Senhas

O orbit-api guarda um verificador PBKDF2-HMAC-SHA256 para cada senha que define: 600.000 iterações, um salt aleatório de 16 bytes, um hash de 32 bytes, o mesmo formato do WEB_AUTH_VERIFIER do próprio web. Uma senha nova precisa ter no mínimo 12 caracteres, no máximo 128, nenhum caractere de controle, não pode ser igual ao nome de usuário e não pode estar entre as 10.000 senhas de 12 caracteres ou mais que mais vazaram (SecLists, tag 2025.3, sem diferenciar maiúsculas). Não há regras de composição nem expiração. O login ainda aceita até 1.024 bytes, então uma senha mais longa definida antes continua valendo.

  • A sua própria senha: a página Conta (/deck/account), ou POST /api/v1/auth/password com {current, next}. Um current errado resulta em 400 e conta como um login com falha para o seu nome de usuário. Todas as suas outras sessões terminam; esta continua.
  • A de outra pessoa: um administrador define uma nova pelo painel lateral do usuário em /deck/admin/users, ou por PATCH /api/v1/users/{id} com password. Todas as sessões desse usuário terminam.
  • A sua própria por PATCH /api/v1/users/{id} no seu próprio id, com password ou {"mfa": false}: envie a sua senha em current e, com o segundo fator ligado, também um code novo. Sem eles, ou com um errado, o orbit-api responde 400 (mfa_required ou mfa_wrong para o código), conta um login com falha para o seu nome de usuário e audita a recusa. Quem roubou a sua sessão não consegue definir uma senha e uma chave próprias e trancar você do lado de fora. Todas as suas outras sessões terminam; esta continua.
  • O seu próprio e-mail pela mesma rota pede a mesma prova: o SSO vincula uma conta pelo e-mail, então sem isso uma sessão roubada apontaria a sua conta para um endereço que o ladrão tem no provedor. Sem senha, a resposta é 400 e não conta tentativa. Um e-mail que um administrador define na conta de outra pessoa fica salvo, e o SSO não vincula essa conta por ele até o titular salvá-lo com a própria senha e um código.
  • Depois de uma prova (a sua senha e um código aqui, num token, ou um novo login no provedor), a mesma sessão não precisa de outra por 5 minutos.
  • Cada uma dessas mudanças, em qualquer conta, publica um aviso de segurança nos canais de alerta que os recebem (alert-notifications.md).
  • Uma senha que um administrador digitou, ao criar um usuário ou redefinir a de outra pessoa, vale só como primeira senha: o próximo login cai em /login/secure e a troca antes de qualquer outra coisa (o orbit-api responde 403 password_change_required a todo o resto). Depois, um papel que precisa cadastra o segundo fator.
  • Uma senha definida antes de entrar na lista de vazadas ainda entra, e cai na mesma página.
  • Todo campo de senha nova no Deck mostra um medidor de força enquanto você digita. É uma estimativa pelo tamanho e pela mistura de caracteres; quem decide são as regras do orbit-api acima.

Sessões

  • Token. Um session id de 32 dígitos hexadecimais e uma assinatura HMAC-SHA256 sobre ele. Um token forjado ou alterado é recusado antes de qualquer busca no armazenamento. A chave é o ORBIT_SESSION_SECRET, quando definido (32 bytes ou mais); caso contrário, o orbit-api gera uma chave de 32 bytes uma única vez e a guarda em ORBIT_DATA_DIR/session.key. Trocar o segredo ou apagar o arquivo encerra todas as sessões de uma vez.
  • Duração. 24 horas a partir do login, com prazo absoluto: a atividade não o estende. Uma sessão que nenhuma requisição usou por 8 horas também termina, e a requisição seguinte recebe 401. Uma aba do Deck aberta só continua lendo enquanto o navegador a deixa rodar: uma aba congelada, ou um notebook dormindo, conta como nenhuma requisição. Reiniciar o orbit-api zera a contagem de inatividade de todas as sessões. Um usuário mantém no máximo 100 sessões; as mais antigas saem primeiro. As expiradas são removidas no máximo uma vez a cada 10 minutos.
  • Revogação. Uma sessão também é um documento em ORBIT_DATA_DIR/sessions, apagado no logout, na desativação da conta, numa troca ou redefinição de senha e pela ação "Encerrar todas as sessões" (POST /api/v1/users/{id}/revoke-sessions). A próxima requisição com esse token recebe 401. Uma troca ou redefinição de senha, e o segundo fator desligado, também apagam todos os tokens de API da conta (veja mcp.md).
  • Suas próprias sessões. Em Conta, "Suas sessões" lista todo navegador conectado à sua conta (GET /api/v1/auth/sessions: quando entrou, de qual endereço e navegador, quando termina e qual delas é este navegador). Digitar sua senha ali encerra as outras (POST /api/v1/auth/sessions/end-others, com o mesmo limite de tentativas do login e auditado como auth.sessions_end_others). Uma conta de demonstração vê só a própria sessão e não encerra nenhuma. Uma conta criada pelo Google ou pelo OIDC não tem senha: a página oferece "Entrar de novo pelo Google" (ou pelo nome do seu provedor) no lugar do campo. A sessão que essa entrada abre encerra as outras sem senha por 5 minutos, e só quando o id_token do provedor diz, em auth_time, que você entrou lá depois do clique, com um minuto de tolerância para a diferença entre relógios. Com um auth_time mais antigo, ou sem ele, você recebe uma sessão comum, e a página avisa que o provedor não confirmou que pediu suas credenciais. "Alterar senha" avisa que a conta não tem senha, em vez de mostrar um formulário que ela não consegue usar. No OIDC, o orbit-api envia prompt=login e max_age=0. O primeiro pede suas credenciais ao provedor; o segundo torna auth_time uma claim obrigatória (OpenID Connect Core 3.1.2.1). O Google não aceita pedido de nova autenticação: a entrada pode aproveitar a sessão do Google que seu navegador já tem, e aí o auth_time é antigo. O Google só envia auth_time quando a requisição pede, o que o orbit-api faz com claims={"id_token":{"auth_time":{"essential":true}}}, e só com "Session age claims" ligado em Google Auth Platform, Settings, Advanced settings (o app precisa estar em produção e verificado). Sem essa opção, uma conta do Google sem senha não consegue encerrar as próprias outras sessões; um admin consegue, com "Encerrar todas as sessões". Para receber um auth_time novo, saia da sua conta do Google nesse navegador antes e depois entre de novo.
  • Mudanças de papel. As permissões são lidas do papel do usuário a cada requisição, então uma troca de papel, ou uma edição do próprio papel, vale a partir da próxima requisição, sem novo login.
  • O cookie. __Host-orbit_session quando o navegador está em https (X-Forwarded-Proto, ou um publicUrl https, que prevalece sobre esse header: veja configuration.md), com Secure e sem Domain, e orbit_session no http puro; HttpOnly, SameSite=Lax, Path=/ e um Max-Age igual ao tempo de vida que resta à sessão. Só as duas rotas do web, api/v1/auth/login e api/v1/auth/logout, o escrevem; o JavaScript da página não consegue lê-lo. O web copia o valor dele para o X-Orbit-Session e nunca repassa o header Cookie do navegador.

Seus dados

Em Conta, "Seus dados" baixa o que o orbit-api guarda sobre você num arquivo JSON (GET /api/v1/auth/export, auditado como user.export): a sua conta, as suas sessões, os nomes e a validade dos seus tokens de API, as visões salvas, consultas SQL e conversas do Nocturne que são suas, e os eventos de auditoria que você causou nos últimos 90 dias, no máximo 1.000. Ele não traz verificador de senha, chave de segundo fator, segredo de token nem webhook. Uma conta de demonstração é compartilhada e não exporta nada (403). Para remover os seus dados, apague as suas visões, consultas e conversas onde você as criou; um administrador apaga a própria conta.

Papéis e permissões

Um usuário tem exatamente um papel, e um papel é um conjunto de permissões tiradas desta lista fechada. Cada rota exige uma delas; o Deck esconde as seções que um papel não concede e as recusa antes de a página ler qualquer coisa.

PermissãoO que concedeSeção do Deck
estate.readClusters, nodes, workloads, eventos, alertas, FinOps, recomendações, eventos de workload e as rotas de leitura do Nocturne/deck e tudo abaixo dele que não aparece nas linhas seguintes
telemetry.queryquery_range, as leituras de labels, de séries e instantâneas do engine, a ferramenta de PromQL do Nocturne/deck/observability, /deck/explore, todo painel de dashboard
apm.readTraces, serviços, operações e o mapa de serviços/deck/apm
logs.readLogs de contêiner dos pods de um workload, e os logs armazenadosA aba Logs de um workload, /deck/logs
databases.queryMonitoramento de bancos e SQL somente leitura nas conexões de banco que o papel alcança (/api/v1/databases, POST /api/v1/sql/query e /explain com um banco)/deck/databases, /deck/sql
databases.raw_sqlCom databases.query: as execuções recentes de uma instrução monitorada com os valores, cada revelação auditada"Mostrar valores" na gaveta de uma instrução
dashboards.readListar e abrir dashboards/deck/dashboards
dashboards.writeCriar, alterar e excluir dashboards salvosEditar e Salvar em um dashboard
nocturne.usePOST /api/v1/nocturne/chat e /analyze/deck/nocturne
workloads.writeEscritas de escala e de recursos, suspender, retomar e disparar CronJobs, reconhecimentos e silenciamentos de alertas, nunca no namespace do próprio orbit-api nem em kube-systemA aba Escala e recursos
config.readO ambiente de um workload comparado aos seus ConfigMaps e Secrets, e revelar um valor mascarado, nunca no namespace do próprio orbit-api; a ferramenta de ConfigMaps do Nocturne, os valores de env na ferramenta de pods dele e os valores que a checagem de patch dele compara (sem esta permissão, cada variável mostra o nome, a origem e o valor [redacted]); toda visualização e toda revelação são auditadasA aba Configuração de um workload
users.manageUsuários, papéis, a lista de leads de vendas/deck/admin, /deck/admin/users, /deck/admin/roles, /deck/admin/leads
audit.readA trilha de auditoria e a exportação dela em CSV/deck/admin/audit
settings.manageA página de configurações do console, as regras de ingestão, e a fatura da conta AWS na visão geral do FinOps/deck/settings, /deck/admin/ingestion

workloads.write é necessária, mas não suficiente: uma mudança de escala ou de recursos também exige que a instalação permita escritas (ORBIT_WRITE_ENABLED=true com o ClusterRole de escrita, Adendo v0.4) e o token de operador no salto do web. Abrir um dashboard exige dashboards.read, e desenhar os painéis dele exige também telemetry.query: um papel com a primeira e sem a segunda vê o layout com todos os painéis recusados.

Papéis embutidos

PapelPermissões
viewerestate.read, telemetry.query, apm.read, logs.read, dashboards.read
editorTudo o que o viewer tem, mais dashboards.write, nocturne.use e workloads.write
adminTodas as permissões da lista

Os papéis embutidos ficam no binário: nada no diretório de dados consegue alterá-los, e uma edição ou uma exclusão é recusada com 400. Para outro conjunto, crie um papel personalizado (ou clone um embutido no Deck e edite a cópia).

Papéis personalizados e as regras que protegem uma instalação

  • Um papel personalizado tem um nome (de 1 a 64 caracteres, único), uma descrição de até 280 caracteres e qualquer subconjunto das permissões acima; uma permissão desconhecida é recusada com 400.
  • Um papel personalizado pode listar as conexões de banco que a sua databases.query alcança (databases, até 64 ids de conexão); nenhuma listada é toda conexão. Fora da lista uma conexão responde 404 em toda rota de banco. Veja databases.md, "Um papel para um time de bancos".
  • Um papel que algum usuário tenha não pode ser excluído (409): mova os usuários dele antes.
  • Ninguém muda o próprio papel, desativa a própria conta nem a exclui (400).
  • Ninguém concede mais do que tem. Criar ou editar um papel, dar um papel a um usuário e alterar, redefinir a senha, desativar, excluir ou encerrar as sessões de uma conta exigem que o papel de quem age tenha todas as permissões envolvidas; senão, a resposta é 403 e um evento access.denied com reason: "subset". Nos papéis embutidos só o admin gerencia usuários, então nada muda; um papel personalizado com users.manage gerencia só as contas e os papéis abaixo dele. A mesma regra vale para os papéis que uma configuração de SSO concede, e para conexões de banco: quem age com um papel que lista algumas concede e mexe só em papéis que listam algumas delas.
  • Nenhuma mudança pode deixar zero usuários ativos com users.manage: uma desativação, uma exclusão, uma troca de papel ou uma edição de papel que levaria a isso é recusada com 409.

Gerenciar usuários e papéis

No Deck, com users.manage: /deck/admin/users cria usuários, troca papéis, redefine senhas, desativa, ativa e exclui contas e encerra sessões; /deck/admin/roles cria, edita, clona e exclui papéis personalizados e mostra a matriz de permissões completa. Pelo shell, com a SESSION de um administrador obtida como em "Entrar pelo shell", mais acima: liste os papéis, crie um usuário, promova-o e encerre as sessões dele.

bash
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" localhost:8080/api/v1/rolescurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \  -d '{"username":"grace","name":"Grace Hopper","email":"grace@example.com","role":"viewer","password":"REPLACE_WITH_AN_INITIAL_PASSWORD","current":"REPLACE_WITH_YOUR_PASSWORD","code":"CODE"}' \  localhost:8080/api/v1/userscurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \  -X PATCH -d '{"role":"editor","current":"REPLACE_WITH_YOUR_PASSWORD","code":"CODE"}' localhost:8080/api/v1/users/USER_IDcurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -X POST \  localhost:8080/api/v1/users/USER_ID/revoke-sessions

Criar um usuário, e definir a senha, o segundo fator, o e-mail ou o papel de outra conta, pede a sua própria senha em current e, com o segundo fator ligado, um code: sem eles, a resposta é 400, auditada como recusa no seu nome. Uma prova vale para a mesma sessão por 5 minutos. Salvar as configurações do Google ou do OIDC pede a mesma prova: um provedor deixa pessoas entrarem. Nome, desativação, exclusão e encerrar sessões não pedem nada: só tiram acesso. REPLACE_WITH_YOUR_PASSWORD e CODE são seus, digitados de novo.

REPLACE_WITH_AN_INITIAL_PASSWORD é uma senha que você escolhe para o novo usuário (12 caracteres ou mais, diferente do nome de usuário) e entrega por um canal em que confia. USER_ID é o campo id desse usuário na resposta da chamada de criação, ou em GET /api/v1/users (16 dígitos hexadecimais), e não o nome de usuário. Todos os formatos e erros dessas rotas estão em api.md; cada mudança acima entra na trilha de auditoria com o nome do que mudou (user.role_change, user.disable, user.password_reset, ...).

Onde o estado fica

Tudo o que esta página descreve fica em arquivos sob ORBIT_DATA_DIR (default /var/lib/sreorbit), um documento JSON por objeto, cada um gravado num arquivo temporário, sincronizado com fsync e renomeado para o lugar final, então uma queda deixa a versão antiga ou a nova, e nunca metade de uma delas:

CaminhoO que guarda
users/Um documento por usuário, com o verificador da senha
roles/Papéis personalizados (os embutidos ficam no binário)
sessions/Um documento por sessão ativa
dashboards/Dashboards salvos (dashboards.md)
alertstate/Reconhecimentos e silenciamentos de alertas, um documento por cluster
leads/Envios do formulário de contato do site
settings/Configurações de login: sso para o Google, oidc para o provedor OpenID Connect, secrets incluídos
audit/A trilha de auditoria, um arquivo JSONL por dia UTC (audit.md)
changes/A linha do tempo de mudanças, um arquivo JSONL por cluster e dia UTC, 14 dias (audit.md)
changestate/O que o último ciclo da linha do tempo de mudanças viu, um documento por cluster
session.keyA chave que assina as sessões, quando ORBIT_SESSION_SECRET não está definido

O orbit-api se recusa a iniciar quando o diretório não é gravável. O armazenamento tem um único escritor, e é por isso que todo caminho de instalação roda o orbit-api com uma réplica: o chart renderiza replicas: 1, não importa o que diga o replicaCount, e se recusa a renderizar com autoscaling ligado (components.orbit-api.singleWriter). Com components.orbit-api.persistence.enabled, o diretório é um claim ReadWriteOnce e o Deployment usa Recreate; sem isso, é um emptyDir, que perde todos os usuários, sessões, dashboards e linhas de auditoria junto com o pod. O compose monta o volume nomeado orbit-api-data. Backups: operations.md.

O Nocturne age como quem está logado

Quando alguém faz uma pergunta ao Nocturne, o proxy do orbit-api repassa o X-Orbit-Session dessa pessoa ao nocturne, e toda chamada de ferramenta de cluster que o Nocturne faz o leva de volta ao orbit-api. Por isso, uma ferramenta lê exatamente o que essa pessoa pode ler (a ferramenta de PromQL exige telemetry.query; as demais, estate.read), e uma recusa entra na trilha de auditoria em nome dela.

Tetos

  • Um provedor OpenID Connect por vez, ao lado do Google; sem SAML. Os grupos precisam vir numa claim de primeiro nível do ID token: o group overage do Entra ID (acima de 200 grupos ele manda um link no lugar) não é seguido. ORBIT_AUTH_MODE=oidc, que trata do bearer de serviço e não de pessoas, continua se recusando a iniciar.
  • TOTP é o único segundo fator local. Sem chaves WebAuthn ou FIDO e sem códigos de recuperação: celular perdido é redefinição pelo administrador. Sem SCIM, sem expiração de senha.
  • Uma réplica. O armazenamento em arquivos tem um único escritor; o caminho de evolução indicado no código é o Postgres, que é o que permite ao orbit-api escalar horizontalmente.
  • As esperas de login são por processo. Uma reinicialização do orbit-api as apaga, algo com que uma réplica única consegue conviver.
  • Sem escopo por dashboard ou por cluster. Uma permissão vale para todos os clusters e todos os dashboards salvos.

Para onde ir em seguida

  • O que cada mudança e cada recusa deixam para trás, e como ler isso: audit.md.
  • O modelo de ameaças em torno de sessões, cookies e requisições cross-site: security.md.
  • Cada variável desta página com o seu default: configuration.md.