Skip to content

Gerenciamento de Senhas

Configure o hash de senhas PBKDF2-SHA256, redefinições via CLI/API de administrador, fluxos de redefinição por token self-service e armazenamento de credenciais em SQLite ou PostgreSQL no Potato.

Novo na v2.4.0

O sistema de autenticação do Potato usa PBKDF2-SHA256 com 100.000 iterações e salts por usuário — a mesma abordagem recomendada pelo NIST para armazenamento seguro de senhas. Esta página aborda como as senhas são armazenadas, como redefini-las e como manter as credenciais entre reinicializações do servidor.

Implementação de segurança

As senhas são armazenadas no formato salt$hash:

  • Salt hexadecimal de 32 caracteres, único por usuário
  • Hash SHA-256 de 64 caracteres de salt + password
  • Comparação em tempo constante via hmac.compare_digest para evitar ataques de temporização

Senhas em texto simples existentes em arquivos user_config.jsonl são automaticamente re-hasheadas com salts únicos quando o Potato as carrega — nenhuma migração manual é necessária.

Configuração padrão

Por padrão, o Potato usa autenticação em memória. Os anotadores devem estar listados na configuração:

yaml
authentication:
  method: in_memory
  require_password: true
 
user_config:
  users:
    - username: "annotator1"
      password: "initial-password"   # will be hashed on first load
    - username: "annotator2"
      password: "initial-password"

Credenciais persistentes

As credenciais em memória são perdidas na reinicialização. Para armazenamento persistente, use um backend de arquivo ou banco de dados.

Persistência baseada em arquivo

yaml
authentication:
  method: in_memory
  user_config_path: /shared/path/to/user_config.jsonl

O Potato grava as credenciais hasheadas neste arquivo. Na reinicialização, ele as lê de volta — senhas definidas ou alteradas durante uma sessão persistem entre reinicializações.

Backend de banco de dados

SQLite (sem dependências adicionais):

yaml
authentication:
  method: database
  database_url: "sqlite:///auth/users.db"

PostgreSQL (requer psycopg2-binary):

yaml
authentication:
  method: database
  database_url: "postgresql://user:password@localhost:5432/potato_auth"

As tabelas do banco de dados são criadas automaticamente na primeira inicialização.

Nota: method: database e user_config_path são mutuamente exclusivos — escolha uma estratégia de persistência.

Redefinindo senhas

CLI de administrador

Redefina uma senha pela linha de comando:

bash
# Reset a specific user's password
potato reset-password config.yaml --username annotator1
 
# Prompted for new password interactively

API de administrador

Redefina programaticamente com uma chave de API:

bash
curl -X POST http://localhost:8000/admin/reset_password \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "annotator1", "new_password": "new-secure-password"}'

Redefinição self-service por token

O Potato oferece um fluxo de redefinição iniciado pelo usuário. Os usuários acessam /forgot-password, informam seu nome de usuário e recebem um token de redefinição de uso único. Eles acessam /reset/<token> para definir uma nova senha.

Os tokens são válidos por 24 horas e só podem ser usados uma vez. O Potato não envia e-mails — o administrador distribui o link de redefinição manualmente.

Habilitar na configuração:

yaml
authentication:
  method: database
  database_url: "sqlite:///auth/users.db"
  allow_password_reset: true
  reset_token_ttl_hours: 24

Fluxo de trabalho do administrador:

bash
# Generate a reset token for a user
curl -X POST http://localhost:8000/admin/generate_reset_token \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -d '{"username": "annotator1"}'
 
# Returns: {"reset_url": "https://your-server.com/reset/abc123..."}
# Share this URL with the annotator

Modo sem senha

Para demonstrações em sala de aula, estudos rápidos ou tarefas que usam autenticação externa (MTurk, Prolific), você pode desabilitar as senhas por completo:

yaml
authentication:
  method: in_memory
  require_password: false

Os anotadores informam qualquer nome de usuário para entrar — nenhuma solicitação de senha aparece. Não recomendado para dados sensíveis ou tarefas que exijam identidade verificada.

Consulte Login sem Senha para mais detalhes.

Referência completa

yaml
authentication:
  method: in_memory       # in_memory | database | oauth | clerk
 
  # In-memory options
  require_password: true
  user_config_path: path/to/users.jsonl   # optional persistence
 
  # Database options (mutually exclusive with user_config_path)
  database_url: "sqlite:///auth/users.db"
 
  # Self-service reset
  allow_password_reset: true
  reset_token_ttl_hours: 24
 
user_config:
  users:
    - username: "researcher"
      password: "secure-passphrase"
      role: admin
    - username: "annotator1"
      password: "initial-pass"
      role: annotator

Leitura adicional

Para detalhes de implementação, consulte a documentação de origem.