OIDC Configuration

OIDC Configuration

Configure OpenID Connect (OIDC) identity providers for enterprise Single Sign-On.

Overview

Mantis uses OIDC 1.0 with Authorization Code flow and PKCE for secure authentication with external identity providers.

Creating an Identity Provider

API Request

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Okta Production",
        "provider_type": "oidc",
        "issuer_url": "https://company.okta.com",
        "client_id": "0oa1234567890abcdef",
        "client_secret": "your-client-secret-here",
        "scopes": ["openid", "profile", "email", "groups"],
        "auto_create_users": true,
        "default_role_id": "019b937d-d9f3-8b6d-a625-c5fa41cd3c10"
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

Request Fields

Field	Required	Description
name	Yes	Unique display name
provider_type	Yes	Must be "oidc"
issuer_url	Yes	OIDC issuer URL
client_id	Yes	OAuth client ID
client_secret	Yes	OAuth client secret
scopes	No	OAuth scopes (default: openid, profile, email)
auto_create_users	No	Auto-provision users (default: false)
default_role_id	No	Default role for new users

Response

{
  "id": "019b937d-b899-8fa4-a6ce-aa778362a062",
  "name": "Okta Production",
  "provider_type": "oidc",
  "issuer_url": "https://company.okta.com",
  "client_id": "0oa1234567890abcdef",
  "discovery_url": "https://company.okta.com/.well-known/openid-configuration",
  "endpoints": {},
  "scopes": ["openid", "profile", "email", "groups"],
  "is_enabled": true,
  "auto_create_users": true,
  "default_role_id": "019b937d-d9f3-8b6d-a625-c5fa41cd3c10",
  "default_role_name": "operator",
  "user_count": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": null
}

At create time all four endpoint columns are stored as null — discovery runs lazily on the first login, not on create, so the endpoints are populated only after the provider is first used. Each unset endpoint is omitted from the JSON rather than rendered as null, so endpoints comes back empty; treat a missing key as “not discovered yet”.

Provider-Specific Setup

Okta

1. Create Application in Okta Admin Console:

   • Applications → Create App Integration
   • Sign-in method: OIDC
   • Application type: Web Application

2. Configure Settings:

   Sign-in redirect URIs: https://your-mantis.com/api/v1/auth/oidc/callback
   Sign-out redirect URIs: https://your-mantis.com
   Controlled access: Limit access to selected groups

3. Enable PKCE (required):

   • General → Edit
   • Proof Key for Code Exchange (PKCE): Require PKCE

4. Add Groups Claim:

   • Sign On → Edit OpenID Connect ID Token
   • Groups claim type: Filter
   • Groups claim filter: groups Matches regex .*

# Create Okta provider
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Okta",
        "provider_type": "oidc",
        "issuer_url": "https://dev-123456.okta.com",
        "client_id": "0oa...",
        "client_secret": "...",
        "scopes": ["openid", "profile", "email", "groups"],
        "auto_create_users": true
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

Azure AD (Microsoft Entra ID)

1. Register Application in Azure Portal:

   • App registrations → New registration
   • Supported account types: Single tenant or Multi-tenant
   • Redirect URI: Web → https://your-mantis.com/api/v1/auth/oidc/callback

2. Configure Authentication:

   • Authentication → Platform configurations → Web
   • Implicit grant: Disable
   • Allow public client flows: No

3. Create Client Secret:

   • Certificates & secrets → New client secret
   • Note the secret value immediately

4. API Permissions:

   • API permissions → Add permission → Microsoft Graph
   • Delegated: openid, profile, email, User.Read

5. Token Configuration (for groups):

   • Token configuration → Add groups claim
   • Select: Security groups / All groups

# Create Azure AD provider
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Azure AD",
        "provider_type": "oidc",
        "issuer_url": "https://login.microsoftonline.com/{tenant-id}/v2.0",
        "client_id": "your-application-id",
        "client_secret": "your-client-secret",
        "scopes": ["openid", "profile", "email"],
        "auto_create_users": true
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

Note

Azure AD uses {tenant-id} in the issuer URL. Replace with your actual tenant ID.

Keycloak

1. Create Client in Keycloak Admin Console:

   • Clients → Create client
   • Client ID: mantis
   • Client Protocol: openid-connect

2. Configure Client:

   Access Type: confidential
   Standard Flow Enabled: ON
   Direct Access Grants: OFF
   Valid Redirect URIs: https://your-mantis.com/api/v1/auth/oidc/callback

3. Get Client Secret:

   • Credentials tab → Copy client secret

4. Configure Mappers (for groups):

   • Mappers → Create
   • Name: groups
   • Mapper Type: Group Membership
   • Token Claim Name: groups
   • Add to ID token: ON

# Create Keycloak provider
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Keycloak",
        "provider_type": "oidc",
        "issuer_url": "https://keycloak.example.com/realms/your-realm",
        "client_id": "mantis",
        "client_secret": "your-client-secret",
        "scopes": ["openid", "profile", "email", "groups"],
        "auto_create_users": true
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

Auth0

1. Create Application in Auth0 Dashboard:

   • Applications → Create Application
   • Application Type: Regular Web Applications

2. Configure Settings:

   Allowed Callback URLs: https://your-mantis.com/api/v1/auth/oidc/callback
   Allowed Logout URLs: https://your-mantis.com
   Allowed Web Origins: https://your-mantis.com

3. Enable Connections:

   • Connections → Enable database/social connections

# Create Auth0 provider
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Auth0",
        "provider_type": "oidc",
        "issuer_url": "https://your-tenant.auth0.com",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "scopes": ["openid", "profile", "email"],
        "auto_create_users": true
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

Google Workspace

1. Create OAuth Client in Google Cloud Console:

   • APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Web application

2. Configure Redirect URIs:

   Authorized redirect URIs: https://your-mantis.com/api/v1/auth/oidc/callback

# Create Google provider
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Google Workspace",
        "provider_type": "oidc",
        "issuer_url": "https://accounts.google.com",
        "client_id": "123456789.apps.googleusercontent.com",
        "client_secret": "your-client-secret",
        "scopes": ["openid", "profile", "email"],
        "auto_create_users": true
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

Claim Configuration

Common Claim Mappings

Provider	Groups	Username	Email
Okta	groups	preferred_username	email
Azure AD	groups	preferred_username	email
Keycloak	groups	preferred_username	email
Auth0	https://your-app/roles	nickname	email
Google	N/A	email	email

Groups Claim Example

ID token with groups:

{
  "iss": "https://company.okta.com",
  "sub": "00u1234567890",
  "aud": "0oa1234567890abcdef",
  "iat": 1704067200,
  "exp": 1704070800,
  "nonce": "abc123",
  "preferred_username": "alice@company.com",
  "email": "alice@company.com",
  "groups": ["Everyone", "Developers", "Mantis-Admins"]
}

Endpoint Discovery

Automatic Discovery

Mantis automatically discovers OIDC endpoints from the issuer URL:

# Discover endpoints before creating provider
curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "discovery_url": "https://company.okta.com"
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers/discover"

Response:

{
  "success": true,
  "endpoints": {
    "authorization_endpoint": "https://company.okta.com/oauth2/v1/authorize",
    "token_endpoint": "https://company.okta.com/oauth2/v1/token",
    "userinfo_endpoint": "https://company.okta.com/oauth2/v1/userinfo",
    "jwks_uri": "https://company.okta.com/oauth2/v1/keys"
  },
  "error": null
}

Discovery is required

Caution

Mantis requires an OIDC provider that serves a standard discovery document. Both the login path and the admin test-connection endpoint fetch it from discovery_url when that field is set, and fall back to <issuer_url>/.well-known/openid-configuration when it is not — so a provider serving its document at a non-canonical URL is configured by setting discovery_url on the create/update request. There is no API field for authorization_endpoint / token_endpoint / jwks_uri, so a provider that serves no discovery document at all cannot be used.

Testing Configuration

Connection Test

Verify the provider configuration is correct:

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}' \
    "https://api.mantis.local/api/v1/admin/identity-providers/$IDP_ID/test"

Response:

{
  "success": true,
  "message": "Connection successful - all endpoints discovered",
  "details": {
    "discovery_reachable": true,
    "authorization_reachable": true,
    "token_reachable": true,
    "jwks_reachable": true,
    "response_time_ms": 125
  }
}

Test Login

After configuration, test the login flow:

1. Navigate to Lens UI login page
2. Click the SSO provider button
3. Authenticate with IdP
4. Verify redirect back to Mantis

Updating Configuration

Update Provider

curl -X PUT \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Okta Production (Updated)",
        "client_secret": "new-client-secret",
        "auto_create_users": false
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers/$IDP_ID"

Enable/Disable Provider

# Disable provider
curl -X PUT \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"is_enabled": false}' \
    "https://api.mantis.local/api/v1/admin/identity-providers/$IDP_ID"

Caution

Disabling a provider prevents all users from logging in via that provider. Existing sessions remain valid until expiration.

Client Secret Rotation

Rotation Process

1. Generate new secret in IdP admin console
2. Update Mantis with new secret:

   curl -X PUT \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"client_secret": "new-rotated-secret"}' \
       "https://api.mantis.local/api/v1/admin/identity-providers/$IDP_ID"

3. Test connection to verify
4. Delete old secret in IdP admin console

Best Practices

• Rotate secrets at least annually
• Use automated rotation where supported
• Monitor for authentication failures after rotation

Deleting Providers

Prerequisites

Before deletion:

• Unlink all users from the provider
• Or migrate users to another provider

# Check linked users
curl -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/identity-providers/$IDP_ID"
# Check user_count field

# Delete provider (fails if users linked)
curl -X DELETE \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/identity-providers/$IDP_ID"

Troubleshooting

Discovery Failed

Error: Failed to fetch OIDC discovery

1. Verify issuer URL is correct
2. Check network connectivity to IdP
3. Verify TLS certificates are valid

Invalid Client

Error: Token exchange failed: invalid_client

1. Verify client ID matches IdP configuration
2. Verify client secret is correct
3. Check token endpoint auth method

Redirect URI Mismatch

Error: The redirect_uri does not match

1. Verify callback URL in IdP matches exactly:

   https://your-mantis.com/api/v1/auth/oidc/callback

2. Check for trailing slashes
3. Verify protocol (http vs https)

Missing Claims

Error: ID token missing email claim

1. Check IdP configuration for claim mapping
2. Verify requested scopes include email
3. Set the claim mapping on the provider if your IdP names the claims differently. POST/PUT /api/v1/admin/identity-providers take a mapping object with username_claim, email_claim, groups_claim, role_sync_mode, token_endpoint_auth_method and provisioning_mode.

Next Steps

• SSO Setup - Complete authentication setup
• Role Mappings - Configure group-to-role mappings
• External Identities - Manage user links