Configuration Reference Parameters
Public Key Url (publicKeyUrls):
This needs to be updated as per different SSO providers. The default value ishttp://localhost:8585/api/v1/system/config/jwks. This is the URL where the public keys are stored. The public keys are used to verify the signature of the JWT token.
Client ID (id):
The client ID provided by your OIDC provider. This is typically obtained when you register your application with the OIDC provider.Type (type):
Specify the type of OIDC provider you are using (e.g., google, azure). This value is same asprovider in authenticationConfiguration.
Client Secret (secret):
Replace with the client secret provided by your OIDC provider.Scope (scope):
Define the scopes that your application requests during authentication. Update${OIDC_SCOPE:-"openid email profile"} with the desired scopes.
Discovery URI (discoveryUri):
Provide the URL of the OIDC provider’s discovery document. This document contains metadata about the provider’s configuration.Use Nonce (useNonce):
Set to true by Default, if you want to use nonce for replay attack protection during authentication. This does not need to be changed.Preferred JWS Algorithm (preferredJwsAlgorithm):
Specify the preferred JSON Web Signature (JWS) algorithm. Default is RS256 and need not be changed .Response Type (responseType):
Define the response type for the authentication request. Default is code and need not be changed.Disable PKCE (disablePkce):
Set${OIDC_DISABLE_PKCE:-true} to true if you want to disable Proof Key for Code Exchange (PKCE). If you want to send CodeVerifier and CodeChallenge in the request, set it to false.
Callback URL (callbackUrl):
Provide the callback URL where the OIDC provider redirects after authentication. Update${OIDC_CALLBACK:-"http://localhost:8585/callback"} with your actual callback URL.
Server URL (serverUrl):
Specify the URL of your OM Server. Default ishttp://localhost:8585.
Client Authentication Method (clientAuthenticationMethod):
Define the method used for client authentication. Default is client_secret_post.Tenant (tenant):
If applicable, specify the tenant ID for multi-tenant applications. Example in case of Azure.Max Clock Skew (maxClockSkew):
Define the maximum acceptable clock skew between your application server and the OIDC server.Custom Parameters (customParams):
If you have any additional custom parameters required for OIDC configuration, specify them here.Config (config):
The central configuration block for OpenMetadata.Provider (provider):
Specifies the authentication method to be used. The default isldap, but you can change it to another supported provider. Example: google, azure.
Entity Id (entityId):
The unique identifier for the SAML Identity Provider. Example:"https://mocksaml.com/api/saml/sso"
SSO Login URL (ssoLoginUrl):
The URL to which users are redirected for Single Sign-On (SSO) authentication. Example:"https://saml.example.com/entityid"
IPDX509 Certificate (idpX509Certificate):
The public certificate used by the IdP to sign SAML assertions. Example:"" (empty string means no certificate provided, needs to be set with actual certificate)
Authority URL (authorityUrl):
The URL used for SAML login, typically a custom endpoint for your SAML provider. Example:"http://localhost:8585/api/v1/saml/login"
Name ID (nameId):
The format for the NameID element in the SAML response, usually representing the unique identifier of the user. Example:"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
ACS (acs):
The Assertion Consumer Service (ACS) URL, where the IdP sends the SAML response after authentication. Example:"http://localhost:8585/api/v1/saml/acs"
SPX509 Certificate (spX509Certificate):
The public certificate used by the Service Provider to verify the IdP’s SAML response. Example:"" (empty string means no certificate provided, needs to be set with actual certificate)
Strict Mode (strictMode):
Whether to enforce strict compliance with the SAML standard, ensuring the response is fully validated. Default:false
Token Validity (tokenValidity):
The validity period of the SAML token in seconds. Default:"3600" (1 hour)
Must be a positive value. OpenMetadata rejects a zero or negative value, and falls back to 3600 at runtime if an invalid value is ever persisted.
Send Encrypted Name ID (sendEncryptedNameId):
Whether to send the NameID in an encrypted format in the SAML response. Default:false
Send Signed Auth Request (sendSignedAuthRequest):
Whether to sign the authentication request sent to the IdP. Default:false
Sign SP Metadata (signSpMetadata):
Whether to sign the Service Provider’s metadata when exchanging SAML metadata with the IdP. Default:false
Want Messages Signed (wantMessagesSigned):
Whether the Service Provider expects SAML messages to be signed. Default:false
Want Assertions Signed (wantAssertionsSigned):
Whether the Service Provider expects SAML assertions to be signed. Default:false
Want Assertion Encrypted (wantAssertionEncrypted):
Whether to encrypt the SAML assertion before sending it to the Service Provider. Default:false
Want Name ID Encrypted (wantNameIdEncrypted):
Whether to encrypt the NameID element in the SAML response. Default:false
Key Store File Path (keyStoreFilePath):
The file path to the keystore file containing certificates and private keys used for signing and encryption. Example:"" (empty string means no keystore file provided)
KeyStore Alias (keyStoreAlias):
The alias used to refer to the key inside the keystore file. Example:"" (empty string means no alias provided)
KeyStore Password (keyStorePassword):
The password used to access the keystore file. Example:"" (empty string means no password provided)
Class Name (className):
Specifies the class that handles the authorization logic. Default:"org.openmetadata.service.security.DefaultAuthorizer"
Container Request Filter (containerRequestFilter):
Specifies the request filter used to process authentication, especially for handling JWT tokens. Default:"org.openmetadata.service.security.JwtFilter"
Initial Admins (initialAdmins):
A list of users who will be granted administrative privileges during the initial setup. Example:["suresh"]
Principal Domain (principalDomain):
The domain that is associated with user accounts. Default:"open-metadata.org"
Deprecated. Use
botDomain for bot email addresses and allowedEmailDomains to restrict which email domains can sign in.Authority (authority):
The base URL of the OIDC authority. Example: Replace{IssuerUrl} with the URL of your custom OIDC provider.
Client ID (clientId):
The client ID for the application registered with the custom OIDC provider. Replace{client id} with the actual client ID.
Host (host):
The hostname of the LDAP server. Defaults tolocalhost.
Port (port):
The port number to connect to the LDAP server. Defaults to10636.
DN Admin Principal (dnAdminPrincipal):
The distinguished name (DN) of the admin user used for lookup operations in LDAP. Defaults to"cn=admin,dc=example,dc=com".
DN Admin Password (dnAdminPassword):
The password for the admin user. Defaults to"secret".
Userbase DN (userBaseDN):
The base DN for user lookup in LDAP. Defaults to"ou=people,dc=example,dc=com".
Mail Attribute Name (mailAttributeName):
The attribute name in LDAP that stores user email addresses. Defaults toemail.
Maximum Pool Size (maxPoolSize) (Optional):
Defines the maximum number of connections in the LDAP connection pool. Defaults to3.
SSL Enabled (sslEnabled):
Indicates if SSL is enabled for connecting to the LDAP server. Defaults totrue.
Custom Trust Manager Configuration (customTrustManagerConfig):
-
TrustStore FilePath (trustStoreFilePath):
Path to the custom trust store file. Default is empty. -
TrustStore File Password (trustStoreFilePassword):
Password for the trust store file. Default is empty. -
TrustStore File Format (trustStoreFileFormat):
Format of the trust store file. Default is empty. -
Verify Host Name (verifyHostname):
If hostname verification is enabled. Default is empty. -
Examine Validity Dates (examineValidityDates):
Whether to check validity dates for certificates. Default is empty.
Host Name Configuration (hostNameConfig):
-
Allow Wild Cards (allowWildCards):
Allows wildcard certificates in hostnames. Default is empty. -
Acceptable Host Names (acceptableHostNames):
A list of acceptable hostnames. Default is an empty list.
JVM Default Configurations (jvmDefaultConfig):
-
Verify Host Name (verifyHostname):
Enables hostname verification using JVM defaults. Default is empty.
Trust All Configurations (trustAllConfig):
-
Examine Validity Dates (examineValidityDates):
Checks the validity dates of certificates when usingTrustAllmode. Defaults totrue.
Enforce Principal Domain (enforcePrincipalDomain):
Whether to enforce user principal matching with the defined principal domainDeprecated. Use
allowedEmailDomains instead.Enable Secure Socket Connection (enableSecureSocketConnection):
If true, enables secure connections (SSL/TLS)Use Roles From Provider (useRolesFromProvider):
Whether to derive roles from the authentication provider. Roles must be included in the identity provider’s token and must match existing OpenMetadata role names. OpenMetadata skips any role name it doesn’t recognize. Whether a role change at the provider reaches OpenMetadata depends on how the user signs in:- OIDC sign-in: OpenMetadata updates the user’s roles each time they sign in, so a role added or removed at the provider takes effect at their next sign-in. If the token doesn’t include a roles claim at all, OpenMetadata treats it as no roles, because some providers leave the claim out once a user’s last role is removed. Admin access follows the provider’s
Adminrole, except for users listed inadminEmails(or the deprecatedadminPrincipals). - SAML sign-in: Signing in doesn’t update roles from the provider. Manage these users’ roles in OpenMetadata directly.
adminEmails (or the deprecated adminPrincipals) keeps admin access, because OpenMetadata restores it for everyone on those lists when they sign in. To remove it, remove the user from the list.
Initial Admins (initialAdmins):
List of initial admin users for the systemJWT Principal Claims (jwtPrincipalClaims):
Definition: The JWT claims OpenMetadata uses to identify the authenticated user.Deprecated. Use
emailClaim instead. This setting keeps working until email-first identity turns on, which happens when you set emailClaim without jwtPrincipalClaimsMapping.Note: At least one claim in this list must correspond to the user’s email
address — OpenMetadata uses this to identify and match authenticated users to
their accounts. Use
email for consistency and compatibility; for domain
scoping, use the hd claim.Note: If you are using Keycloak or Azure, avoid changing the order of
claims in
jwtPrincipalClaims for existing deployments. The system relies
on claim order to match users in tokens to existing user records — changing
the order can cause authentication failures.JWT Principal Claims Mapping (jwtPrincipalClaimsMapping):
Definition: Maps JWT claims to OpenMetadata user profile fields. From OpenMetadata 2.0.6, the session tokens that OpenMetadata issues after sign-in carry the username and email that this mapping resolves, so API calls stay authenticated when your provider uses a custom username claim.Deprecated. Use
emailClaim and displayNameClaim instead. If this setting is present, OpenMetadata keeps using the legacy flow even when emailClaim is set.email 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 — you don’t need to configure it using
jwtPrincipalClaimsMapping.given_name and family_name as claims in the ID token — OpenMetadata will pick them up automatically. Refer to your identity provider’s documentation for instructions:
Email-First User Identity
Starting in 2.1, OpenMetadata can identify a signed-in user by their email address instead of resolving a username from several token claims. The email address becomes the single key for finding an existing account. OpenMetadata generates the username from the email. For example,john.doe@company.com becomes john.doe. If that name is already taken, OpenMetadata appends a random suffix, for example john.doe_x7k2.
Email-first identity is opt-in. It turns on when you set emailClaim and have no jwtPrincipalClaimsMapping configured. Until then, OpenMetadata keeps using jwtPrincipalClaims as before, so upgrading without changing your configuration doesn’t change how users are matched.
Deprecated settings keep working until their replacement takes over. For
jwtPrincipalClaims, that happens when you set emailClaim and have no jwtPrincipalClaimsMapping configured. OpenMetadata logs a deprecation warning at startup only after you configure the replacement.
What Email-First Identity Changes
When email-first identity is on:- OpenMetadata rejects unknown emails instead of guessing. If no account matches the email in the token, but another account already uses the same name as the start of that email, sign-in fails with a
401. This stops an unregistered email from acting as another user. - Deactivated accounts can’t sign in. OpenMetadata doesn’t restore or update a deactivated (soft-deleted) user when their email appears in a token.
- OpenMetadata rejects unverified emails. It refuses an OIDC token that explicitly has
email_verified: false. A token without the claim is accepted. - OpenMetadata updates display names only when the provider sends one. A display name that a user customized in OpenMetadata isn’t overwritten by a value built from their email.
- Self-signup follows
allowedEmailRegistrationDomainsfor OIDC and SAML. LDAP self-signup follows it on every deployment, as described in Changes That Apply to Every Deployment. allowedEmailDomainsapplies to tokens from your identity provider. Tokens issued by OpenMetadata itself, such as session tokens and personal access tokens, skip the check. This keeps the default admin and long-standing users signed in even if their email domain isn’t on the list.
Identity Provider Subject Binding
On a user’s first OIDC sign-in with email-first identity, OpenMetadata records the provider’s unique subject (sub) identifier on the user. If a later sign-in presents the same email with a different subject, OpenMetadata refuses the sign-in instead of giving the person the existing account. This protects against a provider reassigning a former employee’s email address to a new person.
- OIDC binds the subject. SAML and LDAP don’t, because SAML name IDs often change at each sign-in and LDAP has no subject.
- Existing users bind automatically at their next OIDC sign-in. No migration is needed.
- If you legitimately move to a new identity provider that issues new subjects, an administrator must clear the stored subject first. For more information, see Fix a User’s Email Address.
Fix a User’s Email Address
You can’t change a user’s email through the UI or API. Use theopenmetadata-ops.sh tool instead. Run it from your OpenMetadata installation:
--clear-identity-binding to also remove the recorded provider subject, so the user’s next sign-in binds again. Use it when the address now belongs to a different person.
Before turning on emailClaim, find accounts whose email was generated by OpenMetadata rather than supplied by your provider. These accounts have an address like user@principalDomain that won’t match a real address:
-d / --domain to list a specific domain. Then correct each account with change-email.
Changes That Apply to Every Deployment
These happen on upgrade to 2.1 whether or not you turn on email-first identity:- Stored emails become lowercase. The 2.1.0 migration lowercases every user email. Any script or integration that compares emails with case sensitivity sees the new values. No two users can collide because of this.
- MySQL email matching ignores accents.
jose@x.comandjosé@x.comnow match as the same address. - LDAP sign-in changes. Deactivated accounts can’t sign in anymore.
allowedEmailRegistrationDomainsnow applies to LDAP self-signup. A username collision gets a generated suffix instead of failing. The display name is synced from the directory, which overwrites a display name the user customized in OpenMetadata. POST /v1/usersrenames on a collision. For providers other than basic auth, a username that is already taken gets a generated suffix instead of returning a conflict error.
Email Claim (emailClaim):
Definition: The name of the token claim that holds the user’s email address. Setting it turns on email-first identity, unlessjwtPrincipalClaimsMapping is also configured.
Example: email
Environment variable: AUTHENTICATION_EMAIL_CLAIM. Default: empty, which keeps the legacy jwtPrincipalClaims behavior.
Display Name Claim (displayNameClaim):
Definition: The name of the token claim that holds the user’s display name. OpenMetadata reads it only whenemailClaim is set.
Example: name
Environment variable: AUTHENTICATION_DISPLAY_NAME_CLAIM. Default: empty.
Admin Emails (adminEmails):
Definition: Email addresses of users who get administrator access. ReplacesadminPrincipals.
Example: ["admin@company.com"]
Environment variable: AUTHORIZER_ADMIN_EMAILS. Default: [].
adminEmails matches users by email. The deprecated adminPrincipals still matches existing users by name, so upgrading doesn’t create duplicate admin accounts.
Allowed Email Domains (allowedEmailDomains):
Definition: Email domains allowed to sign in. When empty, all domains are allowed. Example:["company.com", "subsidiary.com"]
Environment variable: AUTHORIZER_ALLOWED_EMAIL_DOMAINS. Default: [].
Bot Domain (botDomain):
Definition: The email domain OpenMetadata uses for bot accounts it creates, for exampleingestion-bot@{botDomain}. Replaces principalDomain for bots.
Environment variable: AUTHORIZER_BOT_DOMAIN. Default: empty.