Setting Up OIDC Providers

Overview

Frontier supports OpenID Connect (OIDC) authentication with multiple identity providers. This guide covers configuring the most popular providers:

Google Workspace and Gmail
GitHub
Azure Active Directory / Microsoft Entra ID

OIDC provides secure, standards-based authentication and allows users to sign in with their existing accounts from these providers.

Prerequisites

Before configuring OIDC, ensure you have:

A running Frontier server (see Getting Started)
Admin access to your identity provider
RSA keys generated for JWT signing
A publicly accessible callback URL (or localhost for development)

Understanding OIDC Flow

Here’s how OIDC authentication works with Frontier:

Google OIDC Configuration

Create a Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Note your project ID

Enable Google Identity Platform

In the Google Cloud Console, go to APIs & Services > Library
Search for “Google Identity Platform API” or “Google+ API”
Click Enable

Create OAuth 2.0 Credentials

Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Choose Web application as application type
Configure the OAuth consent screen if prompted:
- Set app name (e.g., “Acme Corp Portal”)
- Add your domain
- Add scopes: email, profile, openid

Configure Authorized Redirect URIs

Add these redirect URIs:For development:

http://localhost:8000/v1beta1/auth/callback

For production:

https://your-domain.com/v1beta1/auth/callback

The callback URL must exactly match what you configure in Frontier. Including or excluding the trailing slash matters.

Save your credentials

After creating the OAuth client, you’ll see:

Client ID: Looks like 123456789-abc.apps.googleusercontent.com
Client Secret: A random string

Copy both values - you’ll need them in your Frontier config.

Update Frontier configuration

Add to your config.yaml:

app:
  authentication:
    callback_urls: 
      - "http://localhost:8000/v1beta1/auth/callback"
    
    oidc_config:
      google:
        client_id: "123456789-abc.apps.googleusercontent.com"
        client_secret: "GOCSPX-your-client-secret"
        issuer_url: "https://accounts.google.com"
        validity: "10m"

Restart Frontier and test

# Restart Frontier
go run main.go server start

Test the authentication flow:

# This redirects to Google login
curl -L http://localhost:8000/v1beta1/auth/google

GitHub OIDC Configuration

Go to GitHub Developer Settings
Click New OAuth App
Fill in the application details:
- Application name: Your app name
- Homepage URL: http://localhost:8000 (dev) or your domain
- Authorization callback URL: http://localhost:8000/v1beta1/auth/callback

Generate a client secret

After creating the app, click Generate a new client secret
Copy the secret immediately (you won’t see it again)
Also copy the Client ID shown on the page

Configure Frontier for GitHub

Add to your config.yaml:

app:
  authentication:
    callback_urls:
      - "http://localhost:8000/v1beta1/auth/callback"
    
    oidc_config:
      github:
        client_id: "Iv1.your_client_id"
        client_secret: "your_client_secret_here"
        issuer_url: "https://github.com/login/oauth"
        validity: "10m"

Test GitHub authentication

curl -L http://localhost:8000/v1beta1/auth/github

This should redirect you to GitHub’s authorization page.

Azure AD / Microsoft Entra ID Configuration

Go to Azure Portal
Navigate to Azure Active Directory (or Microsoft Entra ID)
Go to App registrations > New registration
Fill in:
- Name: Your application name
- Supported account types: Choose based on your needs
  - Single tenant (your org only)
  - Multi-tenant (any Azure AD org)
  - Multi-tenant + personal Microsoft accounts

Configure redirect URI

In Authentication, click Add a platform
Choose Web
Add redirect URI: http://localhost:8000/v1beta1/auth/callback
Under Implicit grant and hybrid flows, select:
- ✓ ID tokens

Create a client secret

Go to Certificates & secrets
Click New client secret
Add a description and set expiration (max 24 months)
Copy the secret Value immediately

Get your tenant and application IDs

From the Overview page, copy:

Application (client) ID: 12345678-1234-1234-1234-123456789abc
Directory (tenant) ID: 87654321-4321-4321-4321-987654321abc

Configure API permissions (optional)

Go to API permissions
Click Add a permission > Microsoft Graph
Add delegated permissions:
- User.Read (basic profile)
- email
- openid
- profile
Click Grant admin consent if required by your organization

Update Frontier configuration

Add to your config.yaml:

app:
  authentication:
    callback_urls:
      - "http://localhost:8000/v1beta1/auth/callback"
    
    oidc_config:
      azure:
        client_id: "12345678-1234-1234-1234-123456789abc"
        client_secret: "your_client_secret_value"
        # For single tenant:
        issuer_url: "https://login.microsoftonline.com/87654321-4321-4321-4321-987654321abc/v2.0"
        # For multi-tenant:
        # issuer_url: "https://login.microsoftonline.com/common/v2.0"
        validity: "10m"

For multi-tenant apps, replace the tenant ID in the issuer URL with common or organizations.

Test Azure AD authentication

curl -L http://localhost:8000/v1beta1/auth/azure

Multiple Providers Configuration

You can enable multiple OIDC providers simultaneously:

config.yaml

app:
  authentication:
    callback_urls:
      - "http://localhost:8000/v1beta1/auth/callback"
    
    oidc_config:
      google:
        client_id: "google-client-id"
        client_secret: "google-secret"
        issuer_url: "https://accounts.google.com"
      
      github:
        client_id: "github-client-id"
        client_secret: "github-secret"
        issuer_url: "https://github.com/login/oauth"
      
      azure:
        client_id: "azure-client-id"
        client_secret: "azure-secret"
        issuer_url: "https://login.microsoftonline.com/{tenant}/v2.0"

Each provider will be available at:

/v1beta1/auth/google
/v1beta1/auth/github
/v1beta1/auth/azure

Custom OIDC Provider

Frontier supports any standard OIDC-compliant provider:

app:
  authentication:
    oidc_config:
      custom:
        client_id: "your-client-id"
        client_secret: "your-client-secret"
        issuer_url: "https://your-provider.com"
        validity: "10m"

What is the issuer URL?

The issuer URL is the base URL of your OIDC provider. Frontier will automatically discover:

Authorization endpoint
Token endpoint
User info endpoint
JWKS (public keys) endpoint

By appending /.well-known/openid-configuration to the issuer URL.

Testing Your OIDC Configuration

# Initiate authentication flow
curl -L http://localhost:8000/v1beta1/auth/google

# This should redirect you to Google's login page

Session Management

After successful OIDC authentication, Frontier:

Creates or updates the user in the database
Sets a secure session cookie (if session is configured)
Generates a JWT token (if token is configured)
Redirects to your application with the session

Configure session settings:

app:
  authentication:
    session:
      hash_secret_key: "hash-secret-should-be-32-chars--"
      block_secret_key: "block-secret-should-be-32-chars-"
      domain: "your-domain.com"
      same_site: "lax"  # lax, strict, or none
      secure: true      # set to true in production (requires HTTPS)
      validity: "720h"   # 30 days

Advanced Configuration

Custom Claims Mapping

Extract additional claims from the OIDC provider:

app:
  authentication:
    token:
      claims:
        add_org_ids: true
        add_user_email: true

Organization Domain Verification

Restrict sign-ups to verified email domains:

# Add a verified domain to an organization
curl -X POST http://localhost:8000/v1beta1/organizations/{org_id}/domains \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com",
    "auto_join": true
  }'

Now users with @acme.com emails automatically join the organization on first login.

Multiple Callback URLs

Support different environments:

app:
  authentication:
    callback_urls:
      - "http://localhost:8000/v1beta1/auth/callback"
      - "https://staging.your-domain.com/v1beta1/auth/callback"
      - "https://your-domain.com/v1beta1/auth/callback"

The first URL is used by default. Override with ?callback_url parameter.

Troubleshooting

Redirect URI mismatch error

Error: redirect_uri_mismatch from Google/GitHub/AzureSolution:

Check that the callback URL in your provider settings exactly matches the URL in Frontier config
Don’t forget /v1beta1/auth/callback path
Ensure http:// vs https:// matches
Check for trailing slashes

Invalid client error

Error: invalid_client or unauthorized_clientSolution:

Verify the client ID is correct
Check that the client secret hasn’t expired (Azure AD)
Ensure the OAuth app is enabled
For Azure, verify you’re using the Application ID, not Object ID

User created but can't access resources

Issue: User logs in successfully but has no permissionsSolution: Users created via OIDC have no roles by default. You must:

Assign them to organizations
Give them roles in those organizations
Or configure domain auto-join with default roles

Session cookie not being set

Token expired errors

Issue: Authentication works but expires immediatelySolution: Increase the validity period:

oidc_config:
  google:
    validity: "30m"  # Increase from default 10m

Security Best Practices

Production Checklist:

✅ Use HTTPS for all callback URLs
✅ Set session.secure: true
✅ Use strong, random session secrets (32+ characters)
✅ Rotate client secrets regularly
✅ Restrict authorized redirect URIs to known domains
✅ Enable CORS only for trusted origins
✅ Monitor authentication logs for suspicious activity
✅ Implement rate limiting on auth endpoints

Development vs Production:For development, you can use http://localhost URLs. For production:

Always use HTTPS
Configure proper CORS settings
Use environment-specific callback URLs
Store secrets in environment variables or secret managers

Next Steps

Organization Domains

Configure domain verification and auto-join

Session Management

Deep dive into session configuration

User Management

Learn about user lifecycle and metadata

Admin Portal

Manage authentication settings via UI

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

Setting Up OIDC Providers

Overview

Prerequisites

Understanding OIDC Flow

Google OIDC Configuration

GitHub OIDC Configuration

Azure AD / Microsoft Entra ID Configuration

Multiple Providers Configuration

Custom OIDC Provider

Testing Your OIDC Configuration

Session Management

Advanced Configuration

Custom Claims Mapping

Organization Domain Verification

Multiple Callback URLs

Troubleshooting

Security Best Practices

Next Steps

Organization Domains

Session Management

User Management

Admin Portal

Build docs developers (and LLMs) love

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Overview

​Prerequisites

​Understanding OIDC Flow

​Google OIDC Configuration

​GitHub OIDC Configuration

​Azure AD / Microsoft Entra ID Configuration

​Multiple Providers Configuration

​Custom OIDC Provider

​Testing Your OIDC Configuration

​Session Management

​Advanced Configuration

​Custom Claims Mapping

​Organization Domain Verification

​Multiple Callback URLs

​Troubleshooting

​Security Best Practices

​Next Steps

Organization Domains

Session Management

User Management

Admin Portal

Build docs developers (and LLMs) love

Overview

Prerequisites

Understanding OIDC Flow

Google OIDC Configuration

GitHub OIDC Configuration

Azure AD / Microsoft Entra ID Configuration

Multiple Providers Configuration

Custom OIDC Provider

Testing Your OIDC Configuration

Session Management

Advanced Configuration

Custom Claims Mapping

Organization Domain Verification

Multiple Callback URLs

Troubleshooting

Security Best Practices

Next Steps