Autenticação e autorização¶
Como o token é validado¶
A identidade vem do Keycloak. O middleware middlewares/keycloak_auth.py valida
o JWT com PyJWKClient e algorithms=['RS256'] — ou seja, busca a chave
pública do realm e verifica a assinatura. O servidor não emite token próprio;
ele apenas confere o que o Keycloak assinou.
Três dependências saem daí, e os nomes importam porque a suíte de testes os substitui um a um:
get_current_user- Exige token válido. Falha com
401se não houver. get_current_user_optional- Resolve o usuário se houver token; devolve
Noneem vez de falhar. require_admin- Exige token válido e papel de administrador.
Os papéis¶
São dois, e a diferença entre eles é estreita e precisa:
- admin
- Pode tudo: criar e apagar aplicação, criar e apagar parâmetro, alterar qualquer campo de qualquer parâmetro, e mudar a configuração em runtime.
- user
- Pode alterar apenas o campo
valuede parâmetros marcados comuser_editable=True. Qualquer outra coisa é403.
O que faz valer é AppService._validate_permission, que diffa os campos
restritos de metadado. A pergunta que ele responde não é "o usuário mexeu no
valor?", e sim "o usuário mexeu em algo além do valor?".
READ_AUTH_MODE¶
De fábrica, ler parâmetro é anônimo. Isso não é descuido: é o comportamento histórico, e o servidor não negocia versão de cliente — apertar o controle de um dia para o outro derrubaria toda frota que ainda não manda token.
O modo é resolvido pelo RuntimeConfigService, que dá precedência ao valor
gravado no banco (alterável por administrador sem redeploy) e cai para o
.env quando não há sobrescrita.
| Modo | O que faz |
|---|---|
off |
Comportamento histórico. Leitura anônima liberada, sem custo de resolução |
warn |
Continua liberando, mas conta e loga cada leitura sem token |
enforce |
Passa a exigir token. Sem token, 401 |
O critério de promoção¶
O warn existe para produzir uma medição, e não para avisar alguém. Ele
alimenta a métrica de leituras anônimas.
Só promova para enforce com a métrica zerada
Enquanto anonymous_reads_total não estiver zerado no ambiente, existe
consumidor sem token — e ligar o enforce vai derrubá-lo.
Token inválido não conta como leitura anônima¶
Uma sutileza que parece detalhe e não é. No modo warn, quando chega uma
requisição com Authorization que não resolve — token expirado, audiência
errada — ela é contabilizada como falha de autenticação, não como leitura
anônima.
Se as duas coisas fossem contadas juntas, uma frota com token momentaneamente expirado manteria o contador de anônimos acima de zero para sempre, e o portão nunca poderia ser promovido. O sinal que decide a promoção ficaria corrompido pelo ruído.
USER_EDITABLE_ENFORCEMENT¶
O mesmo padrão de virada em duas etapas, aplicado à autorização de escrita.
legacy(default)- O diff é calculado contra o payload inteiro, com os defaults do schema
preenchidos. Consequência: um usuário comum recebe
403mesmo editando um parâmetrouser_editable, porque os defaults entram no diff como se fossem alteração deliberada. explicit- O diff considera só os campos que o cliente enviou de fato, e preserva os metadados já gravados. É o comportamento que se quer.
A promoção depende da adoção do cliente 0.5.0 ou superior, que passou a omitir
user_editable do payload quando o chamador não informa. O 0.4.2 envia
user_editable=False explicitamente — sob explicit, isso vira tentativa de
alterar metadado e volta a dar 403.
Rotas de autenticação¶
| Rota | Corpo | Devolve |
|---|---|---|
POST /auth/token |
username e password como form |
O token do Keycloak |
POST /auth/refresh |
refresh_token como form |
Token renovado |
GET /auth/userinfo |
— (token no header) | Dados do usuário autenticado |
Os dois primeiros usam application/x-www-form-urlencoded, não JSON.
O que está congelado no OpenAPI¶
tests/test_openapi_contrato.py congela o securitySchemes e o bloco security
de cada rota. É o que transforma "o schema publicado não mudou" de argumento em
verificação. Não apague esse teste ao mexer nas dependências de
autenticação — ele é a única barreira automatizada que existe nessa área.
Segredo que alcança o histórico¶
Apagar o arquivo não apaga o commit
Um client_secret do Keycloak, uma senha de banco ou um envelope cifrado
que entre num commit segue alcançável por quem tiver o repositório, mesmo
depois de o arquivo sumir da árvore de trabalho. O git log guarda o
conteúdo, não o estado final.
O que encerra a exposição é rotacionar o segredo na origem — no
Keycloak, no banco, onde quer que ele seja emitido. Reescrever o histórico
não substitui isso: num repositório já distribuído, filter-repo invalida
todos os clones e não recupera nada que já tenha sido lido.
É por isso que a varredura de segredo no pipeline roda sobre o histórico inteiro, e não sobre o diff do commit: o que já entrou precisa ser encontrado onde está.