Overview do domínio · Identidade e acesso
Identidade, conta e acesso
Uma Pessoa representa o titular no cadastro institucional. O papel USER permite associar uma conta de acesso à Pessoa; esse papel não determina, por si só, quais operações ela pode executar. A conta local da API vincula a Pessoa ao e-mail, ao Perfil de Acesso e aos vínculos usados na autorização. A identidade Appwrite fornece a sessão do front.
A API é responsável pelas decisões de acesso aos seus recursos. O front usa os dados da conta para apresentar a interface, enquanto a API valida cada operação protegida.
Cadastro de um novo usuário
O cadastro começa na página /pessoas/nova:
- O operador registra uma Pessoa física com papel
USERe informa e-mail, senha inicial e Perfil de Acesso no bloco de conta. - O front envia Pessoa e conta em
POST /v1/people. A API valida a natureza da Pessoa, o papel, o direito do operador de conceder o perfil, a disponibilidade do e-mail e a integração necessária para provisionar a identidade. - A API cria a Pessoa e a conta local vinculada, com
appwriteSubjectigual ao ID local epasswordHashnulo. Em seguida, provisiona a identidade no Appwrite, que guarda a senha. O cadastro é concluído quando as duas partes são confirmadas. - Se o provisionamento externo falhar, a API desfaz a transação local. Se a confirmação local falhar após o provisionamento, a API tenta excluir a identidade externa.
O cadastro conjunto também aceita uma Pessoa com papel ASSOCIATE. POST /v1/users atende à criação administrativa de uma conta local para uma Pessoa já cadastrada; essa operação não executa o mesmo provisionamento externo.
Estratégias de autenticação
| Estratégia | Entrada | Identificação na API |
|---|---|---|
| Appwrite | O front cria uma sessão com e-mail e senha no Appwrite e obtém um JWT vinculado a ela. | A API valida o JWT com o Appwrite e associa a identidade a uma conta local ativa, prioritariamente pelo appwriteSubject. Para contas legadas sem esse vínculo, pode usar o e-mail temporariamente; a reconciliação do vínculo ocorrerá por manifesto operacional. |
| Autenticação própria | POST /v1/auth/login valida a senha de contas locais e emite um JWT da API. Contas Appwrite não usam esse login. | A API valida assinatura e expiração e carrega a conta local ativa indicada por sub. |
| Token de sistema | Um usuário autorizado emite uma credencial para uma integração. | A API valida o segredo, seu prazo, seu estado e o sistema associado. O token representa a integração, não uma Pessoa na interface. |
No fluxo do front, o servidor cria a sessão Appwrite e chama GET /v1/users/me com o JWT. A sessão da aplicação só é estabelecida quando a API reconhece uma conta ativa. Recuperação e troca de senha da interface usam o Appwrite. A autenticação própria atende somente contas locais distintas. Contas Appwrite não entram por POST /v1/auth/login nem alteram a senha por PATCH /v1/users/me/password. Contas vinculadas ao Appwrite não mantêm hash de senha local. A validação de JWT Appwrite requer APPWRITE_ENABLED e APPWRITE_AUTH_ENABLED habilitados no ambiente da API.
Autorização e ACLs
A API aplica a autorização em três etapas:
- Autenticação: identifica a conta local ou a integração; operações públicas dispensam credencial.
- Perfil da operação: compara o Perfil de Acesso da conta com o mínimo exigido pela rota.
- Alcance e recurso: verifica os vínculos da Pessoa e as condições do recurso solicitado. O alcance pode considerar estrutura organizacional, núcleos, associações e carteiras, conforme a operação.
As ACLs dos recursos servidos pela API são centralizadas na própria API. A integração Appwrite autentica e provisiona identidades; a API não usa $permissions ou Role do Appwrite para substituir suas decisões de acesso. Uma credencial ausente ou inválida resulta em 401; uma conta autenticada sem permissão para a operação resulta em 403.