Ory Kratos + Hydra OAuth2 Integration Setup

This repository contains a complete Docker Compose setup for running Ory Kratos (identity management) and Ory Hydra (OAuth2/OpenID Connect server) with full integration between both services. This setup provides a production-ready foundation for identity and OAuth2/OIDC workflows.

🏗️ Architecture

• Ory Kratos: Identity and user management with OAuth2 provider integration
• Ory Hydra: OAuth2 and OpenID Connect provider
• PostgreSQL: Separate databases for Kratos and Hydra
• Kratos Self-Service UI: Web interface for user registration, login, and account management
• MailSlurper: Email testing server for development

✨ Features

• ✅ Complete OAuth2/OIDC Integration: Kratos and Hydra work seamlessly together
• ✅ User Registration & Login: Full self-service user management
• ✅ Session Management: Integrated session handling between services
• ✅ Email Verification: Automated email verification workflows
• ✅ Password Recovery: Self-service password reset
• ✅ Multi-Factor Authentication: TOTP and backup codes support
• ✅ CORS Configuration: Properly configured for frontend integration
• ✅ Development Ready: Optimized for local development with debugging

🚀 Quick Start

Option 1: Complete Automated Setup

./setup-oauth-integration.sh

This script will:

• Start all services with Docker Compose
• Wait for services to be ready
• Initialize OAuth2 clients
• Run integration tests
• Display service URLs and usage instructions

Option 2: Manual Setup

1. Start all services:

   docker-compose up -d

2. Wait for services to be ready, then initialize OAuth2 clients:

   ./init-clients.sh

3. Test the integration:

   ./test-oauth-integration.sh

🌐 Service URLs

• Self-Service UI: http://127.0.0.1:3000
• Kratos Public API: http://127.0.0.1:4433
• Kratos Admin API: http://127.0.0.1:4434
• Hydra Public API: http://127.0.0.1:4444
• Hydra Admin API: http://127.0.0.1:4445
• MailSlurper Web UI: http://127.0.0.1:4437

🔧 OAuth2 Client Management

Use the included client management helper:

# List all OAuth2 clients
./manage-oauth-clients.sh list

# Create different types of clients
./manage-oauth-clients.sh create spa --name "My SPA" --redirect-uri "http://localhost:8080/callback"
./manage-oauth-clients.sh create web --name "My Web App" --secret "my-secret"
./manage-oauth-clients.sh create mobile --name "My Mobile App"
./manage-oauth-clients.sh create service --name "My API Service"

# Get client details
./manage-oauth-clients.sh get [client-id]

# Delete a client
./manage-oauth-clients.sh delete [client-id]

🔐 OAuth2 Integration Flow

1. User Registration/Login with Kratos

Browser → Kratos Self-Service UI (Port 3000)
       ↓
User registers/logs in → Kratos creates session
       ↓
Session stored and managed by Kratos

2. OAuth2 Authorization Flow

App → Hydra Authorization Endpoint (Port 4444)
    ↓
Hydra → Kratos Login UI (if user not authenticated)
      ↓
User logs in → Kratos validates credentials
            ↓
Kratos → Hydra (user authenticated)
       ↓
Hydra → App (authorization code)
      ↓
App → Hydra Token Endpoint (exchange code for tokens)
    ↓
Hydra returns access_token, id_token, refresh_token

3. Sample Authorization URL

http://127.0.0.1:4444/oauth2/auth?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  scope=openid%20email%20profile&
  redirect_uri=http://127.0.0.1:3000/auth/callback&
  state=random-state-value

🔨 Configuration Details

Kratos OAuth2 Provider Integration

oauth2_provider:
  url: http://hydra:4444
  override_return_to: true
  headers:
    X-Forwarded-Proto: http

Session Configuration

session:
  lifespan: 24h
  earliest_possible_extend: 1h
  cookie:
    domain: 127.0.0.1
    same_site: Lax

Enhanced Identity Schema

The identity schema now includes additional fields for better OAuth2 integration:

• Email (required, used for authentication)
• Name (first and last)
• Username (optional)
• Profile picture (optional)

🧪 Testing

Integration Tests

./test-oauth-integration.sh

This script tests:

• Service health checks
• OAuth2 client creation
• Authorization endpoint accessibility
• Registration and login flow initiation
• CORS configuration

Manual Testing

1. Register a new user:

   • Go to http://127.0.0.1:3000
   • Click "Sign Up"
   • Enter email and password
   • Check MailSlurper for verification email

2. Test OAuth2 flow:

   • Use the authorization URL from the test script
   • Complete login if not already authenticated
   • Verify redirect with authorization code

📱 Frontend Integration Examples

JavaScript (SPA)

// Initiate OAuth2 flow
const authUrl = `http://127.0.0.1:4444/oauth2/auth?` +
  `client_id=YOUR_CLIENT_ID&` +
  `response_type=code&` +
  `scope=openid email profile&` +
  `redirect_uri=${encodeURIComponent('http://localhost:8080/callback')}&` +
  `state=${generateRandomState()}`;

window.location.href = authUrl;

// Handle callback and exchange code for tokens
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

if (code) {
  const tokenResponse = await fetch('http://127.0.0.1:4444/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: 'http://localhost:8080/callback',
      client_id: 'YOUR_CLIENT_ID',
      // client_secret: 'YOUR_SECRET' // Only for confidential clients
    })
  });
  
  const tokens = await tokenResponse.json();
  // Use tokens.access_token, tokens.id_token, tokens.refresh_token
}

Node.js Backend

const express = require('express');
const axios = require('axios');

const app = express();

// Verify token with Hydra
app.get('/protected', async (req, res) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  
  try {
    const response = await axios.post('http://127.0.0.1:4445/admin/oauth2/introspect', {
      token: token
    });
    
    if (response.data.active) {
      res.json({ message: 'Access granted', user: response.data });
    } else {
      res.status(401).json({ error: 'Invalid token' });
    }
  } catch (error) {
    res.status(401).json({ error: 'Token verification failed' });
  }
});

🔍 Monitoring and Debugging

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f kratos
docker-compose logs -f hydra
docker-compose logs -f kratos-selfservice-ui

Health Checks

# Kratos health
curl http://127.0.0.1:4433/health/ready

# Hydra health
curl http://127.0.0.1:4444/health/ready

Database Access

# Kratos database
docker exec -it kratos-postgres psql -U kratos -d kratos

# Hydra database
docker exec -it hydra-postgres psql -U hydra -d hydra

🚨 Security Notes

⚠️ This setup is optimized for development!

For production deployment:

• Change all default secrets and passwords
• Enable SSL/TLS for all services
• Configure proper CORS policies
• Use production-grade databases with proper backup
• Set up proper networking and firewalls
• Enable audit logging
• Configure rate limiting
• Use secure cookie settings

🛠️ Useful Commands

# Reset everything
docker-compose down -v && docker-compose up -d

# List Kratos identities
docker exec kratos kratos list identities --endpoint http://127.0.0.1:4434

# Create custom OAuth2 client
docker exec hydra hydra create oauth2-client \
  --endpoint http://127.0.0.1:4445 \
  --name "Custom Client" \
  --secret "custom-secret" \
  --grant-type authorization_code,refresh_token \
  --response-type code,id_token \
  --scope openid,email,profile \
  --redirect-uri http://localhost:8080/callback

# Get OAuth2 client details
docker exec hydra hydra get oauth2-client CLIENT_ID --endpoint http://127.0.0.1:4445

� Go OAuth2 Client

This repository includes a complete Go application that demonstrates OAuth2 integration with your Ory Hydra setup.

Features

• 🔐 Complete OAuth2 Authorization Code flow
• 🎫 Access token, refresh token, and ID token handling
• 🔄 Token refresh functionality
• 👤 User info endpoint integration
• 🏥 Health checks for Ory services
• 🔍 Token introspection
• 🌐 Web interface for easy testing

Quick Start with Go Client

# Setup and build the Go client
./setup-go-client.sh

# Run the Go client (automatically gets client ID)
make run-go-client

# Or manually with specific client ID
export CLIENT_ID=$(docker exec hydra hydra list oauth2-clients --endpoint http://127.0.0.1:4445 --format json | jq -r '.[0].client_id')
cd go-client && ./hydra-client

Go Client URLs

• Web Interface: http://127.0.0.1:8080
• Health Check: http://127.0.0.1:8080/api/health
• Login Flow: http://127.0.0.1:8080/login

Go Client Testing

# Test the Go client
./test-go-client.sh

# Available Make commands
make setup-go-client    # Setup Go OAuth2 client
make test-go-client     # Test Go OAuth2 client
make run-go-client      # Run Go OAuth2 client

See go-client/README.md for detailed Go client documentation.

�📚 Documentation

• Ory Kratos Documentation
• Ory Hydra Documentation
• OAuth2 and OpenID Connect Flows
• Kratos Self-Service Flows
• Go OAuth2 Client README