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

Introdução ao Ory Hydra Self-Hosted

A gestão de identidade e acesso é um dos pilares fundamentais da segurança moderna em infraestrutura. Para desenvolvedores e administradores de sistemas que buscam autonomia total, a abordagem ory hydra self-hosted surge como uma solução robusta e madura. O Ory Hydra atua como um OAuth 2.0 e OpenID Connect Provider (OP) de código aberto, permitindo que você controle completamente o fluxo de autenticação dos seus usuários sem depender de provedores de terceiros.

Diferente de bibliotecas de autenticação simples, o Hydra separa a lógica de interface do usuário da lógica de servidor, garantindo conformidade total com os padrões OAuth 2.1 e OpenID Connect Core. Este ory tutorial foca na implementação prática em um ambiente Linux via Docker, ideal para quem deseja construir uma camada de infraestrutura segura e escalável.

O objetivo aqui não é apenas instalar o software, mas configurar um ambiente de produção que utilize PostgreSQL como backend persistente, garantindo durabilidade dos dados e facilitando backups. Ao final deste guia, você terá um oauth2 provider funcional rodando em sua própria VPS, pronto para integrar com aplicações frontend ou APIs.

Pré-requisitos e Arquitetura do Ambiente

Antes de iniciar a configuração técnica, é essencial definir os componentes que compõem a stack. Para um cenário de produção mínimo viável, utilizaremos:

• Servidor Linux: Uma VPS com Debian 12 ou Ubuntu 22.04 LTS.
• Docker e Docker Compose: Essenciais para orquestrar os contêineres do Hydra e seus serviços dependentes.
• PostgreSQL: Banco de dados relacional para armazenar tokens, sessões e clientes registrados.
• Nginx (Opcional na v1): Para terminação SSL se o Hydra não for exposto diretamente à internet.

A segurança em vps segurança começa com a escolha da infraestrutura. Certifique-se de que seu firewall (UFW ou iptables) bloqueie todas as portas, exceto a 22 (SSH), 80 (HTTP) e 443 (HTTPS). O Hydra deve ser configurado para operar sobre HTTPS em produção; nunca utilize HTTP plano com tokens OAuth.

Passo 1: Preparação do Banco de Dados PostgreSQL

O primeiro passo concreto é provisionar o banco de dados. Embora seja possível usar bancos embutidos para testes, a persistência em produção exige um serviço dedicado. Vamos criar um container PostgreSQL isolado.

Crie um diretório para o projeto e inicie o arquivo docker-compose.yml. A configuração abaixo define o banco de dados com credenciais fortes. Substitua as variáveis de ambiente pelos seus segredos reais em produção.

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: hydra-postgres
    restart: always
    environment:
      POSTGRES_DB: hydra
      POSTGRES_USER: hydra_user
      POSTGRES_PASSWORD: super_secret_password_here
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - hydra-net

volumes:
  pgdata:

networks:
  hydra-net:
    driver: bridge

Inicie o serviço do banco de dados executando:

docker compose up -d postgres

Verifique se o container está rodando e saudável com docker ps. A rede hydra-net permite que os contêineres futuros se comuniquem internamente sem expor a porta 5432 diretamente para a internet, aumentando a segurança da sua solução de identidade linux.

Passo 2: Configuração do Ory Hydra

Agora que o banco está pronto, adicionaremos o serviço do Hydra ao docker-compose.yml. A configuração do Hydra é baseada em variáveis de ambiente, o que facilita a gestão de segredos e a portabilidade entre ambientes (dev/staging/prod).

Atualize seu arquivo docker-compose.yml para incluir o serviço hydra:

  hydra:
    image: oryd/hydra:v2.2.0
    container_name: hydra-server
    restart: always
    command: serve all --dangerous-force-http
    ports:
      - "4444:4444"
      - "4445:4445"
    environment:
      DSN: postgres://hydra_user:super_secret_password_here@postgres:5432/hydra?sslmode=disable
      GODEBUG: x509sha1=1
      STRATEGIES_ACCESS_TOKEN: jwt
      LOG_LEVEL: debug
      URLS_SELF_ISSUER: http://localhost:4444/
      URLS_LOGIN: http://localhost:4444/login/oauth2/auth
      URLS_CONSENT: http://localhost:4444/login/oauth2/consent
      URLS_POST_LOGOUT_REDIRECT: http://localhost:4444/logout
    networks:
      - hydra-net

Atenção Crítica: O flag --dangerous-force-http é necessário apenas se você estiver rodando o Hydra sem um proxy reverso (como Nginx ou Traefik) que gerencie o TLS. Em produção real, remova esse flag e configure certificados SSL corretamente. Para fins deste tutorial de configuração inicial, manteremos a simplicidade.

As variáveis de ambiente mais importantes aqui são:

• DSN: A string de conexão com o PostgreSQL que criamos no passo anterior.
• STRATEGIES_ACCESS_TOKEN: Define como os tokens de acesso são emitidos. JWT é o padrão recomendado para stateless validation.
• URLS_*: Configura os endpoints internos do Hydra para redirecionar usuários durante o fluxo OAuth2.

Passo 3: Migração do Banco de Dados

O Ory Hydra precisa inicializar suas tabelas no PostgreSQL. Isso é feito através das ferramentas de linha de comando (CLI) fornecidas pela imagem Docker. Você pode executar o comando de migração diretamente via docker compose run, o que evita a necessidade de instalar o CLI localmente.

Execute a migração automática:

docker compose run hydra migrate-sql postgres://hydra_user:super_secret_password_here@postgres:5432/hydra?sslmode=disable

Este comando criará todas as tabelas necessárias (como oauth2_auth_code, oauth2_jwt, clients, etc.). Se a operação for bem-sucedida, você verá uma mensagem de confirmação no terminal. Este é um momento crucial na configuração de open source auth, pois garante que o esquema do banco esteja sincronizado com a versão da imagem do Hydra.

Passo 4: Geração de Chaves Criptográficas

O Hydra utiliza pares de chaves RSA para assinar tokens JWT e certificados TLS. Para produção, você deve gerar essas chaves uma vez e armazená-las com segurança, ou gerá-las dinamicamente se for usar um sistema de gerenciamento de segredos externo (como HashiCorp Vault). Para este tutorial, vamos gerar as chaves padrão.

Pode-se fazer isso via CLI do Hydra ou manualmente. A maneira mais limpa no Docker é:

docker compose run hydra keys create --force

Isso criará um arquivo .hydra.keys.json dentro do container (se configurado com volume) ou gerará as chaves na memória. Em produção, recomenda-se montar um volume para este arquivo de chave para que ele persista entre reinicializações do container. Sem isso, cada reinício do container geraria novas chaves, invalidando todos os tokens emitidos anteriormente e quebrando a sessão dos usuários.

Para persistência, adicione um volume ao serviço hydra:

volumes:
  - ./keys:/etc/hydra/keys

E ajuste o comando para usar o arquivo de chave persistente:

command: ["sh", "-c", "migrate-sql postgres://... && keys create --force || true && serve all --dangerous-force-http"]

Passo 5: Inicialização do Serviço

Com o banco migrado e as chaves geradas, estamos prontos para iniciar o servidor principal. Execute:

docker compose up -d hydra

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

docker compose logs -f hydra

Você deve ver mensagens indicando que o servidor está ouvindo nas portas 4444 (API Pública) e 4445 (Admin API). A separação entre API Pública e Admin é uma característica de segurança do Hydra. A API Pública lida com requisições dos navegadores e clientes OAuth, enquanto a Admin API deve ficar restrita à rede interna ou protegida por firewall, pois permite manipulação direta de clientes e tokens.

Passo 6: Configuração do Cliente OAuth2

Agora que o provider está online, precisamos registrar um "Cliente" (sua aplicação) que solicitará autenticação. Usaremos a Admin API para fazer isso via linha de comando ou cURL.

Crie um arquivo client.json com as seguintes configurações:

{
  "id": "my-test-app",
  "name": "My Test Application",
  "redirect_uris": [
    "http://localhost:3000/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "scope": "openid profile email offline_access",
  "token_endpoint_auth_method": "none"
}

O campo redirect_uris é crítico. O Hydra validará estritamente se a URL de retorno corresponde exatamente ao registrado. O método token_endpoint_auth_method: none</strong>) indica que este cliente público (como uma SPA ou app mobile) não possui um segredo do cliente, o que é padrão para fluxos PKCE.</p> <p>Registre o cliente usando cURL contra a porta Admin (4445):</p> <pre><code>curl -X POST http://localhost:4445/clients \ -H "Content-Type: application/json" \ -d @client.json

Se o retorno for um JSON com o ID do cliente, a criação foi bem-sucedida.

Passo 7: Testando o Fluxo de Autorização (Login)

Para testar se tudo funciona, precisamos de uma interface de login. O Hydra não inclui uma UI de login padrão em produção; ele espera que você forneça um serviço que lide com a autenticação real e retorne ao fluxo. No entanto, o Hydra possui uma ferramenta de debug integrada chamada hydra login consent ou podemos usar o endpoint de introspecção.

A maneira mais rápida de validar o provider é tentar iniciar o fluxo OAuth2 manualmente no navegador ou via cURL simulado.

Abra a seguinte URL no seu navegador (substituindo localhost se estiver em uma VPS remota com DNS configurado):

http://localhost:4444/oauth2/auth?client_id=my-test-app&redirect_uri=http://localhost:3000/callback&response_type=code&scope=openid&state=xyz

Como não configuramos um serviço de login personalizado, o Hydra retornará um erro 500 ou uma página padrão se a variável URLS_LOGIN não apontar para um serviço ativo. Para este tutorial, assumimos que você tem um serviço de login simples rodando em http://localhost:4444/login/oauth2/auth ou que está usando o modo de desenvolvimento do Hydra.

Dica de Pro: Para testar sem escrever código de backend, utilize o projeto ory/hydra-oauth2-login ou similar para fornecer a interface de login temporária. No entanto, em produção, você desenvolverá seu próprio controlador que valida as credenciais do usuário e chama o endpoint /oauth2/auth?login_challenge=... fornecido pelo Hydra.

Passo 8: Hardening e Considerações de Segurança

A configuração básica está funcionando, mas para transformar isso em uma solução de vps segurança robusta, aplique as seguintes práticas:

1. Habilite HTTPS: Use Nginx ou Traefik como proxy reverso na frente do Hydra. Configure certificados Let's Encrypt (Certbot) para garantir a criptografia TLS.
2. Restrinja a Admin API: A porta 4445 não deve ser acessível publicamente. Configure regras de firewall para permitir acesso apenas ao IP do seu servidor de aplicação ou CI/CD.
3. Segredos no Docker Compose: Nunca coloque senhas diretamente no arquivo docker-compose.yml. Use arquivos .env ou variáveis de ambiente do sistema operacional.
4. Rotação de Chaves: Implemente um processo para rotacionar as chaves RSA e TLS periodicamente.

A configuração de proxy reverso com Nginx é crítica. Um exemplo básico de nginx.conf para expor o Hydra via HTTPS:

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;

    location / {
        proxy_pass http://hydra:4444;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Conclusão e Próximos Passos

Este tutorial cobriu a instalação e configuração básica do ory hydra self-hosted, demonstrando como integrar com PostgreSQL e Docker para criar um oauth2 provider funcional. Você aprendeu a estruturar a infraestrutura, migrar esquemas de banco de dados e registrar clientes.

O próximo passo natural é desenvolver o serviço de Login e Consentimento que interage com a API do Hydra. Isso envolve criar endpoints HTTP em sua aplicação (Node.js, Go, Python, etc.) que recebam os desafios de login/consentimento, validem as credenciais do usuário no seu banco de dados existente e confirmem ou neguem o acesso ao Hydra.

Ao adotar essa arquitetura, você ganha controle total sobre a identidade dos seus usuários, reduz a dependência de fornecedores e alinha sua stack às melhores práticas de infraestrutura segura. O Hydra é uma escolha sólida para empresas que levam a conformidade e a privacidade de dados a sério.

Para mais detalhes técnicos, consulte a documentação oficial do Ory, mas lembre-se: em ambientes Linux e Docker, a simplicidade da configuração inicial deve sempre evoluir para um modelo de segurança defendido em profundidade. Teste rigorosamente seus fluxos OAuth2 antes de colocar em produção.