12 · Identidade e acesso

Nem toda aplicação tem usuários: um site, uma landing, uma página de documentação podem ser públicos, sem login. Isso é uma decisão declarada, não uma omissão:

Toda aplicação, pública ou não, cumpre o contrato de observabilidade e tem /up.

1. Realm por população, não por aplicação. Colaboradores da Hibex em hibex-team; clientes externos em realm de produto (ex.: hibex-enterprise). Colaborador e cliente nunca no mesmo realm (toolbox ADR-0008). Criar realm é decisão do toolbox;
2. Um client por aplicação, confidencial, Authorization Code com PKCE S256, directAccessGrantsEnabled=false, redirect e post-logout redirect exatos (produção + localhost);
3. O código confere permissões, nunca perfis. O perfil é organização de pessoas; o código não muda quando um perfil ganha ou perde uma permissão;
4. Ninguém recebe papel direto no usuário. Perfil vai para grupo (toolbox ADR-0034); quando toda a população tem o mesmo acesso, o perfil vai para os default roles do realm — e isso também é declarado;
5. A aplicação lê resource_access.<client-id>.roles do access token, sem chamada extra por requisição;
6. Sem senha nem sessão local. O Keycloak autentica: a aplicação não tem login, senha nem cadastro de usuário próprios. Ela pode, sim, manter uma sessão (um cookie), mas essa sessão guarda só os tokens do Keycloak e expira com eles; nunca é uma conta da aplicação;
7. Sem acesso de negado mudo. Autenticado sem permissão vê uma página que diz qual perfil (e qual grupo) dá acesso;
8. Configuração como código. eng/auth/provision.sh <realm> é idempotente: cria o que falta, atualiza o que existe, reexecutar não muda nada; nunca regenera segredo de client (só lê e imprime para guardar no Bitwarden);
9. IdP externo (Google) por script, com credenciais do ambiente — nunca no export do realm versionado; um OAuth client do Google por realm;
10. Realms de desenvolvimento versionados em eng/auth/dev-realms/, gerados a partir do provision.sh, com um usuário de exemplo por perfil (senha = primeiro nome) e um usuário sem nenhum perfil, e segredos de client óbvios (dev-secret-<client>).

Ambientes e realms

Uma stack tem dois ambientes: o local, com o Keycloak descartável do Compose e os realms de desenvolvimento da regra 10, e a produção, com os realms reais. O toolbox já criou o hibex-enterprise-dev (a ADR-0039 de lá), um realm na instância real para ambientes implantados de desenvolvimento do produto Hibex Enterprise. Por enquanto, nenhuma stack o usa: um ambiente implantado de desenvolvimento pede ainda um realm para os colaboradores (não há um hibex-team-dev, e o hibex-team nunca serve de bancada de testes), um host, um valor de deployment.environment e um projeto no Bitwarden. A arquitetura o define quando a primeira stack precisar testar implantada. Até lá, o provision.sh já recebe o realm como argumento (regra 8): é o que permite, depois, rodá-lo em outro realm sem mudar o script.

(Exemplo ilustrativo, no produto fictício de 03. O modelo pede o desenho fino desde o início, mesmo que a primeira versão tenha um perfil com todas as permissões — assim um perfil novo não exige mexer no código.)

Orientações:

• Permissão nomeia um recurso e uma ação do ponto de vista do negócio: carteira:conceder, não POST /carteiras. Ações típicas: ler, criar, editar, excluir, mais verbos do domínio (publicar, atender, aprovar);
• Perfil nomeia um papel de trabalho reconhecível pelas pessoas: gestor, analista, financeiro, cliente;
• O mínimo de toda aplicação com usuários: uma permissão de entrada (<app>:acessar) e um perfil;
• Permissões de API (para outras aplicações) têm o prefixo api: — ex.: api:chamado:ler —, para nunca se confundirem com permissões de tela.

Cada aplicação tem o seu. É o documento que o administrador do realm, o mantenedor e uma equipe de outra aplicação leem para saber "quem pode o quê". Estrutura obrigatória:

# Acesso — <app>

## Resumo
| Realm | Client | Endereço | Perfil padrão |
|---|---|---|---|

## Permissões
| Permissão | O que permite | Telas / rotas | Desde (change) |
|---|---|---|---|
| chamado:ler | ver a lista e o detalhe dos chamados | /chamados, /chamados/{id} | identidade |

## Perfis
| Perfil | Para quem | Grupo | Permissões |
|---|---|---|---|
| perfil:gestor | quem conduz os atendimentos | atendimento-gestores | chamado:ler, chamado:atender, … |

## Matriz perfil × permissão
| Permissão \ Perfil | gestor | analista | financeiro |
|---|---|---|---|
| chamado:ler | ✓ | ✓ | |

## Como dar acesso a uma pessoa
1. No realm <realm>, Usuários → a pessoa → Grupos → entrar em <grupo>;
2. A pessoa sai e entra de novo (o token novo traz o perfil).

## Como outra aplicação obtém acesso à API desta
(permissões `api:*`, audiência, exemplo de token — ver seção do guia)

## Usuários de desenvolvimento
| Usuário / senha | Perfil | Serve para |
|---|---|---|
| ana.souza / ana | gestor | caminho feliz da gestão |
| bruno.dias / bruno | nenhum | ver o 403 explicativo |

## Histórico
| Data | Change | O que mudou no acesso |

A seção Matriz é verificada de ponta a ponta pelo agrupamento E2E identidade: um caso por perfil confere o que ele vê e o que não vê.

Quando uma aplicação B precisa chamar a API da aplicação A (de outra stack ou da mesma), o padrão é client credentials com a conta de serviço de B recebendo permissões api:* do client de A.

Quem faz o quê:

Regras: a aplicação provedora nunca confia num token sem aud próprio; tokens de usuário não são repassados entre aplicações (cada chamada de serviço usa a conta de serviço de quem chama).

Mudou acesso? A change mexe no provision.sh, roda o dev-realms.sh, confere o diff dos JSON, atualiza docs/acesso/<app>.md e os casos do agrupamento identidade.

Roteiro que o mantenedor segue; o agente só o escreve.

Oferecidas como guia (não obrigatórias):