You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
164 lines
4.4 KiB
Markdown
164 lines
4.4 KiB
Markdown
# Estrategia De Credenciais Para StaffAccount
|
|
|
|
Este documento define a estrategia inicial de credenciais para contas administrativas internas (`StaffAccount`).
|
|
|
|
## Objetivo
|
|
|
|
Permitir autenticacao web no `orquestrador-admin` sem misturar a identidade do painel com o `User` do atendimento.
|
|
|
|
## O que e o StaffAccount
|
|
|
|
`StaffAccount` e a conta administrativa interna do sistema.
|
|
|
|
Ela representa um funcionario ou administrador da empresa e existe apenas no dominio administrativo.
|
|
Nao deve ser usada para identificar cliente do atendimento.
|
|
|
|
Responsabilidades principais do `StaffAccount`:
|
|
|
|
- autenticar acesso ao painel administrativo
|
|
- carregar papel de autorizacao (`colaborador`, `diretor`)
|
|
- auditar quem executou uma acao interna
|
|
- governar drafts, configuracoes, relatorios e publicacao de tools
|
|
|
|
## O que e a StaffSession
|
|
|
|
`StaffSession` representa uma sessao administrativa ativa derivada de um login do `StaffAccount`.
|
|
|
|
Cada sessao possui:
|
|
|
|
- `session_id`
|
|
- `refresh_token_hash`
|
|
- data de expiracao
|
|
- marcador de revogacao
|
|
- metadados simples de IP e user-agent
|
|
|
|
Isso permite tratar login, refresh e logout sem depender apenas de um access token solto.
|
|
|
|
## Identificador de login
|
|
|
|
O identificador principal de login sera:
|
|
|
|
- `email`
|
|
|
|
Regras:
|
|
|
|
- deve ser unico no banco administrativo
|
|
- deve ser normalizado em lowercase na camada de servico e repositorio
|
|
- nao sera compartilhado com a identidade do atendimento
|
|
|
|
## Segredo primario
|
|
|
|
O segredo primario inicial sera:
|
|
|
|
- senha gerenciada internamente
|
|
|
|
A senha nunca deve ser armazenada em texto puro.
|
|
|
|
## Estrategia de hash
|
|
|
|
A estrategia inicial definida para `password_hash` e:
|
|
|
|
- esquema: `pbkdf2_sha256`
|
|
- iteracoes padrao: `390000`
|
|
- salt aleatorio por conta
|
|
- pepper opcional via ambiente: `ADMIN_AUTH_PASSWORD_PEPPER`
|
|
|
|
Formato de persistencia adotado:
|
|
|
|
- `pbkdf2_sha256$<iterations>$<salt>$<digest>`
|
|
|
|
## Politica inicial de senha
|
|
|
|
Politica minima definida:
|
|
|
|
- tamanho minimo: `12`
|
|
- exigir letra maiuscula
|
|
- exigir letra minuscula
|
|
- exigir digito
|
|
- exigir simbolo
|
|
|
|
A validacao dessa politica ja esta refletida no runtime administrativo.
|
|
|
|
## Tokens e sessao
|
|
|
|
Estrategia inicial para a autenticacao web:
|
|
|
|
- access token curto: `30` minutos
|
|
- refresh token: `7` dias
|
|
- secret de assinatura dedicado: `ADMIN_AUTH_TOKEN_SECRET`
|
|
- issuer do admin runtime: `ADMIN_AUTH_TOKEN_ISSUER`
|
|
- tamanho configuravel do refresh token: `ADMIN_AUTH_REFRESH_TOKEN_BYTES`
|
|
|
|
Nesta etapa, o runtime administrativo ja faz:
|
|
|
|
- emissao de access token assinado por HMAC-SHA256
|
|
- emissao de refresh token opaco
|
|
- armazenamento hash do refresh token em `StaffSession`
|
|
- rotacao do refresh token no endpoint de refresh
|
|
- revogacao da sessao no logout
|
|
|
|
## Bootstrap do primeiro diretor
|
|
|
|
A primeira conta de diretor deve nascer por fluxo controlado, nunca por startup automatico.
|
|
|
|
Variaveis previstas:
|
|
|
|
- `ADMIN_BOOTSTRAP_ENABLED`
|
|
- `ADMIN_BOOTSTRAP_EMAIL`
|
|
- `ADMIN_BOOTSTRAP_DISPLAY_NAME`
|
|
- `ADMIN_BOOTSTRAP_PASSWORD`
|
|
- `ADMIN_BOOTSTRAP_ROLE`
|
|
|
|
Regras:
|
|
|
|
- o bootstrap deve ser executado por comando explicito no futuro
|
|
- nao deve criar conta automaticamente ao subir o servico
|
|
- o papel padrao do bootstrap e `diretor`
|
|
|
|
## Relacao com papeis e permissoes
|
|
|
|
A conta `StaffAccount` continua acoplada a hierarquia compartilhada:
|
|
|
|
- `colaborador`
|
|
- `diretor`
|
|
|
|
A senha autentica a identidade; o `role` governa autorizacao.
|
|
|
|
## Configuracoes adicionadas ao admin runtime
|
|
|
|
As configuracoes de credenciais passam a existir em `admin_app/core/settings.py`:
|
|
|
|
- `admin_auth_password_hash_scheme`
|
|
- `admin_auth_password_hash_iterations`
|
|
- `admin_auth_password_min_length`
|
|
- `admin_auth_password_require_uppercase`
|
|
- `admin_auth_password_require_lowercase`
|
|
- `admin_auth_password_require_digit`
|
|
- `admin_auth_password_require_symbol`
|
|
- `admin_auth_password_pepper`
|
|
- `admin_auth_token_secret`
|
|
- `admin_auth_token_issuer`
|
|
- `admin_auth_access_token_ttl_minutes`
|
|
- `admin_auth_refresh_token_ttl_days`
|
|
- `admin_auth_refresh_token_bytes`
|
|
- `admin_bootstrap_enabled`
|
|
- `admin_bootstrap_email`
|
|
- `admin_bootstrap_display_name`
|
|
- `admin_bootstrap_password`
|
|
- `admin_bootstrap_role`
|
|
|
|
## Endpoints iniciais de autenticacao
|
|
|
|
Nesta etapa, o `orquestrador-admin` passa a expor:
|
|
|
|
- `POST /auth/login`
|
|
- `POST /auth/refresh`
|
|
- `POST /auth/logout`
|
|
- `GET /auth/me`
|
|
|
|
## Proximos passos naturais
|
|
|
|
- implementar autorizacao por papel nas demais rotas administrativas
|
|
- implementar fluxo explicito de bootstrap do primeiro diretor
|
|
- implementar gestao de sessoes revogaveis por tela administrativa
|