> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Serviço Auth
> Emita tokens OAuth2/OIDC, valide sessões, verifique permissões e trate desafios de MFA com o serviço Auth.
Auth é o serviço de acesso em tempo de execução do Access Manager. Ele fica entre seus produtos Lerian protegidos e o identity provider configurado, dando aos produtos uma única interface para ciclo de vida de tokens, informações de usuário, verificações de permissão, logout e verificação de login com MFA.
Use o Auth quando precisar:
* solicitar access tokens para usuários humanos ou aplicações máquina-a-máquina;
* renovar um access token expirado;
* recuperar informações de usuário compatíveis com OIDC;
* validar se um subject pode executar uma ação sobre um recurso;
* recuperar as permissões disponíveis para o usuário autenticado;
* encerrar a sessão de um usuário;
* iniciar e verificar desafios de MFA durante o login.
O Auth delega os dados de identidade ao identity provider e faz cache de dados de token, permissão e MFA com o Valkey para reduzir chamadas repetidas durante a operação normal.
## Fluxos principais
***
O Auth suporta os fluxos de acesso usados pelos produtos e integrações Lerian.
### Fluxo de autenticação
1. **Requisição de token**
* Usuários humanos autenticam com o grant `password`.
* Integrações de serviço autenticam com o grant `client_credentials`.
* O Auth encaminha a requisição ao identity provider e retorna o access token, o refresh token e o ID token quando aplicável.
2. **Renovação de token**
* Os clientes trocam um refresh token por um novo access token.
* O Auth valida o refresh token com o identity provider antes de emitir o novo token.
3. **Validação de token**
* Os produtos protegidos validam bearer tokens antes de aceitar uma requisição.
* O Auth extrai claims confiáveis do token para identificar o subject e o contexto de tenant.
* Os resultados da validação podem ser armazenados em cache para reduzir chamadas repetidas ao identity provider.
**Contexto de tenant** — Em deployments SaaS e BYOC multi-tenant, o JWT emitido contém um claim `tenantId`. Esse claim é resolvido automaticamente pela plataforma em cada requisição de API — você não precisa passar um identificador de tenant em headers ou no corpo da requisição. Seu token define o seu escopo. Saiba mais sobre [multi-tenancy](/pt/multi-tenancy).
### Tratamento de token multi-tenant
Quando o multi-tenancy está habilitado, o Auth mantém as operações de token e permissão dentro do tenant resolvido para o subject autenticado.
Para usuários humanos, o grant password resolve o tenant do usuário antes de solicitar tokens ao identity provider configurado. Os fluxos de refresh token usam o contexto de tenant carregado pelo token existente, então uma renovação não consegue mover a sessão para outro tenant.
Para integrações máquina-a-máquina, o Auth resolve as credenciais da aplicação e o conjunto de permissões a partir da organização da aplicação. O token resultante fica restrito ao tenant dessa aplicação.
Em deployments single-tenant, o Auth usa a organização padrão configurada e não exige um claim de tenant.
### Passo a passo da resolução de tenant
Quando o multi-tenancy está habilitado, uma única requisição percorre sete passos, da chamada do cliente até a resposta isolada. Cada passo restringe o escopo ao tenant chamador e se recusa a prosseguir se o contexto de tenant não puder ser estabelecido.
Um cliente chama uma API de produto protegida com um bearer token. O cliente nunca envia um identificador de tenant em headers ou no corpo — o token é a única fonte do contexto de tenant.
O produto valida o bearer token antes de aceitar a requisição. O Auth verifica o token com o identity provider (ou um resultado de validação em cache) e rejeita qualquer coisa expirada, malformada ou não assinada.
O Auth extrai as claims confiáveis do token validado, incluindo a claim `tenantId` que identifica o tenant do chamador. Essa claim é definida na emissão e não pode ser sobrescrita pela requisição.
O middleware multi-tenant do produto lê o `tenantId` das claims validadas e estabelece o contexto de tenant para o ciclo de vida da requisição.
O middleware resolve o tenant para a sua configuração de serviço através da camada de plataforma (usando o cache local quando válido), obtendo os detalhes de conexão para a infraestrutura isolada daquele tenant.
O produto abre — ou reutiliza do pool por tenant — uma conexão restrita exatamente ao banco de dados ou schema daquele tenant. Os dados de nenhum outro tenant são alcançáveis através dessa conexão.
A operação é executada contra os dados isolados e a resposta é retornada ao chamador, inteiramente restrita ao tenant resolvido.
#### Contexto de tenant fail-closed
A resolução de tenant é **fail-closed**: se o contexto de tenant não puder ser estabelecido, a requisição é rejeitada em vez de ser atendida contra um escopo padrão ou compartilhado. Uma requisição é negada quando o token é inválido ou não contém a claim `tenantId`, quando o tenant não pode ser resolvido para uma configuração de serviço, ou quando o serviço de multi-tenancy está inacessível e não existe uma configuração válida em cache (veja o [circuit breaker](/pt/multi-tenancy#circuit-breaker)). A plataforma nunca recorre aos dados de outro tenant nem a uma conexão sem escopo quando a resolução falha.
O comportamento fail-closed significa que uma falha na resolução de tenant se manifesta como uma requisição negada, e não como um acesso ampliado silenciosamente. Isso é intencional — garante que nenhuma operação seja executada sem um escopo de tenant confirmado.
### Fluxo de login com MFA
1. **Desafio necessário**
* Quando o MFA é exigido, o Auth retorna um estado de desafio de MFA em vez de concluir o login imediatamente.
* O usuário recebe um código de desafio pelo método configurado.
2. **Verificação do desafio**
* O usuário envia o token de MFA e o passcode.
* O Auth verifica o desafio e retorna os access tokens quando a verificação tem sucesso.
3. **Controles de sessão**
* Os desafios de MFA expiram após o TTL configurado.
* As tentativas falhas são limitadas para proteger a conta contra tentativas repetidas de adivinhação.
### Fluxo de autorização
1. **Aplicar acesso**
* Um produto protegido pergunta se o subject autenticado pode executar uma ação específica sobre um recurso específico.
* O Auth avalia a requisição contra as permissões configuradas no Access Manager.
* Decisões de autorização bem-sucedidas podem ser armazenadas em cache para performance.
2. **Recuperar permissões**
* Um cliente pode recuperar as permissões disponíveis para o usuário autenticado.
* O Auth retorna as permissões como um mapa de recursos para ações permitidas.
### Fluxo de informações do usuário
1. **Requisição de perfil**
* O cliente solicita informações de perfil do usuário com um bearer token.
* O Auth valida o token e recupera os detalhes do usuário no identity provider.
* O Auth retorna informações de usuário compatíveis com OIDC.
### Fluxo de logout
1. **Logout do usuário**
* O cliente envia uma requisição de logout com o ID token hint.
* O Auth invalida a sessão no identity provider.
* As entradas de cache relacionadas são limpas.
## Visão geral da API
***
O Auth expõe APIs para:
* solicitar access tokens com `password` ou `client_credentials`;
* renovar access tokens;
* encerrar sessões de usuário;
* validar permissões de usuário;
* recuperar informações de usuário;
* recuperar permissões de usuário;
* iniciar um desafio de MFA;
* verificar um desafio de login com MFA.
O acesso às APIs do Auth é protegido por controles rígidos de permissão. Para detalhes técnicos sobre endpoints e uso, consulte a documentação das [APIs do Auth](/pt/reference/access-manager/am-auth-apis).
## Decisões de permissão
***
Quando um produto protegido pergunta ao Auth se um subject pode executar uma ação sobre um recurso, o Auth resolve o subject (um usuário humano ou uma aplicação máquina-a-máquina), busca as permissões associadas a ele e retorna uma decisão de autorizado ou negado.
Para usuários humanos, as permissões vêm dos grupos atribuídos no Identity. Para aplicações máquina-a-máquina, as permissões vêm do conjunto de permissões configurado da aplicação. O Auth não inventa permissões; ele avalia os dados que o Identity gerencia.
Para o modelo completo de subject/recurso/ação, exemplos e como as rotas são protegidas, consulte [Aplicação em nível de produto](/pt/platform/access-manager/product-level-enforcement). Para inspecionar o que o subject autenticado consegue alcançar, use [Recuperar Permissões de Usuário](/pt/reference/access-manager/retrieve-user-permissions).
## Armazenamento de dados e cache
***
O Auth usa dados de política estruturados e entradas de cache para reduzir trabalho repetido:
* **Dados de política** armazenam as regras de controle de acesso para usuários, grupos e aplicações.
* **Cache de token** armazena os resultados de validação de token.
* **Cache de permissões** armazena decisões de autorização bem-sucedidas.
* **Cache de permissões do usuário** armazena o mapa de recursos e ações disponíveis para um usuário.
* **Cache de MFA** armazena o estado temporário de desafios, contadores de tentativas e o estado de remember-device quando configurado.
## Testes e confiabilidade
***
O **Auth** passa por testes contínuos para manter confiabilidade e segurança. Os testes cobrem:
* **Fluxos de autenticação e validação de token**.
* **Aplicação de controle de acesso**.
* **Performance e eficiência de cache**.
O Auth também executa avaliações de segurança e monitoramento contínuos nesses fluxos.