Ory Hydra

Key Features

• RFC-compliant OAuth 2.0 Authorization Server with support for all standard grant types including authorization code, client credentials, and refresh token flows
• OpenID Connect Provider implementation with support for ID tokens, userinfo endpoint, and discovery mechanisms
• Dual-port architecture with separate public OAuth2 API (4444) and administrative API (4445) for security isolation
• PostgreSQL-backed persistence with ACID-compliant storage for OAuth2 clients, tokens, and authorization grants
• Consent and login flow delegation allowing integration with existing authentication systems and custom user interfaces
• Advanced token introspection and revocation capabilities through the administrative API
• Built-in support for JWT access tokens with configurable signing algorithms and key rotation
• Database migration system ensuring schema versioning and upgrade compatibility across Hydra releases

Common Use Cases

• 1API gateway authorization for microservices architectures requiring centralized OAuth2 token validation
• 2Single sign-on (SSO) implementation for multi-application environments with existing user authentication systems
• 3Third-party application integration hub allowing external developers to build applications against your APIs
• 4Zero-trust network security implementation where every service-to-service communication requires valid OAuth2 tokens
• 5Mobile application backend providing secure token-based authentication for iOS and Android applications
• 6Enterprise B2B integration platform enabling partner applications to access internal APIs through standardized OAuth2 flows
• 7Multi-tenant SaaS platform requiring isolated OAuth2 clients and scopes for different customer organizations

Prerequisites

• Minimum 1GB RAM for PostgreSQL database operations and Hydra token processing
• Available ports 4444 (OAuth2 public API) and 4445 (administrative API) for external access
• Separate login and consent application implementation as Hydra delegates user authentication flows
• Understanding of OAuth 2.0 authorization flows and OpenID Connect concepts for proper client configuration
• TLS certificate management knowledge for production deployments requiring HTTPS endpoints
• Database backup and recovery procedures for protecting OAuth2 client credentials and token data

docker-compose.yml

1services: 
2  hydra: 
3    image: oryd/hydra:latest
4    container_name: hydra
5    restart: unless-stopped
6    environment: 
7      DSN: postgres://hydra:${DB_PASSWORD}@postgres:5432/hydra?sslmode=disable
8      SECRETS_SYSTEM: ${SECRETS_SYSTEM}
9      URLS_SELF_ISSUER: http://localhost:4444
10      URLS_LOGIN: http://localhost:3000/login
11      URLS_CONSENT: http://localhost:3000/consent
12    command: serve all --dev
13    ports: 
14      - "4444:4444"
15      - "4445:4445"
16    depends_on: 
17      - postgres
18
19  postgres: 
20    image: postgres:15-alpine
21    container_name: hydra-db
22    environment: 
23      POSTGRES_USER: hydra
24      POSTGRES_PASSWORD: ${DB_PASSWORD}
25      POSTGRES_DB: hydra
26    volumes: 
27      - hydra_db:/var/lib/postgresql/data
28
29volumes: 
30  hydra_db: 

.env Template

1DB_PASSWORD=changeme
2SECRETS_SYSTEM=generate-32-char-secret

Usage Notes

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

hydra:
  image: oryd/hydra:latest
  container_name: hydra
  restart: unless-stopped
  environment:
    DSN: postgres://hydra:${DB_PASSWORD}@postgres:5432/hydra?sslmode=disable
    SECRETS_SYSTEM: ${SECRETS_SYSTEM}
    URLS_SELF_ISSUER: http://localhost:4444
    URLS_LOGIN: http://localhost:3000/login
    URLS_CONSENT: http://localhost:3000/consent
  command: serve all --dev
  ports:
    - "4444:4444"
    - "4445:4445"
  depends_on:
    - postgres

postgres:
  image: postgres:15-alpine
  container_name: hydra-db
  environment:
    POSTGRES_USER: hydra
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_DB: hydra
  volumes:
    - hydra_db:/var/lib/postgresql/data

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  hydra:
5    image: oryd/hydra:latest
6    container_name: hydra
7    restart: unless-stopped
8    environment:
9      DSN: postgres://hydra:${DB_PASSWORD}@postgres:5432/hydra?sslmode=disable
10      SECRETS_SYSTEM: ${SECRETS_SYSTEM}
11      URLS_SELF_ISSUER: http://localhost:4444
12      URLS_LOGIN: http://localhost:3000/login
13      URLS_CONSENT: http://localhost:3000/consent
14    command: serve all --dev
15    ports:
16      - "4444:4444"
17      - "4445:4445"
18    depends_on:
19      - postgres
20
21  postgres:
22    image: postgres:15-alpine
23    container_name: hydra-db
24    environment:
25      POSTGRES_USER: hydra
26      POSTGRES_PASSWORD: ${DB_PASSWORD}
27      POSTGRES_DB: hydra
28    volumes:
29      - hydra_db:/var/lib/postgresql/data
30
31volumes:
32  hydra_db:
33EOF
34
35# 2. Create the .env file
36cat > .env << 'EOF'
37DB_PASSWORD=changeme
38SECRETS_SYSTEM=generate-32-char-secret
39EOF
40
41# 3. Start the services
42docker compose up -d
43
44# 4. View logs
45docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/ory-hydra/run | bash

Troubleshooting