DOCS: Adicionado documentação sobre controle de acesso
All checks were successful
Deploy Dev / deploy (push) Successful in 3s
All checks were successful
Deploy Dev / deploy (push) Successful in 3s
This commit is contained in:
parent
da737b62fc
commit
312f330bdf
351
docs/access-control.md
Normal file
351
docs/access-control.md
Normal file
@ -0,0 +1,351 @@
|
||||
# Controle de Acesso, Areas e Usuarios
|
||||
|
||||
## Visao geral
|
||||
|
||||
O backend agora usa o banco PostgreSQL para manter o usuario interno da aplicacao e suas atribuicoes operacionais.
|
||||
|
||||
A autenticacao continua sendo feita por provedores externos:
|
||||
|
||||
- LDAP / Active Directory
|
||||
- Microsoft OAuth
|
||||
|
||||
Depois que o provedor confirma a identidade, o backend sincroniza esse usuario no banco e consulta:
|
||||
|
||||
- perfis de acesso
|
||||
- areas vinculadas
|
||||
- area principal
|
||||
- status de acesso
|
||||
|
||||
Esse status determina qual experiencia o frontend deve renderizar em `/home`.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo de login com banco
|
||||
|
||||
```text
|
||||
Frontend
|
||||
-> POST /auth/login ou OAuth Microsoft
|
||||
-> Backend autentica no provedor externo
|
||||
-> Backend cria/atualiza usuarios
|
||||
-> Backend cria/atualiza usuarios_provedores
|
||||
-> Backend consulta usuarios_perfis e usuarios_areas
|
||||
-> Backend emite JWT com perfis/areas
|
||||
-> Frontend salva authToken/authUser
|
||||
-> Frontend navega para /home
|
||||
```
|
||||
|
||||
O provedor externo valida identidade. O banco define acesso dentro do Omnichannel.
|
||||
|
||||
---
|
||||
|
||||
## Tabelas usadas
|
||||
|
||||
### `usuarios`
|
||||
|
||||
Representa uma pessoa autenticada no produto.
|
||||
|
||||
Campos principais:
|
||||
|
||||
- `id`
|
||||
- `nome`
|
||||
- `email`
|
||||
- `ativo`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
|
||||
### `usuarios_provedores`
|
||||
|
||||
Relaciona o usuario interno com o provedor externo usado no login.
|
||||
|
||||
Exemplos:
|
||||
|
||||
- `ldap` + username do AD
|
||||
- `microsoft` + userPrincipalName/email
|
||||
|
||||
### `perfis_acesso`
|
||||
|
||||
Define os niveis de acesso.
|
||||
|
||||
Perfis iniciais:
|
||||
|
||||
- `Agente`
|
||||
- `Supervisor`
|
||||
- `Admin`
|
||||
|
||||
### `usuarios_perfis`
|
||||
|
||||
Relaciona usuarios e perfis.
|
||||
|
||||
Hoje o frontend usa o perfil principal para decidir a experiencia em `/home`.
|
||||
|
||||
### `areas`
|
||||
|
||||
Representa as areas operacionais.
|
||||
|
||||
Areas iniciais:
|
||||
|
||||
- `Suporte`
|
||||
- `Financeiro`
|
||||
- `Comercial`
|
||||
|
||||
### `usuarios_areas`
|
||||
|
||||
Relaciona usuarios e areas.
|
||||
|
||||
Um usuario pode ter mais de uma area, mas a regra atual permite no maximo uma area principal por usuario.
|
||||
|
||||
---
|
||||
|
||||
## Status de acesso
|
||||
|
||||
O backend devolve `accessStatus` no usuario autenticado.
|
||||
|
||||
Valores:
|
||||
|
||||
- `assigned`: usuario tem pelo menos um perfil e uma area
|
||||
- `unassigned`: usuario existe/autenticou, mas ainda nao tem perfil ou area
|
||||
|
||||
### Comportamento no frontend
|
||||
|
||||
```text
|
||||
assigned + Admin -> /home renderiza painel Admin
|
||||
assigned + Supervisor -> /home renderiza painel Supervisor
|
||||
assigned + Agente -> /home renderiza tela do Atendente
|
||||
unassigned -> /home renderiza tela de acesso aguardando configuracao
|
||||
```
|
||||
|
||||
Esse comportamento permite que um usuario novo entre via AD/OAuth, seja criado no banco e fique bloqueado ate um Admin atribuir perfil e area.
|
||||
|
||||
---
|
||||
|
||||
## Payload do usuario autenticado
|
||||
|
||||
Exemplo de resposta do login:
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "jwt",
|
||||
"user": {
|
||||
"id": "1",
|
||||
"databaseId": 1,
|
||||
"name": "Atendente Demo",
|
||||
"email": "atendente@sothis.com.br",
|
||||
"username": "atendente",
|
||||
"provider": "ldap",
|
||||
"perfis": ["Agente"],
|
||||
"profiles": ["Agente"],
|
||||
"areas": ["Suporte"],
|
||||
"areaPrincipal": "Suporte",
|
||||
"accessStatus": "assigned"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
No JWT tambem entram:
|
||||
|
||||
- `name`
|
||||
- `email`
|
||||
- `provider`
|
||||
- `username`
|
||||
- `perfis`
|
||||
- `profiles`
|
||||
- `areas`
|
||||
- `areaPrincipal`
|
||||
- `accessStatus`
|
||||
|
||||
---
|
||||
|
||||
## Variaveis de ambiente
|
||||
|
||||
O backend le as variaveis de banco pelo `.env.development` em desenvolvimento.
|
||||
|
||||
```env
|
||||
DB_HOST=10.0.120.75
|
||||
DB_PORT=5432
|
||||
DB_USER=desenvolvimento
|
||||
DB_PASSWORD=********
|
||||
DB_NAME=omnichannel-dev
|
||||
```
|
||||
|
||||
Observacao:
|
||||
|
||||
- `npm run dev` usa `NODE_ENV=development` e carrega `.env.development`.
|
||||
- `npm run start` usa `NODE_ENV=production`; nesse caso, configure `.env.production` ou variaveis do ambiente.
|
||||
|
||||
---
|
||||
|
||||
## Endpoints administrativos
|
||||
|
||||
Base path:
|
||||
|
||||
```text
|
||||
/admin/access
|
||||
```
|
||||
|
||||
### Listar opcoes de acesso
|
||||
|
||||
```http
|
||||
GET /admin/access/options
|
||||
```
|
||||
|
||||
Resposta:
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": [
|
||||
{ "id": 3, "nome": "Admin" },
|
||||
{ "id": 1, "nome": "Agente" },
|
||||
{ "id": 2, "nome": "Supervisor" }
|
||||
],
|
||||
"areas": [
|
||||
{ "id": 3, "nome": "Comercial" },
|
||||
{ "id": 2, "nome": "Financeiro" },
|
||||
{ "id": 1, "nome": "Suporte" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Listar usuarios
|
||||
|
||||
```http
|
||||
GET /admin/access/users
|
||||
```
|
||||
|
||||
Resposta:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"nome": "Admin Demo",
|
||||
"email": "admin@sothis.com.br",
|
||||
"ativo": true,
|
||||
"perfis": [{ "id": 3, "nome": "Admin" }],
|
||||
"areas": [{ "id": 1, "nome": "Suporte", "principal": true }],
|
||||
"perfilPrincipal": { "id": 3, "nome": "Admin" },
|
||||
"areaPrincipal": { "id": 1, "nome": "Suporte", "principal": true },
|
||||
"accessStatus": "assigned"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Atualizar acesso de usuario
|
||||
|
||||
```http
|
||||
PUT /admin/access/users/:id
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Body:
|
||||
|
||||
```json
|
||||
{
|
||||
"perfilId": 2,
|
||||
"areaId": 1
|
||||
}
|
||||
```
|
||||
|
||||
Comportamento atual:
|
||||
|
||||
- remove perfis anteriores do usuario
|
||||
- remove areas anteriores do usuario
|
||||
- cria o novo perfil informado
|
||||
- cria a nova area como principal
|
||||
- retorna o usuario atualizado
|
||||
|
||||
Para remover atribuicoes:
|
||||
|
||||
```json
|
||||
{
|
||||
"perfilId": null,
|
||||
"areaId": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usuarios de demonstracao
|
||||
|
||||
A migration `003_demo_access.sql` cria usuarios iniciais para demonstracao:
|
||||
|
||||
| Usuario | Email | Perfil | Area |
|
||||
|---|---|---|---|
|
||||
| Admin Demo | `admin@sothis.com.br` | Admin | Suporte |
|
||||
| Supervisor Demo | `supervisor@sothis.com.br` | Supervisor | Suporte |
|
||||
| Atendente Demo | `atendente@sothis.com.br` | Agente | Suporte |
|
||||
|
||||
Esses usuarios existem no banco, mas nao substituem a autenticacao real.
|
||||
|
||||
Para logar pela tela de login, o usuario precisa existir no AD ou no provedor Microsoft configurado.
|
||||
|
||||
---
|
||||
|
||||
## Como testar
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Endpoints de validacao:
|
||||
|
||||
```text
|
||||
http://localhost:3001/admin/access/options
|
||||
http://localhost:3001/admin/access/users
|
||||
```
|
||||
|
||||
### Frontend sem depender de AD
|
||||
|
||||
No console do navegador:
|
||||
|
||||
```js
|
||||
localStorage.setItem('authUser', JSON.stringify({
|
||||
username: 'admin@sothis.com.br',
|
||||
name: 'Admin Demo',
|
||||
email: 'admin@sothis.com.br',
|
||||
perfis: ['Admin'],
|
||||
profiles: ['Admin'],
|
||||
areas: ['Suporte'],
|
||||
accessStatus: 'assigned'
|
||||
}));
|
||||
localStorage.setItem('authToken', 'dev-token');
|
||||
location.href = '/home';
|
||||
```
|
||||
|
||||
Para usuario sem atribuicao:
|
||||
|
||||
```js
|
||||
localStorage.setItem('authUser', JSON.stringify({
|
||||
username: 'novo.usuario',
|
||||
name: 'Novo Usuario',
|
||||
email: 'novo.usuario@sothis.com.br',
|
||||
perfis: [],
|
||||
profiles: [],
|
||||
areas: [],
|
||||
accessStatus: 'unassigned'
|
||||
}));
|
||||
localStorage.setItem('authToken', 'dev-token');
|
||||
location.href = '/home';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Limitacoes atuais
|
||||
|
||||
- Os endpoints `/admin/access/*` ainda nao possuem guard JWT nem checagem de perfil Admin.
|
||||
- A alteracao de acesso substitui perfil/area atuais por um unico perfil e uma unica area principal.
|
||||
- Ainda nao ha auditoria das alteracoes de acesso.
|
||||
- O painel Admin consome os endpoints reais, mas ainda possui fallback visual mockado se o backend estiver indisponivel.
|
||||
- A senha do banco nao deve ser commitada; arquivos `.env.*` seguem ignorados pelo Git.
|
||||
|
||||
---
|
||||
|
||||
## Proximos passos sugeridos
|
||||
|
||||
- Adicionar `AuthGuard` JWT.
|
||||
- Proteger `/admin/access/*` para `Admin`.
|
||||
- Registrar auditoria em `logs_auditoria`.
|
||||
- Criar endpoints CRUD completos para `areas`.
|
||||
- Permitir multiplas areas por usuario na UI, mantendo uma area principal.
|
||||
10
docs/auth.md
10
docs/auth.md
@ -257,4 +257,12 @@ loginComNovoProvedor(dados: any) {
|
||||
- [ ] Guard NestJS para proteger rotas privadas (`@UseGuards(AuthGuard)`)
|
||||
- [ ] Roles e permissões
|
||||
- [ ] Auditoria de login
|
||||
- [ ] Trocar token na query string por cookie HTTP-only (reduz exposição no browser)
|
||||
- [ ] Trocar token na query string por cookie HTTP-only (reduz exposição no browser)
|
||||
|
||||
---
|
||||
|
||||
## Documentacao complementar
|
||||
|
||||
A sincronizacao de usuarios autenticados com o banco, os perfis de acesso, as areas operacionais e os endpoints administrativos estao documentados em:
|
||||
|
||||
- [`access-control.md`](./access-control.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user