Segurança e Autenticação

Segurança e Autenticação

O PgArachne depende inteiramente do sistema de permissões do PostgreSQL. Ele não reinventa Listas de Controle de Acesso (ACLs). O PgArachne suporta quatro métodos de autenticação. Os métodos 1–3 usam SET LOCAL ROLE para trocar de identidade; o método 4 (credenciais diretas) conecta-se diretamente como o usuário, portanto nenhuma troca de papel é necessária.

1. Login Interativo (JWT)

Os usuários se autenticam usando seu nome de usuário e senha reais do PostgreSQL via o método JSON-RPC get_jwt. Em caso de sucesso, recebem um JWT de curta duração. As requisições subsequentes transportam esse token no cabeçalho Authorization: Bearer <token>, e o PgArachne altera o papel ativo para esse usuário durante toda a duração da requisição.

2. Contas de Serviço (Tokens de API)

Para sistemas automatizados ou scripts, você pode usar chaves de API de longa duração.

• Os tokens são armazenados na tabela pgarachne.api_tokens.
• Cada token é mapeado para um usuário/papel de banco de dados específico.
• Envie o token através do cabeçalho Authorization: Bearer <token>.

A criação de tokens de API requer o papel pgarachne_admin. Use pgarachne.add_api_token(...) com um papel membro de pgarachne_admin.

3. Provedor de identidade externo (JWT de terceiros)

Se você autentica usuários fora do PgArachne (por exemplo, em um serviço de autenticação externo), pode emitir os JWTs nesse serviço e enviá-los diretamente ao PgArachne.

• Formato do cabeçalho: Authorization: Bearer <jwt>.
• Assinatura: apenas HMAC (HS256/HS384/HS512) com o mesmo JWT_SECRET configurado no PgArachne.
• Claims obrigatórios: db_role (string não vazia) e db_name (string que deve corresponder a /api/:database).
• Claim recomendado: exp (timestamp Unix) para expiração do token.

Exemplo mínimo de payload:

{
  "db_role": "demo_user",
  "db_name": "my_database",
  "exp": 1767225600
}

Importante: algoritmos JWT assimétricos (por exemplo, RS256/ES256) não são aceitos pela implementação atual do servidor.

4. Credenciais diretas do banco de dados (Basic Auth)

É possível enviar o nome de usuário e a senha do PostgreSQL diretamente via HTTP Basic Authentication, sem necessidade de token JWT ou token de API.

• Formato do cabeçalho: Authorization: Basic <base64(usuario:senha)>
• O PgArachne conecta-se ao PostgreSQL diretamente como esse usuário — nenhum SET LOCAL ROLE é executado.
• Não é necessário executar GRANT usuario TO pgarachne.
• Os pools de conexão são criados por usuário e têm tempo de vida de 5 minutos.

Exemplo com curl:

curl -u demo_user:senha \
  -X POST http://localhost:8080/db/meu_banco/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"api.hello_world","params":{},"id":1}'

Principais diferenças em relação aos métodos baseados em token:

• Não é necessário nenhum GRANT demo_user TO pgarachne — o PgArachne não troca de papel.
• A segurança em nível de linha (Row-Level Security) e as permissões via GRANT do PostgreSQL são aplicadas normalmente, pois a conexão é executada como o próprio usuário.
• Os pools de conexão são mantidos por usuário para maior eficiência, com um tempo de vida máximo de 5 minutos. Após uma alteração de senha, as conexões antigas expiram dentro dessa janela.
• Para que as chaves de idempotência funcionem com credenciais diretas, conceda ao usuário EXECUTE ON FUNCTION pgarachne.save_idempotency_key(text).

Comparação dos métodos de autenticação

-- Permitir que 'pgarachne' mude para 'demo_user'
GRANT demo_user TO pgarachne;

Veja também

• Configuração
• Códigos de Erro