Identity Providers

Identity Providers

Configure external identity providers for Single Sign-On (SSO) authentication in Mantis.

Overview

Mantis supports integration with external identity providers (IdPs) using OpenID Connect (OIDC), enabling centralized authentication and automatic user provisioning.

Key Features

Feature	Description
OIDC Support	Standard OpenID Connect 1.0 protocol
Auto-Discovery	Automatic endpoint discovery via .well-known
User Provisioning	Auto-create users on first SSO login
Role Mapping	Map IdP groups to Mantis roles
Multi-Tenant	Tenant-specific identity providers
PKCE	Secure authorization code flow with S256

Supported Providers

All OIDC-compatible providers are supported:

Provider	Status	Notes
Okta	✓ Supported	Full OIDC support
Azure AD	✓ Supported	Microsoft Entra ID
Keycloak	✓ Supported	Open source IdP
Auth0	✓ Supported	Developer-friendly
Google	✓ Supported	Google Workspace
OneLogin	✓ Supported	HR integration
Ping Identity	✓ Supported	Enterprise IdP
Custom OIDC	✓ Supported	Any OIDC provider

Architecture

Authentication Flow

Security Mechanisms

Mechanism	Purpose
PKCE (S256)	Prevents authorization code interception
State Parameter	CSRF protection
Nonce	Replay attack prevention
ID Token Validation	Signature, issuer, audience verification
Encrypted Secrets	Client secrets encrypted at rest

Component Integration

Provider Configuration Model

Field	Type	Description
id	UUID	Unique identifier
name	String	Display name (unique)
provider_type	Enum	Always oidc
issuer_url	URL	OIDC issuer URL
client_id	String	OAuth client ID
client_secret_encrypted	String	Encrypted client secret
discovery_url	URL	Optional custom discovery URL
scopes	Array	OAuth scopes to request
is_enabled	Boolean	Provider enabled status
auto_create_users	Boolean	Auto-provision on first login
default_role_id	UUID	Default role for new users
tenant_id	UUID	Optional tenant scope

Claim Configuration

Field	Default	Description
groups_claim	groups	Claim containing user groups
username_claim	preferred_username	Claim for username
email_claim	email	Claim for email address

Advanced Settings

Field	Default	Description
token_endpoint_auth_method	client_secret_basic	Token endpoint auth
role_sync_mode	additive	How to sync roles from groups
end_session_endpoint	NULL (manual only)	Logout endpoint

Quick Start

1. Register Application with IdP

Register a new OIDC application with your identity provider:

Setting	Value
Sign-in redirect URI	https://your-mantis.com/api/v1/auth/oidc/callback
Sign-out redirect URI	https://your-mantis.com
Grant type	Authorization Code
PKCE	Required (S256)

2. Create Provider in Mantis

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Corporate Okta",
        "provider_type": "oidc",
        "issuer_url": "https://company.okta.com",
        "client_id": "0oa1234567890abcdef",
        "client_secret": "your-client-secret",
        "auto_create_users": true,
        "default_role_id": "role_operator_id"
    }' \
    "https://api.mantis.local/api/v1/admin/identity-providers"

3. Test Connection

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"

4. Enable Provider

The provider is enabled by default. Users can now login via SSO.

API Overview

Endpoint	Method	Description
/api/v1/admin/identity-providers	GET	List providers
/api/v1/admin/identity-providers	POST	Create provider
/api/v1/admin/identity-providers/{id}	GET	Get provider details
/api/v1/admin/identity-providers/{id}	PUT	Update provider
/api/v1/admin/identity-providers/{id}	DELETE	Delete provider
/api/v1/admin/identity-providers/{id}/test	POST	Test connection
/api/v1/admin/identity-providers/discover	POST	Discover endpoints
/api/v1/auth/oidc/providers	GET	List enabled providers (public)
/api/v1/auth/oidc/{provider_id}/login	POST	Initiate SSO login
/api/v1/auth/oidc/callback	GET	Handle SSO callback

Permissions

Action	Required Permission
View providers	settings:read
Create provider	settings:manage
Update provider	settings:manage
Delete provider	settings:manage
Test connection	settings:read

Database Schema

CREATE TABLE identity_providers (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL UNIQUE,
    provider_type TEXT NOT NULL,
    issuer_url TEXT NOT NULL,
    client_id TEXT NOT NULL,
    client_secret_encrypted TEXT NOT NULL,
    discovery_url TEXT,
    authorization_endpoint TEXT,
    token_endpoint TEXT,
    userinfo_endpoint TEXT,
    jwks_uri TEXT,
    scopes TEXT[] NOT NULL DEFAULT '{openid,profile,email}',
    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    auto_create_users BOOLEAN NOT NULL DEFAULT FALSE,
    default_role_id UUID REFERENCES roles(id) ON DELETE SET NULL,
    tenant_id UUID REFERENCES tenants(id) ON DELETE CASCADE,
    trust_unverified_email BOOLEAN NOT NULL DEFAULT FALSE,
    groups_claim TEXT NOT NULL DEFAULT 'groups',
    username_claim TEXT NOT NULL DEFAULT 'preferred_username',
    email_claim TEXT NOT NULL DEFAULT 'email',
    end_session_endpoint TEXT,
    token_endpoint_auth_method TEXT NOT NULL DEFAULT 'client_secret_basic',
    role_sync_mode TEXT NOT NULL DEFAULT 'additive',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP
);

Best Practices

Security

1. Use HTTPS - Always use TLS for callback URLs
2. Enable PKCE - Required for public clients
3. Minimal scopes - Request only needed scopes
4. Regular rotation - Rotate client secrets periodically

User Management

1. Enable auto-provisioning - Reduces admin overhead
2. Set default roles - Appropriate access for new users
3. Configure role mappings - Sync roles from IdP groups
4. Review external identities - Audit linked accounts

Multi-Tenancy

1. Tenant-specific IdPs - Isolate customer authentication
2. System-wide IdPs - For platform administrators
3. Consistent naming - Clear provider identification

Next Steps

• OIDC Configuration - Detailed provider setup
• SSO Setup - Authentication flow configuration
• Role Mappings - Map IdP groups to roles
• External Identities - Manage linked accounts