Overview
Custom OIDC authentication enables integration with any OpenID Connect (OIDC) compliant identity provider such as Keycloak, Authentik, PingIdentity, or other enterprise identity solutions.Configure Custom OIDC SSO
Complete the following steps to configure Custom OIDC SSO.-
Navigate to Settings > SSO.

- Click Custom-OIDC, and then click Configure.
- Enter the configuration details. For more information, see Configuration Fields.
- Click Test Login and complete the sign-in. For more information, see Test Login.
- Click Save to finish the SSO configuration.
Configuration Fields
This section lists all fields in the order they appear in the OpenMetadata SSO configuration form.General Configuration
Configure the identity provider connection and basic authentication behavior.Provider Name
- Definition: A human-readable name for this OIDC configuration instance.
- Example:
Company SSO,Internal Auth,Keycloak SSO - Why it matters: Helps identify this SSO configuration in logs and user interfaces.
- Note: This is a display name and doesn’t affect authentication functionality.
Enable Self Signup
- Definition: Allows new users to create OpenMetadata accounts through OIDC authentication.
- Default:
false - Why it matters: Controls whether unknown users can automatically create accounts.
- Note: Enable only if you trust all users from your OIDC provider.
Authority
- Definition: Base URL of your OIDC provider’s authentication server.
- Example:
https://auth.yourcompany.comorhttps://keycloak.company.com/realms/your-realm - Why it matters: OpenMetadata uses this to discover OIDC endpoints and validate tokens.
- Note: Must be publicly accessible and return a valid OIDC discovery document at
/.well-known/openid-configuration.
Public Key Urls
- Definition: URLs pointing to the OIDC provider’s public keys used to verify token signatures.
- Example:
https://auth.yourcompany.com/oauth2/v3/certs - Why it matters: OpenMetadata fetches public keys from these URLs to validate JSON Web Token (JWT) signatures from your provider.
- Note: Enter each URL and press Enter. Leave empty to use keys from the discovery document.
Token Validation Algorithm
- Definition: Algorithm used to validate JWT token signatures from the OIDC provider.
- Default:
RS256 - Options:
RS256,RS384,RS512,HS256,HS384,HS512 - Example:
RS256 - Why it matters: Must match the signing algorithm configured in your OIDC provider.
OIDC Configuration
Configure the OIDC client credentials, discovery endpoint, and token behavior.Id
- Definition: OAuth2 client identifier issued by your OIDC provider.
- Example:
my-custom-oidc-client-12345 - Why it matters: Identifies your application to the OIDC provider.
- Note: Found in your OIDC provider’s application settings.
Secret
- Definition: OAuth2 client secret issued by your OIDC provider.
- Example:
abc123-secret-xyz789 - Why it matters: Authenticates your application with the OIDC provider.
- Note: Keep this value secure. Never expose it in client-side code.
Scope
- Definition: OAuth2 scopes to request from the OIDC provider.
- Default:
openid profile email - Example:
openid profile email groups - Why it matters: Determines what user information OpenMetadata can access.
- Note:
openid: Required for OIDC.profile: Access to user profile information.email: Access to user email address.groups: Access to user group memberships (if supported by your provider).offline_access: Needed for a confidential client so the provider issues a refresh token (Okta, Microsoft Entra ID, Auth0). Google issues a refresh token only when the user sees its consent screen. Without a refresh token, the user signs in again each time the ID token expires.
DiscoveryUri
- Definition: Your OIDC provider’s OpenID Connect metadata endpoint.
- Example:
https://auth.yourcompany.com/.well-known/openid-configuration - Why it matters: Allows OpenMetadata to automatically discover the provider’s OIDC endpoints.
- Note: Usually
{authority}/.well-known/openid-configuration.
PreferredJwsAlgorithm
- Definition: Preferred JSON Web Signature algorithm for token validation.
- Default:
RS256 - Example:
RS256 - Why it matters: Specifies the preferred algorithm when the provider supports multiple signing options.
- Note: Must match the algorithm your OIDC provider uses to sign tokens.
ResponseType
- Definition: OAuth2 response type for the authorization flow.
- Default:
code - Options:
code,token,id_token - Example:
code - Why it matters: Determines which OAuth2 flow is used. Authorization Code flow (
code) is the most secure.
ClientAuthenticationMethod
- Definition: Method used to authenticate the client with the OIDC provider.
- Default:
client_secret_post - Options:
client_secret_basic|client_secret_post|client_secret_jwt|private_key_jwt - Example:
client_secret_post - Why it matters: Must match the client authentication method configured in your OIDC provider.
Tenant
- Definition: Tenant identifier if your OIDC provider supports multi-tenancy.
- Example:
your-tenant-idorcompany-realm - Why it matters: Identifies the specific tenant or realm within a multi-tenant OIDC provider.
- Note: Leave empty if your provider is single-tenant.
ServerUrl
- Definition: Base URL of your OpenMetadata deployment.
- Example:
https://openmetadata.company.com - Why it matters: Used internally to construct redirect URLs.
- Note: This field is read-only: it is auto-populated based on your OpenMetadata deployment URL.
CallbackUrl
- Definition: URL where the OIDC provider redirects after authentication.
- Example:
https://openmetadata.company.com/callback - Why it matters: Must be registered in your OIDC provider configuration.
- Note:
- This field is read-only: it is auto-populated as
{your-domain}/callback. - Copy this URL and add it to your OIDC provider’s allowed redirect URIs list.
- This field is read-only: it is auto-populated as
Prompt
- Definition: Controls the OIDC provider’s authentication prompt behavior.
- Options:
none,login,consent,select_account - Default: Empty. Leave it empty unless you need to force a specific behavior. OpenMetadata sends
noneitself when it re-authenticates a user silently. - Example:
login - Why it matters: Defines how the login experience behaves for users.
- Note:
login: Always prompt for credentials.none: Use existing session silently (SSO).consent: Prompt for permissions.
Advanced Configuration
The following fields are grouped under Advanced Config in the UI (collapsed by default):UseNonce
- Definition: Security feature to prevent replay attacks in OIDC flows.
- Default:
false - Why it matters: Enhances security by ensuring each authentication request is unique.
disablePkce
- Definition: Whether to disable Proof Key for Code Exchange.
- Default:
false - Why it matters: PKCE adds security to the authorization code flow.
- Note: Should remain
false(enabled) in most cases.
MaxClockSkew
- Definition: Maximum allowed time difference in seconds between systems when validating tokens.
- Default:
0 - Why it matters: Prevents token validation failures due to minor clock differences between servers.
MaxAge
- Definition: The
max_agerequest parameter, in seconds, that OpenMetadata sends to the identity provider. - Default: Empty.
- Why it matters: Leave it empty so the identity provider can reuse its own session. A value of
0is treated as not set. To force users to re-enter their credentials, set Prompt tologin.
OIDC Session Expiry
- Definition: How long user sessions remain valid in seconds.
- Default:
604800(7 days) - Why it matters: Controls session timeout for confidential clients.
Session Expiry
- Definition: How long an authenticated session remains valid across all authentication providers, in seconds.
- Default: Empty. OpenMetadata then uses OIDC Session Expiry when it is set, and otherwise
604800. - Why it matters: The minimum is
3600seconds.
Max Active Sessions Per User
- Definition: The maximum number of active authenticated sessions each user can have.
- Default:
5 - Why it matters: When a user exceeds the limit, OpenMetadata revokes the least recently used sessions.
JWT Claims
Map identity token claims to OpenMetadata user identities and team assignments.Jwt Principal Claims
- Definition: JWT claims used to identify users in OpenMetadata. The first claim that returns a value is used.
- Default:
["email", "preferred_username", "sub"] - Example:
["email", "username", "sub"] - Why it matters: Determines how users are matched to their OpenMetadata accounts.
- Note: At least one claim must correspond to the user’s email address.
Jwt Principal Claims Mapping
Definition: Maps JSON Web Token (JWT) claims to OpenMetadata user profile fields. Supported keys: Onlyemail and username are valid mapping targets in jwtPrincipalClaimsMapping.
Example:
openmetadata_field:jwt_claim (for example, "email:email").
Note: The display name is derived automatically from standard OIDC/JWT claims, so you don’t need to configure it using
jwtPrincipalClaimsMapping. If you need richer name handling, make sure your OIDC provider is configured to include given_name and family_name as claims in the ID token. OpenMetadata picks them up automatically.Email Claim
- Definition: The claim in the sign-in token that contains the user’s email address. When set, OpenMetadata resolves the user by email address. If you set Jwt Principal Claims Mapping, the mapping wins. Email Claim applies only when the mapping is empty.
- Example:
email,upn - Why it matters: OpenMetadata identifies the user by email address.
- Note:
- If the claim is missing or invalid, OpenMetadata falls back to Jwt Principal Claims. If that has no values, sign-in fails.
- The claim must be present in the ID token that the identity provider issues.
Display Name Claim
- Definition: The claim in the sign-in token that contains the user’s display name.
- Example:
name - Why it matters: OpenMetadata uses this field only when Email Claim is set, and the provider’s name replaces the stored display name on every sign-in.
- Note: If you leave it empty, OpenMetadata reads the standard name claims:
name,displayName, or the first and last name.

Jwt Team Claim Mapping
- Definition: JWT claim containing team or department information for automatic team assignment in OpenMetadata.
- Example:
department,groups,organization,team - Why it matters: Automatically assigns users to existing OpenMetadata teams based on their OIDC provider attributes at login.
- Note:
- Ensure the claim is included in the ID token by your OIDC provider.
- Common attributes:
department,organization,groups,roles. - The team must already exist in OpenMetadata for assignment to work.
- Only teams of type Group can be auto-assigned. Team names are case-sensitive.
Enable Auto Redirect
- Definition: Automatically redirects users to the OIDC Identity Provider without showing the OpenMetadata login page.
- Default:
false - Why it matters: Provides a seamless SSO experience: users already authenticated with the IdP are logged in automatically.
- Note: Disable if you need users to be able to choose between SSO and other login methods.
Authorizer Configuration
Control which users and domains are permitted to access OpenMetadata.Admin Principals
- Definition: Users granted admin access in OpenMetadata.
- Example:
["admin", "sysadmin", "john.doe"] - Why it matters: Grants full admin privileges in OpenMetadata.
- Note: Enter usernames only, not email addresses. Use the part of the email before
@(for example, foradmin@company.com, enteradmin).
Principal Domain
- Definition: Default domain appended to usernames when the domain is not present in claims.
- Example:
company.com - Why it matters: Ensures consistent user identification across systems.
- Note: Optional: only needed if usernames don’t include domain information.
- Deprecated: Use Allowed Email Domains for domain restrictions.
Enforce Principal Domain
- Definition: Restricts login to users belonging to the configured Principal Domain.
- Default:
false - Example:
true - Why it matters: Adds an extra layer of security by limiting access to a specific domain.
- Deprecated: Use Allowed Email Domains instead.
Enable Secure Socket Connection
- Definition: Enables Secure Sockets Layer/Transport Layer Security (SSL/TLS) for all SSO communication.
- Default:
false - Example:
true - Why it matters: Ensures encrypted communication between OpenMetadata and your OIDC provider.
- Note: Recommended in production environments.
Allowed Email Domains
- Definition: The email domains that users must belong to in order to sign in to OpenMetadata.
- Example:
["company.com"] - Why it matters: Restricts which email domains can sign in. When set, it replaces Allowed Domains and Enforce Principal Domain, which are deprecated.
- Note: OpenMetadata rejects creating a user outside these domains. The check is skipped for bots and for
basicandopenmetadataauthentication.

Allowed Email Registration Domains
- Definition: Domains allowed to register new accounts via SSO self-signup.
- Example:
company.com - Why it matters: Restricts which email domains can create new OpenMetadata accounts through self-signup.
- Note: Use
"all"to allow any domain. Leave empty to block all self-signup registrations. Requires Enable Self Signup to be active.
Allowed Domains
- Definition: List of email domains permitted to authenticate with OpenMetadata.
- Example:
["company.com", "external-partner.com"] - Why it matters: Provides fine-grained control over which email domains can authenticate via your OIDC provider.
- Note:
- Works in conjunction with Enforce Principal Domain.
- Leave empty if you only use a single domain configured in Principal Domain.
- Deprecated: Use Allowed Email Domains instead.
Use Roles From Provider
- Definition: Use roles returned by the OIDC provider in the token to assign OpenMetadata roles.
- Default:
false - Why it matters: Enables role-based access control driven by your provider’s role assignments.
- Note: Roles must be included in the token and must match existing OpenMetadata role names.
- Roles sync on every login. A role change at the provider takes effect the next time the user signs in.
- If the token omits the roles claim entirely, OpenMetadata treats it as no roles. Some providers leave the claim out once a user’s last role is removed.
- A fresh sign-in then removes the roles and administrator access that the provider no longer grants.
- Roles from the provider can promote a user to Admin. A sign-in never demotes an admin assigned through Admin Principals.
Default OAuth Role
- Definition: Default role assigned to new users when they first sign in via SSO self-signup.
- Example:
DataConsumer - Why it matters: Controls the starting permission level for new users who join through self-signup.
- Note: Leave empty to create users without any role. Requires Enable Self Signup to be active. The role must already exist in OpenMetadata.
Summary
Quick reference of all configuration fields and their example values.Common OIDC Provider Examples
Sample configurations for popular OIDC-compliant identity providers. KeycloakHow Confidential Clients Sign In
With a confidential client, OpenMetadata passes the identity provider’s ID token to the browser and renews it by redeeming the provider’s refresh token. The identity provider, not OpenMetadata, sets the token lifetime. Because the browser holds the provider’s ID token, the claims you map in Jwt Principal Claims Mapping, or the Email Claim, such asupn, must be present in the ID token the provider issues.
Token Validation
A token signed by the identity provider must name one of your configured clients (clientId) in its audience, or OpenMetadata rejects the request with 401. For confidential clients, the token’s issuer must also match the issuer in the provider’s discovery document. Tokens signed by OpenMetadata itself, such as bot tokens and personal access tokens, are not subject to these checks.
Session Renewal
- Ended session: OpenMetadata returns
401and ends the session if the provider issued no refresh token, rejects the refresh token (invalid_grantorinvalid_token), or returns no ID token that lasts more than 60 seconds. The browser then tries to sign the user in again at the identity provider without prompting, and shows the sign-in page if that does not succeed. - No answer from the provider: OpenMetadata returns
503and keeps the session. The browser may still sign the user out. - Session limit: The session expiry (Session Expiry, or OIDC Session Expiry when Session Expiry is not set) still caps the session. A renewal never extends it. Logging out or revoking a session ends it at once, but the ID token already issued stays valid until it expires, and the next renewal fails.
Display Name and Picture
On sign-in with a confidential OIDC client, OpenMetadata fills the display name from the provider (name, or first and last name) when the user’s display name is empty or only repeats the login name. A display name set in OpenMetadata is kept. If you set Email Claim, the provider’s name replaces the stored display name on every sign-in.
OpenMetadata also stores the picture from the standard picture claim when it is an absolute http or https URL. A new picture replaces all stored sizes. A token without a valid picture never clears the stored picture.
MCP Sign-In and Self Sign-Up
Model Context Protocol (MCP) sign-in reads the claims mapping like web sign-in, including claim names that contain a colon. It does not read Email Claim. Opening/signup directly, without a pending self-sign-up user, redirects to the sign-in page.
Troubleshooting
Troubleshooting
If users are automatically logged out and unable to log in again due to a bad authentication configuration, you can reset the security setup using the following command:Docker Security
Configure SSO for your Docker deployment.
Bare Metal Security
Configure SSO for your bare metal deployment.
Kubernetes Security
Configure SSO for your Kubernetes deployment.