OIDC Single Sign-On (SSO) Setup

Configure OIDC SSO in OpsKnight for common identity providers.

Prerequisites

OpsKnight admin access
An IdP OIDC app registration created
A stable base URL for OpsKnight (used for redirect/callback)
ENCRYPTION_KEY configured (required to store client secrets)

Callback URL

Configure this callback URL in your identity provider:

https://YOUR_OPSKNIGHT_URL/api/auth/callback/oidc

Replace YOUR_OPSKNIGHT_URL with your OpsKnight instance URL.

Configuration Fields

Field	Required	Description
Issuer URL	Yes	The OIDC issuer URL for your provider
Client ID	Yes	From your IdP app
Client Secret	Yes	From your IdP app (stored encrypted)
Custom Scopes	No	Additional scopes beyond default
Auto-provision	No	Create users on first login
Allowed Domains	No	Email domain allowlist
Role Mapping	No	Map IdP claims to roles
Profile Mapping	No	Map IdP claims to user fields
Provider Label	No	Custom text for SSO button

Default Scopes: openid email profile

OpsKnight Setup Steps

Go to Settings → System Settings → Single Sign-On (OIDC)
Enable SSO
Enter Issuer URL, Client ID, Client Secret
Configure optional settings:
- Custom scopes
- Allowed domains
- Auto-provision
- Role mapping
- Profile mapping
Save
Test with the SSO button on the login page

Supported Providers

OpsKnight auto-detects provider type from the issuer URL:

Provider	Detection
Google	`accounts.google.com` in issuer
Microsoft	`login.microsoftonline.com` in issuer
Okta	`okta` in issuer
Auth0	`auth0` in issuer
Custom	All other issuers

Provider Guides

Google Workspace

Create an OAuth app in Google Cloud Console
Configure OAuth consent screen
Create OAuth client credentials (Web application)
Authorized redirect URI: https://YOUR_OPSKNIGHT_URL/api/auth/callback/oidc
Issuer URL: https://accounts.google.com
Scopes: openid email profile (default)

Profile mapping claims:

avatarUrl: picture
department: Not provided by Google
jobTitle: Not provided by Google

Microsoft Entra ID (Azure AD)

Register an app in Azure Entra ID
Add a Web platform redirect URI: https://YOUR_OPSKNIGHT_URL/api/auth/callback/oidc
Create a client secret
Issuer URL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
Scopes: openid email profile (default)
Optional: Add email and profile claims if not present

Profile mapping claims:

department: department
jobTitle: jobTitle
avatarUrl: picture

Okta

Create an OIDC Web App integration
Sign-in redirect URI: https://YOUR_OPSKNIGHT_URL/api/auth/callback/oidc
Issuer URL: https://YOUR_OKTA_DOMAIN/oauth2/default
Scopes: openid email profile (default)

Profile mapping claims:

department: department
jobTitle: title
avatarUrl: picture

Auth0

Create a Regular Web Application
Allowed Callback URLs: https://YOUR_OPSKNIGHT_URL/api/auth/callback/oidc
Issuer URL: https://YOUR_AUTH0_DOMAIN
Scopes: openid email profile (default)

Profile mapping claims:

department: Use custom claim, e.g., https://example.com/department
jobTitle: Use custom claim, e.g., https://example.com/title
avatarUrl: picture

Keycloak

Create a Realm and Client (OpenID Connect)
Client Access Type: Confidential
Valid Redirect URIs: https://YOUR_OPSKNIGHT_URL/api/auth/callback/oidc
Issuer URL: https://YOUR_KEYCLOAK_HOST/realms/YOUR_REALM
Scopes: openid email profile (default)

Profile mapping claims:

department: department
jobTitle: jobTitle
avatarUrl: picture

Role Mapping

Map IdP claims to OpsKnight roles automatically.

Format

JSON array of rules:

[
  { "claim": "groups", "value": "admins", "role": "ADMIN" },
  { "claim": "groups", "value": "oncall-team", "role": "RESPONDER" },
  { "claim": "department", "value": "engineering", "role": "RESPONDER" }
]

Rule Fields

Field	Description
`claim`	The IdP claim name to check
`value`	The value to match
`role`	OpsKnight role: `ADMIN`, `RESPONDER`, or `USER`

Evaluation

Rules are evaluated in order
First match wins
Users not matching any rule get the default role (USER)

Profile Mapping

Sync user profile fields from IdP claims.

Supported Fields

OpsKnight Field	Description
`department`	User's department
`jobTitle`	User's job title
`avatarUrl`	Profile picture URL

Format

JSON object mapping OpsKnight fields to IdP claim names:

{
  "department": "department",
  "jobTitle": "title",
  "avatarUrl": "picture"
}

Behavior

Profile fields update on each login
Empty claims don't overwrite existing values

Domain Restrictions

Limit which email domains can use SSO:

In SSO settings, add Allowed Domains
Enter domains (comma-separated): example.com, subsidiary.com
Only users with matching email domains can sign in

If empty, all email domains are allowed.

Auto-Provisioning

Enabled: Users are created automatically on first SSO login.

Disabled: Only pre-existing users can sign in via SSO.

When enabled:

New users get the role from role mapping (or default USER)
Profile fields populated from claims
Email domain must match allowed domains (if configured)

Troubleshooting

SSO Button Not Showing

Verify SSO is enabled in settings
Check ENCRYPTION_KEY environment variable is set
Verify client secret can be decrypted

Validation Fails

Confirm issuer URL uses HTTPS
Verify OIDC discovery document is reachable: {issuer}/.well-known/openid-configuration
Check client ID and secret are correct

Access Denied

Check allowed domains configuration
Verify auto-provision is enabled (for new users)
Ensure IdP sends the email claim

Profile Fields Not Syncing

Confirm claim names in profile mapping match IdP claims
Verify IdP includes the claims in the token
Check IdP token/claims debugger

Missing Email Claim

Ensure your IdP is configured to include the email claim in tokens. Some providers require explicit configuration.

Authentication — All authentication methods
Users — User management
Security Overview — Security best practices

OIDC SSO Setup