Ory Hydra Self-Hosted: Implementando OAuth2 em Produção

Ory Hydra Self-Hosted: OAuth2 Provider em Produção

A gestão de identidades é um dos pilares fundamentais da segurança moderna. Em vez de armazenar senhas e gerenciar sessões manualmente para cada aplicação, a abordagem recomendada é delegar essa responsabilidade a um provedor de identidade dedicado. O Ory Hydra surge como a solução robusta para quem precisa implementar fluxos OAuth 2.0 e OpenID Connect (OIDC) em infraestrutura própria, seja em VPSs, containers Docker ou orquestradores Kubernetes.

Diferente de soluções "caixa preta", o Hydra é construído com foco em conformidade total com os padrões da indústria, transparência e extensibilidade. Neste tutorial técnico, vamos guiar você através do processo de instalação e configuração de um Ory Hydra self-hosted em um ambiente Linux Ubuntu/Debian, preparado para produção.

1. Arquitetura e Requisitos do Sistema

Antes de iniciar a instalação, é crucial entender a arquitetura proposta pelo Ory. O Hydra não armazena dados de usuários (como senhas ou perfis) diretamente. Ele atua como o provedor de autorização (Authorization Server). Para isso, ele depende de um banco de dados relacional para armazenar tokens, sessões e metadados de clientes.

Requisitos mínimos recomendados:

• Sistema Operacional: Linux Ubuntu 20.04 LTS ou superior (Debian 11+).
• Processador: 1 CPU Core (2.0 GHz+).
• Memória RAM: 512 MB a 1 GB (para ambientes de teste/pequeno porte).
• Disco: 10 GB SSD mínimo.
• Banco de Dados: PostgreSQL 12+ ou MySQL/MariaDB 8+.

Para este tutorial, utilizaremos o PostgreSQL, pois é o banco de dados preferencial pela comunidade Ory devido à sua robustez e suporte nativo a JSONB, que facilita a expansão futura.

2. Preparação do Ambiente Linux

O primeiro passo é garantir que seu servidor esteja atualizado e com as dependências básicas instaladas. Conecte-se ao seu VPS via SSH e execute os comandos abaixo para instalar o PostgreSQL e utilitários de linha de comando necessários.

sudo apt update
sudo apt upgrade -y
sudo apt install postgresql postgresql-client curl wget jq -y

Agora, vamos configurar o banco de dados. É altamente recomendável criar um usuário dedicado e um banco de dados exclusivo para o Hydra, seguindo o princípio do menor privilégio.

sudo -u postgres psql

Dentro do shell do PostgreSQL, execute as seguintes queries:

CREATE DATABASE hydra_db;
CREATE USER hydra_user WITH ENCRYPTED PASSWORD 'SENHA_FORTE_AQUI';
GRANT ALL PRIVILEGES ON DATABASE hydra_db TO hydra_user;

Após criar o usuário e conceder permissões, saia do shell digitando \q. Verifique se a conexão está funcionando:

psql -U hydra_user -d hydra_db -h 127.0.0.1

Se a conexão for estabelecida sem erros, o banco de dados está pronto.

3. Instalação do Ory Hydra

O Ory Hydra pode ser baixado diretamente dos releases oficiais ou compilado a partir do código-fonte. Para produção, recomendamos baixar o binário pré-compilado mais recente da página oficial do projeto no GitHub.

# Verifique a última versão em https://github.com/ory/hydra/releases
HYDRA_VERSION="v2.2.0"
cd /tmp
wget https://github.com/ory/hydra/releases/download/${HYDRA_VERSION}/hydra_${HYDRA_VERSION}_linux-amd64.tar.gz
tar -xzf hydra_${HYDRA_VERSION}_linux-amd64.tar.gz

Mova o binário para um diretório no seu PATH e defina as permissões adequadas:

sudo mv hydra /usr/local/bin/hydra
sudo chmod +x /usr/local/bin/hydra

Verifique a instalação:

hydra --version

Você deve ver o número da versão instalado. Agora, precisamos configurar o Hydra para se conectar ao PostgreSQL que criamos.

4. Configuração do Ambiente e Migração de Banco de Dados

O Hydra utiliza variáveis de ambiente para configuração. Crie um arquivo .env na raiz do seu projeto ou defina as variáveis no shell. Para produção, utilize um gerenciador de segredos ou um arquivo .env protegido com permissões restritas (chmod 600 .env).

# Configuração Básica
DSN=postgres://hydra_user:SENHA_FORTE_AQUI@127.0.0.1:5432/hydra_db?sslmode=disable
LOG_LEVEL=info
OVERRIDE_URLS=https://seu-dominio.com

# Chaves de Segurança (Geradas automaticamente na primeira execução se não fornecidas)
# É crítico manter essas chaves seguras!
SK_OAUTH2_SIGNING=a7f8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7
SK_COOKIE=8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8

Com as variáveis definidas, execute a migração do banco de dados para criar as tabelas necessárias:

hydra migrate sql postgres://hydra_user:SENHA_FORTE_AQUI@127.0.0.1:5432/hydra_db?sslmode=disable

Este comando criará todas as tabelas de esquema necessárias. Se você estiver usando uma versão diferente do banco de dados ou quiser verificar o status das migrações, use hydra migrate status.

5. Geração de Chaves e Configuração de TLS

O Hydra requer chaves criptográficas para assinar tokens JWT e cookies de sessão. Na primeira inicialização, ele pode gerar essas chaves automaticamente, mas em produção, você deve gerenciá-las explicitamente.

# Gerar novas chaves se necessário
hydra keys create all --force

Nota de Segurança Crítica: O Hydra exige HTTPS/TLS para operar em produção. Não tente expor o Hydra diretamente na porta 443 sem um proxy reverso ou certificação TLS válida, pois os fluxos OAuth falharão se o esquema não for https.

Para fins de teste local ou desenvolvimento, você pode gerar certificados auto-assinados:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout hydra.key -out hydra.crt \
  -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

Para produção, utilize certificados emitidos por uma Autoridade Certificadora confiável (Let's Encrypt, Digicert, etc.) e aponte para os arquivos .crt e .key na configuração do Hydra ou no seu Load Balancer.

6. Inicialização do Serviço

Agora que tudo está configurado, podemos iniciar o servidor Hydra. O daemon expõe duas portas principais: a porta pública (geralmente 4444) para requisições OAuth e a porta administrativa (geralmente 4445) para gerenciar clientes e configurações.

# Modo de desenvolvimento/produção simplificado
hydra serve all \
  --dangerous-force-http \
  --config /caminho/para/config.yaml

No entanto, para um serviço em produção robusto, recomenda-se usar systemd para gerenciar o processo.

Crie o arquivo de serviço /etc/systemd/system/hydra.service:

[Unit]
Description=Ory Hydra OAuth2 Provider
After=network.target postgresql.service

[Service]
Type=simple
User=ubuntu
Group=ubuntu
ExecStart=/usr/local/bin/hydra serve all \
  --dangerous-allow-insecure-callbacks-for-localhost \
  --log-level info
EnvironmentFile=/home/ubuntu/hydra/.env
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Substitua User e Group pelo seu usuário Linux. Recarregue o systemd e inicie o serviço:

sudo systemctl daemon-reload
sudo systemctl enable hydra
sudo systemctl start hydra
sudo systemctl status hydra

Verifique os logs para garantir que não há erros de conexão com o banco de dados:

sudo journalctl -u hydra -f

7. Configuração do Proxy Reverso (Nginx/Apache)

Nunca exponha as portas 4444 e 4445 diretamente à internet. Utilize um proxy reverso como Nginx para gerenciar o TLS, balanceamento de carga e roteamento.

Exemplo de configuração básica no /etc/nginx/sites-available/hydra:

server {
    listen 443 ssl;
    server_name auth.seudominio.com;

    ssl_certificate /etc/letsencrypt/live/auth.seudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.seudominio.com/privkey.pem;

    # Proxy para a porta pública (OAuth)
    location / {
        proxy_pass http://127.0.0.1:4444;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Proxy para a porta administrativa (Admin)
    location /admin {
        proxy_pass http://127.0.0.1:4445;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Ative a configuração e reinicie o Nginx:

sudo ln -s /etc/nginx/sites-available/hydra /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

8. Registro do Cliente (Client Registration)

Agora que o Hydra está rodando, você precisa registrar sua aplicação como um "Cliente OAuth". Isso pode ser feito via API Admin ou usando a CLI.

Utilize a CLI para criar um cliente de teste:

hydra clients create \
  --endpoint http://127.0.0.1:4445/ \
  --id meu-app-cliente \
  --secret meu-segredo-super-forte \
  --grant-types authorization_code,refresh_token \
  --response-types code,id_token \
  --scope openid,offline,profile,email \
  --callbacks https://seudominio.com/callback

Explicação dos Parâmetros:

• --grant-types: Define quais fluxos o cliente pode usar (Authorization Code é o padrão seguro).
• --response-types: Tipos de resposta esperados (Code para OAuth, ID Token para OIDC).
• --callbacks: URLs onde o Hydra redirecionará após a autorização. Deve corresponder exatamente ao registrado.

9. Teste do Fluxo de Autenticação

Para validar se a infraestrutura está segura e funcional, inicie o fluxo OAuth 2.0. Abra seu navegador e acesse:

https://auth.seudominio.com/oauth2/auth?response_type=code&client_id=meu-app-cliente&scope=openid+offline+profile&redirect_uri=https://seudominio.com/callback&state=aleatorio123

O Hydra deve redirecionar você para uma página de login (se não estiver configurado um "Login Hook" ou UI personalizada, ele usará a UI padrão embutida para testes). Após inserir credenciais fictícias (ou configurar o hook de login), o sistema deverá redirecionar para sua redirect_uri com um código de autorização.

Use esse código para trocar por tokens no endpoint /oauth2/token:

curl -X POST https://auth.seudominio.com/oauth2/token \
  -d "grant_type=authorization_code" \
  -d "code=CODIGO_RECEBIDO" \
  -d "client_id=meu-app-cliente" \
  -d "client_secret=meu-segredo-super-forte" \
  -d "redirect_uri=https://seudominio.com/callback"

Se a resposta contiver access_token, refresh_token e id_token, seu provedor de identidade está operando corretamente.

10. Considerações Finais para Produção

A implementação do Ory Hydra self-hosted oferece controle total sobre a gestão de identidades, mas exige manutenção contínua. Mantenha o binário atualizado para receber patches de segurança. Monitore os logs e métricas (o Hydra expõe dados em Prometheus por padrão) para detectar tentativas de ataque ou falhas de conexão.

Além disso, considere implementar um Login Hook ou integrar com provedores SAML/OIDC existentes para não depender da UI padrão do Hydra para autenticação real. Isso permite que você gerencie a experiência do usuário e a validação de credenciais em suas próprias aplicações, enquanto o Hydra foca exclusivamente na emissão segura de tokens.

Com esta configuração, você tem uma base sólida para OAuth2 Provider em produção, garantindo segurança, escalabilidade e conformidade com os padrões modernos da web.