OIDC Setup Guide

This guide provides step-by-step instructions for integrating OIDC (OpenID Connect) identity providers with the Inference API platform. The platform supports multiple OIDC providers including Microsoft Entra ID (Azure AD), Auth0, JumpCloud, Keycloak, and any standard OIDC-compliant provider.

Table of Contents

1. Prerequisites
2. Understanding OIDC Configuration
3. General Setup Steps
4. Provider-Specific Guides
5. Platform Configuration
6. Testing the Integration
7. Troubleshooting
8. Security Best Practices

Prerequisites

Before setting up OIDC integration, ensure you have:

1. Access to your OIDC Provider: Administrative access to configure applications in your identity provider
2. Platform Access: Access to configure tenant settings in the Inference API platform
3. Network Access: The platform must be able to reach your OIDC provider's endpoints (authorization, token, userinfo, JWKS)
4. HTTPS: All communication must use HTTPS (required for OIDC security)
5. Callback URL: A publicly accessible callback URL for your platform (e.g., https://api.yourplatform.com/v1/auth/oidc/callback)

Understanding OIDC Configuration

The Inference API platform requires the following OIDC configuration parameters for each tenant:

Parameter	Description	Example
OIDCIssuer	The OIDC provider's issuer URL (well-known configuration endpoint)	https://login.microsoftonline.com/{tenant-id}/v2.0
OIDCClientID	The OAuth2 client ID registered with your OIDC provider	00001111-aaaa-2222-bbbb-3333cccc4444
OIDCClientSecret	The OAuth2 client secret (keep this secure)	your-secret-value
OIDCRedirectURL	The callback URL where the provider redirects after authentication	https://api.yourplatform.com/v1/auth/oidc/callback
OIDCScopes	Space-separated list of scopes to request	openid profile email
FrontendURL	Your frontend application URL for token delivery	https://app.yourplatform.com

Finding Your OIDC Issuer URL

The issuer URL is typically found at your provider's well-known OpenID configuration endpoint:

{provider_base_url}/.well-known/openid-configuration

For example:

• Microsoft Entra: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
• Auth0: https://{your-domain}.auth0.com/.well-known/openid-configuration
• JumpCloud: https://sso.jumpcloud.com/sso/.well-known/openid-configuration
• Keycloak: https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration

The issuer URL is usually the base URL without the .well-known/openid-configuration path. For example, if the well-known endpoint is https://login.microsoftonline.com/abc123/v2.0/.well-known/openid-configuration, the issuer URL would be https://login.microsoftonline.com/abc123/v2.0.

General Setup Steps

Step 1: Register Application in OIDC Provider

1. Log in to your OIDC provider's administration console
2. Navigate to Application Registration or App Registration
3. Create a new application or select an existing one
4. Configure the application type (typically "Web Application" or "Confidential Client")

Step 2: Configure Redirect URI

In your OIDC provider, add the callback URL as an allowed redirect URI:

https://api.yourplatform.com/v1/auth/oidc/callback

Important: The redirect URI must:

• Use HTTPS (HTTP is not allowed for security)
• Match exactly (including trailing slashes) with the URL configured in the platform
• Be publicly accessible (not behind a firewall that blocks the OIDC provider)

Step 3: Enable Required Scopes

Ensure your OIDC provider is configured to issue ID tokens and supports the following scopes:

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

Step 4: Configure Response Type

The platform uses the Authorization Code flow with PKCE. Ensure your OIDC provider supports:

• Authorization Code grant type
• PKCE (Proof Key for Code Exchange) with S256 method

Step 5: Obtain Credentials

After registering the application, obtain:

1. Client ID: Usually displayed immediately after registration
2. Client Secret: May need to be generated or revealed (save this securely)
3. Issuer URL: Found in the provider's well-known configuration document

Step 6: Configure Platform

Add the OIDC configuration to your tenant configuration in the platform (see Platform Configuration section below).

Provider-Specific Guides

Microsoft Entra ID (Azure AD)

Microsoft Entra ID (formerly Azure AD) is Microsoft's cloud-based identity and access management service. Reference: Microsoft Entra OIDC Documentation

Step 1: Register Application in Azure Portal

1. Sign in to the Azure Portal
2. Navigate to Microsoft Entra ID > App registrations
3. Click New registration
4. Enter application details:
   • Name: Your application name (e.g., "Inference API Integration")
   • Supported account types: Select based on your needs:
     • Accounts in this organizational directory only: Single tenant
     • Accounts in any organizational directory: Multi-tenant
     • Accounts in any organizational directory and personal Microsoft accounts: Multi-tenant with personal accounts
   • Redirect URI:
     • Platform: Web
     • URI: https://api.yourplatform.com/v1/auth/oidc/callback
5. Click Register

Step 2: Configure Authentication

1. In your app registration, go to Authentication
2. Under Platform configurations, ensure Web platform is added
3. Under Implicit grant and hybrid flows, you do NOT need to enable "ID tokens" (the platform uses authorization code flow, not implicit flow)
4. Under Advanced settings, ensure Allow public client flows is set to No (unless you have specific requirements)

Step 3: Create Client Secret

1. Go to Certificates & secrets
2. Click New client secret
3. Enter a description (e.g., "OIDC Integration Secret")
4. Select expiration period (recommended: 24 months)
5. Click Add
6. Important: Copy the secret value immediately (it will not be shown again)

Step 4: Configure API Permissions (Optional)

1. Go to API permissions
2. The default permissions (openid, profile, email, User.Read) are usually sufficient
3. If you need additional Microsoft Graph permissions, add them here

Step 5: Get Configuration Values

1. Client ID: Found on the Overview page (Application (client) ID)

2. Client Secret: The value you copied in Step 3

3. Issuer URL: Construct based on your tenant:

   • Single tenant: https://login.microsoftonline.com/{tenant-id}/v2.0
   • Multi-tenant (organizations): https://login.microsoftonline.com/organizations/v2.0
   • Multi-tenant (common): https://login.microsoftonline.com/common/v2.0

   To find your tenant ID:

   • Go to Overview page
   • Copy the Directory (tenant) ID

4. Well-Known Configuration: Verify by visiting:

   https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

Step 6: Platform Configuration

Use these values in your platform configuration:

{
  "oidc_issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "oidc_client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "oidc_client_secret": "your-client-secret-value",
  "oidc_redirect_url": "https://api.yourplatform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

Microsoft-Specific Notes:

• The platform automatically discovers endpoints from the well-known configuration
• Microsoft Entra supports PKCE by default
• ID tokens are issued automatically when using authorization code flow with openid scope
• The sub claim in ID tokens is a pairwise identifier (unique per application)

Generic OIDC Provider

For any standard OIDC-compliant provider (Keycloak, Okta, Google Workspace, etc.), follow these general steps:

Step 1: Locate Provider Documentation

Consult your provider's documentation for:

• Application registration process
• OAuth2/OIDC configuration
• Well-known configuration endpoint location

Step 2: Register Application

1. Create a new OAuth2/OIDC application in your provider
2. Application type: Confidential Client or Web Application
3. Grant type: Authorization Code
4. Enable PKCE if supported (recommended)

Step 3: Configure Redirect URI

Add the callback URL:

https://api.yourplatform.com/v1/auth/oidc/callback

Step 4: Get Configuration Values

1. Client ID: From application registration
2. Client Secret: From application registration (generate if needed)
3. Issuer URL: Found in well-known configuration:

   {provider_base_url}/.well-known/openid-configuration

   The issuer URL is typically the base URL without the path

Step 5: Verify Well-Known Configuration

Visit the well-known endpoint and verify it returns valid JSON with:

• issuer: The issuer URL
• authorization_endpoint: Authorization endpoint URL
• token_endpoint: Token endpoint URL
• jwks_uri: JSON Web Key Set endpoint
• userinfo_endpoint: UserInfo endpoint (optional)

Step 6: Platform Configuration

Use these values in your platform configuration:

{
  "oidc_issuer": "https://your-provider.com",
  "oidc_client_id": "your-client-id",
  "oidc_client_secret": "your-client-secret",
  "oidc_redirect_url": "https://api.yourplatform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

Keycloak Example:

{
  "oidc_issuer": "https://keycloak.example.com/realms/your-realm",
  "oidc_client_id": "your-keycloak-client-id",
  "oidc_client_secret": "your-keycloak-client-secret",
  "oidc_redirect_url": "https://api.yourplatform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

Platform Configuration

After obtaining the OIDC configuration values from your provider, configure them in the Inference API platform.

Configuration Format

The OIDC configuration is part of the tenant configuration. Add the following fields to your tenant configuration:

{
  "tenant_id": "your-tenant-id",
  "name": "Your Tenant Name",
  "mongo_uri": "mongodb://...",
  "mongo_database": "your-database",
  "redis_addr": "localhost:6379",
  "redis_db": 0,
  "frontend_url": "https://app.yourplatform.com",
  "oidc_issuer": "https://your-oidc-provider.com",
  "oidc_client_id": "your-client-id",
  "oidc_client_secret": "your-client-secret",
  "oidc_redirect_url": "https://api.yourplatform.com/v1/auth/oidc/callback",
  "oidc_scopes": "openid profile email"
}

Configuration Validation

The platform validates OIDC configuration as follows:

1. If oidc_issuer is provided, the following are required:

   • oidc_client_id (required)
   • oidc_client_secret (required)
   • oidc_redirect_url (required)
   • oidc_scopes (optional, defaults to "openid profile email" if not provided)

2. If oidc_issuer is empty, OIDC is disabled for the tenant (other OIDC fields are ignored)

Environment Variable Configuration

If using environment variables for configuration, the OIDC fields map as follows:

TENANT_OIDC_ISSUER=https://your-oidc-provider.com
TENANT_OIDC_CLIENT_ID=your-client-id
TENANT_OIDC_CLIENT_SECRET=your-client-secret
TENANT_OIDC_REDIRECT_URL=https://api.yourplatform.com/v1/auth/oidc/callback
TENANT_OIDC_SCOPES=openid profile email

Configuration Updates

After updating OIDC configuration:

1. Restart the service: The platform caches OIDC provider configurations in memory. Restart the service to load new configurations.

2. Clear caches: If provider caching causes issues, restart the service to clear the cache.

3. Verify connectivity: Ensure the platform can reach your OIDC provider's endpoints (authorization, token, JWKS).

Testing the Integration

Step 1: Verify Configuration

1. Check well-known endpoint: Visit your provider's well-known configuration endpoint:

   {issuer_url}/.well-known/openid-configuration

   Verify it returns valid JSON.

2. Test provider discovery: The platform automatically discovers endpoints from the well-known configuration. Check logs for any discovery errors.

Step 2: Test Login Flow

1. Initiate login: Send a POST request to initiate OIDC login:

   curl -X POST https://api.yourplatform.com/v1/auth/oidc/login \
     -H "Content-Type: application/json" \
     -d '{"tenant_id": "your-tenant-id"}'

2. Verify response: You should receive an auth_url in the response:

   {
     "auth_url": "https://your-oidc-provider.com/authorize?..."
   }

3. Test authorization: Open the auth_url in a browser and verify:

   • You are redirected to your OIDC provider
   • The login page appears correctly
   • You can authenticate with valid credentials

4. Test callback: After authentication:

   • You should be redirected to the callback URL
   • The callback should process successfully
   • You should be redirected to your frontend with a token in the URL fragment

Step 3: Verify Token

1. Extract token: Extract the token from the URL fragment after successful authentication
2. Test API request: Use the token in an API request:

   curl -X GET https://api.yourplatform.com/v1/some-endpoint \
     -H "Authorization: Bearer {token}"

3. Verify user context: Check that the request context includes:
   • Correct user ID (from OIDC sub claim)
   • Correct tenant ID
   • IsSSO: true flag
   • User email and name (if available)

Step 4: Test Error Scenarios

Test common error scenarios:

1. Invalid credentials: Attempt login with invalid credentials (should fail at provider)
2. Expired state: Wait for state to expire (10 minutes) and attempt callback (should fail)
3. Invalid redirect URI: Temporarily change redirect URI in provider (should fail)
4. Missing scopes: Remove required scopes (should fail or return incomplete token)

External References

• Microsoft Entra OIDC Documentation
• Auth0 OIDC Documentation
• JumpCloud OIDC Support
• OpenID Connect Core 1.0 Specification