> ## 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

> O serviço Auth emite tokens OAuth2/OIDC, valida sessões, verifica permissões e trata desafios de MFA durante a entrada do usuário.

O Auth é o serviço de acesso em tempo de execução do Access Manager. Ele fica entre os seus produtos Lerian protegidos e o provedor de identidade configurado. Ele dá aos produtos uma interface única para o ciclo de vida do token, informações do usuário, verificações de permissão, logout e verificação de login com MFA.

Use o Auth quando você precisar:

* pedir access tokens para usuários humanos ou applications máquina a máquina.
* renovar um access token expirado.
* obter informações de usuário compatíveis com OIDC.
* validar se um subject pode executar uma ação em um recurso.
* obter as permissões disponíveis para o usuário autenticado.
* encerrar uma sessão de usuário.
* iniciar e verificar desafios de MFA durante o login.
* fazer o login de pessoas com uma passkey.

O Auth delega os dados de identidade ao provedor de identidade e guarda em cache no Valkey os dados de token, de permissão e relacionados a MFA, para reduzir chamadas repetidas durante a operação normal.

## Fluxos principais

***

O Auth aceita os fluxos de acesso usados pelos produtos e integrações Lerian.

![Fluxo conceitual de autenticação e autorização pelo plugin Auth, incluindo a emissão de token e as verificações de permissão](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/am-auth-flow.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=849fd0fdf01583add1c04508d8c1c03b)

Figura 1. Fluxo de autenticação e autorização

### Fluxo de autenticação

1. **Pedido de token**
   * Usuários humanos se autenticam com o grant `password` ou com uma [passkey](https://docs.lerian.studio/pt/platform/access-manager/features/passkeys/overview.md).
   * Integrações de serviço se autenticam com o grant `client_credentials`.
   * O Auth encaminha o pedido ao provedor de identidade 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 provedor de identidade antes de emitir o novo token.
3. **Validação de token**
   * Os produtos protegidos validam os bearer tokens antes de aceitar uma requisição.
   * O Auth extrai as claims confiáveis do token para identificar o subject e o contexto de tenant.
   * O Auth pode guardar em cache os resultados da validação para reduzir chamadas repetidas ao provedor de identidade.

### Contexto de organização

Na Lerian Cloud, o Auth pega a organização do token. Em um deploy BYOC, ele usa a organização configurada. O produto que recebe uma requisição autorizada é dono do próprio isolamento de dados.

### Fluxo de SSO no navegador

1. **Início do fluxo**
   * O navegador inicia o SSO pelo Auth com um endereço de e-mail, um provedor elegível e um `code_challenge` PKCE S256. O Auth resolve o tenant no servidor a partir do endereço de e-mail e redireciona o navegador ao provedor de identidade upstream.
2. **Tratamento do callback**
   * O provedor de identidade redireciona o navegador para `PLUGIN_AUTH_SSO_CALLBACK_URL`. Essa URL de callback absoluta deve estar registrada na lista de URIs de redirecionamento permitidas da aplicação no provedor de identidade.
   * O Console envia o código de autorização do provedor, o state do Auth e o `codeVerifier` PKCE correspondente pelo grant `sso_code` do Auth. O Auth consome o fluxo uma única vez, repassa o código ao provedor de identidade e retorna o envelope de token.

Antes de emitir tokens, o Auth verifica se o e-mail devolvido pelo provedor de identidade resolve para o tenant que iniciou o fluxo. O Auth recusa o login se o e-mail estiver ausente ou resolver para outro tenant. A recusa usa a mesma falha genérica de SSO dos demais repasses recusados.

Configure o provedor OAuth e a política de SSO do tenant pelo [Identity](https://docs.lerian.studio/pt/platform/access-manager/identity-plugin.md). A URL de callback do Auth deve coincidir com a URI de redirecionamento permitida da aplicação.

### Fluxo de login com MFA

1. **Desafio necessário**
   * Quando o usuário tem a MFA habilitada, o Auth retorna um estado de desafio de MFA em vez de concluir o login na hora.
   * Quando o usuário não tem nenhum método de MFA e a organização exige um, o Auth responde `AUT-0019` com um token de MFA válido apenas para a adesão. O usuário configura e confirma o método, e o desafio continua com o mesmo token.
2. **Início da entrega do desafio**
   * Para MFA por e-mail, o cliente envia o token de MFA devolvido para pedir a entrega do desafio, e o Auth manda o código do desafio por e-mail.
   * Um aplicativo TOTP gera o código de acesso dele localmente, sem pedido de entrega.
3. **Verificação do desafio**
   * O cliente envia o token de MFA com um código de acesso ou um código de recuperação.
   * O Auth verifica o desafio e retorna os access tokens quando a verificação dá certo, a menos que o usuário ainda tenha um método exigido a cadastrar (`AUT-0019`).
4. **Controles de sessão**
   * Os desafios de MFA expiram depois do TTL configurado.
   * As tentativas que falham têm limite, para proteger a conta de adivinhações repetidas.

### Fluxo de autorização

1. **Aplicar o acesso**
   * Um produto protegido pergunta se o subject autenticado pode executar uma ação específica em um recurso específico.
   * O Auth avalia o pedido contra as permissões configuradas no Access Manager.
   * O Auth pode guardar em cache as decisões de autorização bem-sucedidas, por desempenho.
2. **Obter permissões**
   * Um cliente pode obter 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. **Pedido de perfil**
   * O cliente pede as informações de perfil do usuário com um bearer token.
   * O Auth retorna informações de usuário compatíveis com OIDC.

### Fluxo de logout

1. **Logout do usuário**
   * O cliente manda um pedido de logout com o hint de ID token.
   * O Auth invalida a sessão no provedor de identidade.

## Visão geral da API

***

O Auth expõe APIs para:

* pedir access tokens com `password` ou `client_credentials`.
* renovar access tokens.
* encerrar sessões de usuário.
* validar permissões de usuário.
* obter informações do usuário.
* obter permissões do usuário.
* iniciar, concluir e descobrir fluxos de SSO no navegador.
* iniciar um desafio de MFA.
* verificar um desafio de login com MFA.
* cadastrar um método de MFA exigido durante a entrada.
* começar e concluir um login com passkey.

O Auth expõe tanto pontos de entrada que carregam credenciais quanto operações protegidas. Siga os requisitos de segurança documentados para cada endpoint. Para detalhes técnicos sobre endpoints e uso, veja a documentação das [APIs do Auth](https://docs.lerian.studio/pt/reference/platform/access-manager/am-auth-apis.md).

## Decisões de permissão

***

Quando um produto protegido pergunta ao Auth se um subject pode executar uma ação em um recurso, o Auth resolve o subject (um usuário humano ou uma application 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, o Auth avalia as permissões embutidas nos dados de identidade deles, incluindo permissões diretas do usuário e os papéis aplicáveis. Para applications máquina a máquina, as permissões vêm do conjunto de permissões configurado da application. O Auth avalia os dados que o Identity gerencia e não inventa permissões.

Para o modelo completo de subject/recurso/ação, exemplos e como as rotas são protegidas, veja [Aplicação no nível do produto](https://docs.lerian.studio/pt/platform/access-manager/product-level-enforcement.md). Para inspecionar o que o subject autenticado alcança, use [Obter permissões do usuário](https://docs.lerian.studio/pt/reference/platform/access-manager/retrieve-user-permissions.md).

## 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** guardam as regras de controle de acesso de usuários, grupos e applications.
* **Cache de token** guarda os resultados de validação de token.
* **Cache de permissão** guarda as decisões de autorização bem-sucedidas.
* **Cache de permissões do usuário** guarda o mapa de recursos e ações disponíveis para um usuário.
* **Cache de MFA** guarda o estado temporário do desafio e da adesão e os contadores de tentativas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.