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.
| Credencial | Quem a guarda | O que ela prova | Por onde trafega |
|---|---|---|---|
Bearer de serviço ORBIT_AUTH_TOKEN | Só o servidor do web | Que a chamada veio pelo web (Adendo v0.2) | Authorization: Bearer ... em toda chamada repassada pelo proxy |
| Token de sessão | O navegador, dentro de um cookie HttpOnly | Qual pessoa está pedindo | Cookie 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:
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:
kubectl -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_codeNo 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:
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \ --data @setup.json localhost:8080/api/v1/auth/setupA 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):
umask 077printf '{"username":"%s","password":"%s"}\n' admin 'REPLACE_WITH_THE_PASSWORD' > login.jsonTroque 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:
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/meDireto 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:
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
| Resposta | Por quê |
|---|---|
401 unauthorized | Usuá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 forbidden | A senha estava certa e a conta está desativada. |
429 rate_limited + Retry-After | Há uma espera em andamento. Nada é conferido até ela acabar. |
401 mfa_required | A senha estava certa e a conta entra com código também: envie-o como code. Nada é contado. |
401 mfa_wrong | O 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/securee mais nada: oorbit-apiresponde403 mfa_enrollment_requireda essa sessão em tudo, menosGET /api/v1/auth/me, sair e as duas chamadas abaixo.POST /api/v1/auth/mfa/setupsorteia uma chave nova de 20 bytes e a responde uma vez, em base32 e como linkotpauth://.POST /api/v1/auth/mfa/confirmcom{"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/loginrecebecodeao lado deusernameepassword. Sem ele, uma senha certa responde401 mfa_requirede não conta nada; um código errado, ou já usado, responde401 mfa_wronge 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: oorbit-apiguarda o último passo de tempo aceito. - Perdeu o celular. Um administrador desativa por
PATCH /api/v1/users/{id}com{"mfa": false}(auditado comouser.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-apia sela comORBIT_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 aORBIT_SEAL_KEYna instalação quandosecrets.sealKeyestá 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 terORBIT_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 aORBIT_SEAL_KEYcom 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 recebe401no login, administradores inclusive. Voltar a chave antiga as recupera. Se ela se perder, uma conta que ainda entra e temusers.managedesativa 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ção | Default | Observações |
|---|---|---|
| URL do emissor (issuer) | nenhum | Somente 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 secret | nenhum | Um 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. |
| Escopos | openid email profile | openid é obrigatório. Inclua o escopo com que o seu provedor envia os grupos (groups no Okta). |
| Nome de exibição | SSO | O /login mostra "Entrar com" seguido deste nome; a trilha de auditoria identifica o provedor por ele. |
| Domínios de e-mail permitidos | qualquer um | Quando definidos, o domínio do e-mail precisa estar na lista. |
| Claim de e-mail | email | Uma 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 grupos | groups | Uma lista de strings de primeiro nível (uma string sozinha também serve). |
| Grupo para papel | nenhum | Linhas 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 corresponde | viewer | Um 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
nonenem 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-agedele (de 5 minutos a um dia); umkiddesconhecido o busca de novo no máximo a cada 30 s, então uma rotação de chaves é percebida e uma enxurrada dekids inventados não é; issexatamente o emissor configurado;audcontém o client ID, eazpprecisa ser o client ID quando há várias audiências ou sempre que estiver presente;exp,nbfeiatdentro de 60 s de tolerância de relógio e emitidos durante o fluxo; ononceprecisa 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":
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \ localhost:8080/api/v1/settings/sso/oidcSenhas
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), ouPOST /api/v1/auth/passwordcom{current, next}. Umcurrenterrado resulta em400e 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 porPATCH /api/v1/users/{id}compassword. Todas as sessões desse usuário terminam. - A sua própria por
PATCH /api/v1/users/{id}no seu próprio id, compasswordou{"mfa": false}: envie a sua senha emcurrente, com o segundo fator ligado, também umcodenovo. Sem eles, ou com um errado, oorbit-apiresponde400(mfa_requiredoumfa_wrongpara 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 é
400e 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/securee a troca antes de qualquer outra coisa (oorbit-apiresponde403 password_change_requireda 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-apiacima.
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, oorbit-apigera uma chave de 32 bytes uma única vez e a guarda emORBIT_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 oorbit-apizera 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 recebe401. Uma troca ou redefinição de senha, e o segundo fator desligado, também apagam todos os tokens de API da conta (vejamcp.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 comoauth.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, emauth_time, que você entrou lá depois do clique, com um minuto de tolerância para a diferença entre relógios. Com umauth_timemais 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, oorbit-apienviaprompt=loginemax_age=0. O primeiro pede suas credenciais ao provedor; o segundo tornaauth_timeuma 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í oauth_timeé antigo. O Google só enviaauth_timequando a requisição pede, o que oorbit-apifaz comclaims={"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 umauth_timenovo, 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_sessionquando o navegador está em https (X-Forwarded-Proto, ou umpublicUrlhttps, que prevalece sobre esse header: vejaconfiguration.md), comSecuree semDomain, eorbit_sessionno http puro;HttpOnly,SameSite=Lax,Path=/e umMax-Ageigual ao tempo de vida que resta à sessão. Só as duas rotas doweb,api/v1/auth/logineapi/v1/auth/logout, o escrevem; o JavaScript da página não consegue lê-lo. Owebcopia o valor dele para oX-Orbit-Sessione nunca repassa o headerCookiedo 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ão | O que concede | Seção do Deck |
|---|---|---|
estate.read | Clusters, 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.query | query_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.read | Traces, serviços, operações e o mapa de serviços | /deck/apm |
logs.read | Logs de contêiner dos pods de um workload, e os logs armazenados | A aba Logs de um workload, /deck/logs |
databases.query | Monitoramento 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_sql | Com 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.read | Listar e abrir dashboards | /deck/dashboards |
dashboards.write | Criar, alterar e excluir dashboards salvos | Editar e Salvar em um dashboard |
nocturne.use | POST /api/v1/nocturne/chat e /analyze | /deck/nocturne |
workloads.write | Escritas 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-system | A aba Escala e recursos |
config.read | O 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 auditadas | A aba Configuração de um workload |
users.manage | Usuários, papéis, a lista de leads de vendas | /deck/admin, /deck/admin/users, /deck/admin/roles, /deck/admin/leads |
audit.read | A trilha de auditoria e a exportação dela em CSV | /deck/admin/audit |
settings.manage | A 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
| Papel | Permissões |
|---|---|
viewer | estate.read, telemetry.query, apm.read, logs.read, dashboards.read |
editor | Tudo o que o viewer tem, mais dashboards.write, nocturne.use e workloads.write |
admin | Todas 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.queryalcança (databases, até 64 ids de conexão); nenhuma listada é toda conexão. Fora da lista uma conexão responde404em toda rota de banco. Vejadatabases.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 é
403e um eventoaccess.deniedcomreason: "subset". Nos papéis embutidos só oadmingerencia usuários, então nada muda; um papel personalizado comusers.managegerencia 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 com409.
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.
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-sessionsCriar 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:
| Caminho | O 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.key | A 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-apiescalar horizontalmente. - As esperas de login são por processo. Uma reinicialização do
orbit-apias 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.