Generic OIDC Provider Setup Tutorial

Generic OIDC Provider Setup Tutorial

This tutorial walks you through setting up generic OpenID Connect (OIDC) Single Sign-On (SSO) authentication for ContextForge, enabling integration with any OIDC-compliant identity provider including Keycloak, Auth0, Authentik, and others.

Overview

The Generic OIDC provider support allows you to integrate ContextForge with any standards-compliant OpenID Connect provider. This flexibility enables you to use your existing identity infrastructure regardless of the vendor.

Supported Providers (non-exhaustive):

• Keycloak
• Auth0
• Authentik
• Authelia
• Ory Hydra
• GitLab (as OIDC provider)
• Casdoor
• FusionAuth
• Any other OIDC-compliant provider

Prerequisites

• ContextForge installed and running
• Access to your OIDC provider's admin console
• Ability to create OAuth/OIDC applications in your provider
• Access to your gateway's environment configuration
• HTTPS enabled on your gateway (recommended for production)

Understanding OIDC Discovery

Most OIDC providers support automatic discovery via the .well-known/openid-configuration endpoint:

# Example discovery endpoints
https://keycloak.company.com/auth/realms/master/.well-known/openid-configuration
https://your-tenant.auth0.com/.well-known/openid-configuration
https://authentik.company.com/application/o/app-name/.well-known/openid-configuration

This endpoint returns all necessary URLs for OIDC integration. You can use curl or a browser to view it:

curl https://your-provider.com/.well-known/openid-configuration | jq .

Look for these key fields:

• authorization_endpoint → SSO_GENERIC_AUTHORIZATION_URL
• token_endpoint → SSO_GENERIC_TOKEN_URL
• userinfo_endpoint → SSO_GENERIC_USERINFO_URL
• issuer → SSO_GENERIC_ISSUER

Step 1: Choose Your Provider ID

Select a unique identifier for your provider. This will be used in URLs and configuration.

Guidelines:

• Use lowercase alphanumeric characters and hyphens
• Common choices: keycloak, auth0, authentik, gitlab, custom-sso
• Avoid: github, google, okta, entra, ibm_verify (reserved for built-in providers)

Example: If using Keycloak, you might choose keycloak or company-sso

This becomes your callback URL:

https://gateway.yourcompany.com/auth/sso/callback/{provider_id}

Step 2: Configure Your OIDC Provider

Choose your provider below for specific setup instructions:

Option A: Keycloak Setup

2A.1 Create Client Application

1. Log in to Keycloak Admin Console
2. Select your realm (e.g., master or custom realm)
3. Go to Clients → Create client

Settings:

• Client type: OpenID Connect
• Client ID: mcp-gateway (or your choice)
• Client authentication: ON (confidential client)
• Authorization: OFF (not needed for SSO)

2A.2 Configure Client Settings

Access Settings:

• Root URL: https://gateway.yourcompany.com
• Home URL: https://gateway.yourcompany.com/admin
• Valid redirect URIs: https://gateway.yourcompany.com/auth/sso/callback/keycloak
• Valid post logout redirect URIs: https://gateway.yourcompany.com/admin/login
• Web origins: https://gateway.yourcompany.com

Advanced Settings:

• Access Token Lifespan: 5 minutes (default is fine)
• Client authentication: ON
• Standard flow: Enabled (Authorization Code Flow)
• Direct access grants: Disabled (not needed)

2A.3 Get Client Credentials

1. Go to Clients → Select your client → Credentials tab
2. Copy the Client secret
3. Note your realm name from the URL

Your endpoints will be:

# For realm "master" on keycloak.company.com:
Authorization: https://keycloak.company.com/auth/realms/master/protocol/openid-connect/auth
Token:         https://keycloak.company.com/auth/realms/master/protocol/openid-connect/token
Userinfo:      https://keycloak.company.com/auth/realms/master/protocol/openid-connect/userinfo
Issuer:        https://keycloak.company.com/auth/realms/master

2A.4 Configure Scopes (Optional)

1. Go to Client scopes tab

2. Ensure these scopes are in Assigned default client scopes:

   • openid (required)
   • profile (recommended)
   • email (recommended)

2A.5 Map User Attributes (Optional)

To ensure proper user info:

1. Go to Clients → Your client → Client scopes

2. Click on profile scope

3. Verify these mappers exist:

   • email → User attribute email
   • given_name → User attribute firstName
   • family_name → User attribute lastName
   • preferred_username → User attribute username

Option B: Auth0 Setup

2B.1 Create Application

1. Log in to Auth0 Dashboard
2. Go to Applications → Applications
3. Click + Create Application

Settings:

• Name: ContextForge
• Application type: Regular Web Applications
• Click Create

2B.2 Configure Application Settings

In the application settings:

Application URIs:

• Allowed Callback URLs: https://gateway.yourcompany.com/auth/sso/callback/auth0
• Allowed Logout URLs: https://gateway.yourcompany.com/admin/login
• Allowed Web Origins: https://gateway.yourcompany.com

Advanced Settings → Grant Types:

• ✅ Authorization Code
• ✅ Refresh Token (optional)
• ❌ Implicit (not needed)

Click Save Changes

2B.3 Get Client Credentials

In the Settings tab:

• Copy Domain: your-tenant.auth0.com
• Copy Client ID
• Copy Client Secret

Your endpoints will be:

Authorization: https://your-tenant.auth0.com/authorize
Token:         https://your-tenant.auth0.com/oauth/token
Userinfo:      https://your-tenant.auth0.com/userinfo
Issuer:        https://your-tenant.auth0.com/

2B.4 Configure Connection (Optional)

1. Go to Authentication → Database or Enterprise
2. Configure your identity source (Active Directory, LDAP, etc.)
3. Enable the connection for your application

Option C: Authentik Setup

2C.1 Create Provider

1. Log in to Authentik Admin Interface
2. Go to Applications → Providers
3. Click Create

Provider Settings:

• Name: ContextForge Provider
• Type: OAuth2/OpenID Provider
• Client type: Confidential
• Client ID: Auto-generated or custom
• Client Secret: Auto-generated (copy this)
• Redirect URIs: https://gateway.yourcompany.com/auth/sso/callback/authentik

Advanced Settings:

• Scopes: openid profile email
• Subject mode: Based on the User's hashed ID
• Include claims in id_token: Yes

Click Create

2C.2 Create Application

1. Go to Applications → Applications
2. Click Create

Application Settings:

• Name: ContextForge
• Slug: mcp-gateway
• Provider: Select the provider you just created
• Launch URL: https://gateway.yourcompany.com/admin

2C.3 Get Configuration

Your endpoints will be:

# Assuming app slug is "mcp-gateway"
Authorization: https://authentik.company.com/application/o/authorize/
Token:         https://authentik.company.com/application/o/token/
Userinfo:      https://authentik.company.com/application/o/userinfo/
Issuer:        https://authentik.company.com/application/o/mcp-gateway/

Note: Authentik URLs typically include the application slug in the issuer URL.

Step 3: Configure ContextForge

3.1 Basic Configuration

Add these variables to your .env file:

# Enable SSO System
SSO_ENABLED=true

# Generic OIDC Provider Configuration
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=keycloak  # Change to your chosen ID
SSO_GENERIC_DISPLAY_NAME=Company SSO  # Display name on login button
SSO_GENERIC_CLIENT_ID=your-client-id
SSO_GENERIC_CLIENT_SECRET=your-client-secret
SSO_GENERIC_AUTHORIZATION_URL=https://your-provider.com/auth
SSO_GENERIC_TOKEN_URL=https://your-provider.com/token
SSO_GENERIC_USERINFO_URL=https://your-provider.com/userinfo
SSO_GENERIC_ISSUER=https://your-provider.com
SSO_GENERIC_SCOPE=openid profile email  # Optional, this is the default

# Optional: Auto-create users on first login
SSO_AUTO_CREATE_USERS=true

# Optional: Restrict to corporate email domains
SSO_TRUSTED_DOMAINS=["yourcompany.com"]

# Optional: Preserve local admin authentication
SSO_PRESERVE_ADMIN_AUTH=true

3.2 Keycloak Configuration Example

# Keycloak on keycloak.company.com with realm "master"
SSO_ENABLED=true
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=keycloak
SSO_GENERIC_DISPLAY_NAME=Company SSO
SSO_GENERIC_CLIENT_ID=mcp-gateway
SSO_GENERIC_CLIENT_SECRET=AbC123dEf456GhI789jKl012MnO345pQr678StU901vWx234YzA567
SSO_GENERIC_AUTHORIZATION_URL=https://keycloak.company.com/auth/realms/master/protocol/openid-connect/auth
SSO_GENERIC_TOKEN_URL=https://keycloak.company.com/auth/realms/master/protocol/openid-connect/token
SSO_GENERIC_USERINFO_URL=https://keycloak.company.com/auth/realms/master/protocol/openid-connect/userinfo
SSO_GENERIC_ISSUER=https://keycloak.company.com/auth/realms/master
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["company.com"]

3.3 Auth0 Configuration Example

# Auth0 tenant
SSO_ENABLED=true
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=auth0
SSO_GENERIC_DISPLAY_NAME=Auth0
SSO_GENERIC_CLIENT_ID=AbCdEfGhIjKlMnOpQrStUvWx
SSO_GENERIC_CLIENT_SECRET=1234567890abcdefghijklmnopqrstuvwxyz1234567890ABCDEFG
SSO_GENERIC_AUTHORIZATION_URL=https://your-tenant.auth0.com/authorize
SSO_GENERIC_TOKEN_URL=https://your-tenant.auth0.com/oauth/token
SSO_GENERIC_USERINFO_URL=https://your-tenant.auth0.com/userinfo
SSO_GENERIC_ISSUER=https://your-tenant.auth0.com/
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["company.com"]

3.4 Authentik Configuration Example

# Authentik with application slug "mcp-gateway"
SSO_ENABLED=true
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=authentik
SSO_GENERIC_DISPLAY_NAME=Authentik SSO
SSO_GENERIC_CLIENT_ID=generated-client-id-from-authentik
SSO_GENERIC_CLIENT_SECRET=generated-client-secret-from-authentik
SSO_GENERIC_AUTHORIZATION_URL=https://authentik.company.com/application/o/authorize/
SSO_GENERIC_TOKEN_URL=https://authentik.company.com/application/o/token/
SSO_GENERIC_USERINFO_URL=https://authentik.company.com/application/o/userinfo/
SSO_GENERIC_ISSUER=https://authentik.company.com/application/o/mcp-gateway/
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["company.com"]

3.5 Development Configuration

For local testing:

# Development setup with HTTP (not recommended for production)
SSO_ENABLED=true
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=keycloak-dev
SSO_GENERIC_DISPLAY_NAME=Dev SSO
SSO_GENERIC_CLIENT_ID=dev-client-id
SSO_GENERIC_CLIENT_SECRET=dev-client-secret
SSO_GENERIC_AUTHORIZATION_URL=http://localhost:8080/auth/realms/master/protocol/openid-connect/auth
SSO_GENERIC_TOKEN_URL=http://localhost:8080/auth/realms/master/protocol/openid-connect/token
SSO_GENERIC_USERINFO_URL=http://localhost:8080/auth/realms/master/protocol/openid-connect/userinfo
SSO_GENERIC_ISSUER=http://localhost:8080/auth/realms/master
SSO_AUTO_CREATE_USERS=true
SSO_PRESERVE_ADMIN_AUTH=true

# Note: Update callback URL in provider to:
# http://localhost:4444/auth/sso/callback/keycloak-dev

Step 4: Verify OIDC Endpoints

Before starting the gateway, verify your provider's endpoints are accessible:

# Test authorization endpoint (should return HTML page or redirect)
curl -I https://your-provider.com/auth

# Test discovery endpoint
curl https://your-provider.com/.well-known/openid-configuration | jq .

# Verify these match your configuration:
# - authorization_endpoint
# - token_endpoint
# - userinfo_endpoint
# - issuer

Step 5: Start and Verify Gateway

5.1 Restart the Gateway

# Development
make dev

# Production
make serve

# Docker
docker-compose restart gateway

5.2 Verify Generic OIDC Provider is Listed

# Check if your provider appears in the list
curl -X GET http://localhost:8000/auth/sso/providers

# Should include your provider:
[
  {
    "id": "keycloak",
    "name": "keycloak",
    "display_name": "Company SSO"
  }
]

5.3 Check Startup Logs

# Look for SSO initialization messages
tail -f logs/gateway.log | grep -i sso

# Should see:
# ✅ Created SSO provider: Company SSO
# or
# 🔄 Updated SSO provider: Company SSO

Step 6: Test OIDC Login Flow

6.1 Access Login Page

1. Navigate to your gateway's login page:

   • Development: http://localhost:8000/admin/login
   • Production: https://gateway.yourcompany.com/admin/login

2. You should see a button with your configured SSO_GENERIC_DISPLAY_NAME

6.2 Test Authentication Flow

1. Click the Company SSO button (or your display name)
2. You'll be redirected to your OIDC provider's sign-in page
3. Enter your credentials
4. Complete any MFA if configured
5. Grant consent if prompted (first-time users)
6. You'll be redirected back to the gateway
7. You should be logged in successfully

6.3 Verify User Creation

Check that a user was created:

# Using admin API (requires admin token)
curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  http://localhost:8000/auth/users

# Look for your email in the user list

6.4 Verify User Profile

# Get user details
curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  http://localhost:8000/auth/users/{user_id}

# Verify fields:
# - email: your@company.com
# - full_name: First Last
# - provider: keycloak (or your provider_id)
# - provider_id: unique-user-id-from-provider

Step 7: Advanced Configuration

7.1 Custom Scopes

Add additional scopes if your provider supports them:

# Example: Add group membership scope
SSO_GENERIC_SCOPE=openid profile email groups roles

# Or organization access
SSO_GENERIC_SCOPE=openid profile email read:org

Verify your provider supports these scopes in their documentation.

7.2 Multiple OIDC Providers

To configure multiple generic providers, use the Admin API:

# Create additional providers via API
curl -X POST http://localhost:8000/auth/sso/admin/providers \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "gitlab",
    "name": "gitlab",
    "display_name": "GitLab",
    "provider_type": "oidc",
    "client_id": "gitlab-client-id",
    "client_secret": "gitlab-client-secret",
    "authorization_url": "https://gitlab.com/oauth/authorize",
    "token_url": "https://gitlab.com/oauth/token",
    "userinfo_url": "https://gitlab.com/oauth/userinfo",
    "issuer": "https://gitlab.com",
    "scope": "openid profile email",
    "trusted_domains": ["company.com"],
    "auto_create_users": true
  }'

7.3 Trusted Domains

Restrict access to specific email domains:

# Single domain
SSO_TRUSTED_DOMAINS=["company.com"]

# Multiple domains
SSO_TRUSTED_DOMAINS=["company.com", "partner.com", "contractor.net"]

Users with email addresses outside these domains will be rejected.

7.4 Team Mapping (Advanced)

Configure automatic team assignment using the Admin API:

# Update provider with team mapping
curl -X PUT http://localhost:8000/auth/sso/admin/providers/keycloak \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_mapping": {
      "engineering": {
        "team_id": "uuid-of-engineering-team",
        "role": "member"
      },
      "admin": {
        "team_id": "uuid-of-admin-team",
        "role": "owner"
      }
    }
  }'

Troubleshooting

Error: "SSO authentication is disabled"

Problem: SSO endpoints return 404 Solution: Verify SSO_ENABLED=true and SSO_GENERIC_ENABLED=true, then restart

curl -I http://localhost:8000/auth/sso/providers
# Should return 200 OK

Error: "invalid_client"

Problem: Client ID or secret is incorrect Solution: Verify credentials match your provider exactly

# Double-check these values from your provider
SSO_GENERIC_CLIENT_ID=actual-client-id-from-provider
SSO_GENERIC_CLIENT_SECRET=actual-secret-from-provider

Error: "redirect_uri_mismatch"

Problem: Callback URL doesn't match provider configuration Solution: Ensure exact match including protocol and trailing slashes

# Provider configuration must exactly match:
https://gateway.yourcompany.com/auth/sso/callback/keycloak

# Common mistakes:
https://gateway.yourcompany.com/auth/sso/callback/keycloak/  # Extra slash
http://gateway.yourcompany.com/auth/sso/callback/keycloak   # HTTP vs HTTPS
https://gateway.yourcompany.com/auth/sso/callback/generic   # Wrong provider_id

Error: "invalid_scope"

Problem: Requested scope not supported by provider Solution: Check provider documentation for supported scopes

# Start with minimal scopes
SSO_GENERIC_SCOPE=openid profile email

# Add scopes incrementally after testing

Error: "issuer mismatch"

Problem: Token issuer doesn't match configured issuer Solution: Verify issuer URL format matches provider exactly

# Check discovery endpoint
curl https://your-provider.com/.well-known/openid-configuration | jq '.issuer'

# Ensure SSO_GENERIC_ISSUER matches exactly (including trailing slash)
SSO_GENERIC_ISSUER=https://your-provider.com/  # Note the trailing slash if needed

Token Validation Errors

Problem: JWT tokens failing validation Solution: Enable debug logging to see token validation details

# Enable debug logging
LOG_LEVEL=DEBUG

# Check logs for token validation errors
tail -f logs/gateway.log | grep -i token

User Info Endpoint Issues

Problem: User profile incomplete or missing Solution: Verify userinfo endpoint and scope configuration

# Test userinfo endpoint directly
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://your-provider.com/userinfo

# Should return user profile JSON
# Verify email, name, and preferred_username fields exist

Certificate/SSL Errors

Problem: SSL certificate verification failing Solution: For development only, you can skip verification (not recommended for production)

# Development only - DO NOT use in production
SKIP_SSL_VERIFY=true

For production, fix the certificate issue at the provider level.

Testing Checklist

• Provider application created with correct settings
• Client ID and secret obtained
• Redirect URI configured correctly
• Required scopes configured
• Discovery endpoint accessible
• Environment variables configured
• Gateway restarted
• Provider appears in /auth/sso/providers list
• Login page shows provider button
• Authentication flow completes
• User created in gateway
• User profile populated
• Email domain restriction working (if configured)
• Logout redirects correctly

Security Best Practices

Secret Management

DO:

• ✅ Store secrets in environment variables or secret management systems
• ✅ Use strong, randomly generated client secrets
• ✅ Rotate secrets regularly (every 90-180 days)
• ✅ Use separate credentials for dev/staging/prod
• ✅ Enable HTTPS for all redirect URIs

DON'T:

• ❌ Store secrets in source control
• ❌ Share secrets via email or chat
• ❌ Use the same credentials across environments
• ❌ Use HTTP in production

Access Control

1. Trusted Domains: Always configure SSO_TRUSTED_DOMAINS in production
2. User Review: Implement user approval workflows if needed
3. Scope Minimization: Only request necessary scopes
4. Regular Audits: Review user access quarterly

Provider Security

1. Enable MFA on your OIDC provider
2. Configure session timeouts appropriately
3. Enable audit logging for all authentication events
4. Monitor failed login attempts
5. Review access logs regularly

Next Steps

After Generic OIDC SSO is working:

1. Configure team mappings for automatic team assignment
2. Set up additional providers via Admin API if needed
3. Enable MFA on your OIDC provider
4. Configure conditional access policies (provider-specific)
5. Set up monitoring for authentication events
6. Document your configuration for team reference

Provider-Specific Resources

Keycloak

• Keycloak Documentation
• Client Configuration Guide
• Client Authentication

Auth0

• Auth0 Documentation
• Application Settings
• Configure OpenID Connect

Authentik

• Authentik Documentation
• OAuth2/OIDC Provider
• Application Configuration

Related Documentation

• Complete SSO Guide - Full SSO documentation
• Microsoft Entra ID Tutorial - Entra ID setup
• GitHub SSO Tutorial - GitHub setup
• Google SSO Tutorial - Google setup
• Team Management - Managing teams and roles
• RBAC Configuration - Role-based access control

Support

Getting Help

If you encounter issues:

1. Check provider's authentication logs for error details
2. Enable debug logging: LOG_LEVEL=DEBUG
3. Review gateway logs for OIDC-specific errors
4. Test provider endpoints directly with curl
5. Verify all URLs match provider documentation exactly
6. Consult provider-specific documentation
7. Check ContextForge issue tracker

Common OIDC Standards

• OpenID Connect Core 1.0
• OAuth 2.0 Authorization Framework
• OpenID Connect Discovery