> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC Based Authentication

# Configuration Reference Parameters

## Public Key Url (publicKeyUrls):

This needs to be updated as per different SSO providers. The default value is `http://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.

<Warning>
  **Google**: [https://www.googleapis.com/oauth2/v3/certs](https://www.googleapis.com/oauth2/v3/certs)

  **Okta**: [https://dev-19259000.okta.com/oauth2/aus5836ihy7o8ivuJ5d7/v1/keys](https://dev-19259000.okta.com/oauth2/aus5836ihy7o8ivuJ5d7/v1/keys)

  **Auth0**: [https://dev-3e0nwcqx.us.auth0.com/.well-known/jwks.json](https://dev-3e0nwcqx.us.auth0.com/.well-known/jwks.json)

  **Azure**: [https://login.microsoftonline.com/\{tenant}/discovery/v2.0/keys](https://login.microsoftonline.com/\{tenant}/discovery/v2.0/keys)

  Also if you have enabled [JWT Tokens](/deployment/security/enable-jwt-tokens) then `http://localhost:8585/api/v1/system/config/jwks` also needs to be there in the list with proper server url.
</Warning>

## 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 as `provider` 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.

<Tip>
  It does not need to be changed in most cases. The default scopes are `openid email profile`. The `openid` scope is required for OIDC authentication. The `email` and `profile` scopes are used to retrieve the user's email address and profile information.
  Some providers return refresh tokens only when `offline_access` is requested. If refresh tokens are required, add `offline_access` to the configured scopes, for example:
  `openid email profile offline_access`.
</Tip>

## Discovery URI (discoveryUri):

Provide the URL of the OIDC provider's discovery document. This document contains metadata about the provider's configuration.

<Warning>
  It is mostly in the format as below: [https://accounts.google.com/.well-known/openid-configuration](https://accounts.google.com/.well-known/openid-configuration)

  **Google**: [https://accounts.google.com/.well-known/openid-configuration](https://accounts.google.com/.well-known/openid-configuration)

  **Okta**: [https://dev-19259000.okta.com/oauth2/aus5836ihy7o8ivuJ5d7/.well-known/openid-configuration](https://dev-19259000.okta.com/oauth2/aus5836ihy7o8ivuJ5d7/.well-known/openid-configuration)

  **Auth0**: [https://dev-3e0nwcqx.us.auth0.com/.well-known/openid-configuration](https://dev-3e0nwcqx.us.auth0.com/.well-known/openid-configuration)

  **Azure**: [https://login.microsoftonline.com/\{tenant}/v2.0/.well-known/openid-configuration](https://login.microsoftonline.com/\{tenant}/v2.0/.well-known/openid-configuration)

  Normally it's some initial SSO provider URL followed by `.well-known/openid-configuration`
</Warning>

## 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.

<Warning>
  The only initial part of the URL should be changed, the rest of the URL should be the same as the default one. The default URL is `http://localhost:8585/callback`.
  Also, this should match what you have configured in your OIDC provider.
</Warning>

## Server URL (serverUrl):

Specify the URL of your OM Server. Default is `http://localhost:8585`.

## Client Authentication Method (clientAuthenticationMethod):

Define the method used for client authentication. Default is client\_secret\_post.

<Warning>
  This does not need to be changed in most cases. The default value is `client_secret_post`.
  This method is used to send the client ID and client secret in the request body.
  Another possible value is `client_secret_basic`, which sends the client ID and client secret in the Authorization header.
  Depending on the OIDC provider, you may need to change this value if only one of them is supported.
</Warning>

## Tenant (tenant):

If applicable, specify the tenant ID for multi-tenant applications. Example in case of Azure.

<Warning>
  This is only applicable for multi-tenant applications. If you are using a single tenant application, you can leave this field empty.
  For Azure SSO Provider this may be needed.
</Warning>

## 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 is `ldap`, 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. Collate 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"`

<Note>
  **Deprecated.** Use `botDomain` for bot email addresses and `allowedEmailDomains` to restrict which email domains can sign in.
</Note>

## 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 to `localhost`.

## Port (port):

The port number to connect to the LDAP server. Defaults to `10636`.

## 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 to `email`.

## Maximum Pool Size (maxPoolSize) (Optional):

Defines the maximum number of connections in the LDAP connection pool. Defaults to `3`.

## SSL Enabled (sslEnabled):

Indicates if SSL is enabled for connecting to the LDAP server. Defaults to `true`.

## 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 using `TrustAll` mode. Defaults to `true`.

## Enforce Principal Domain (enforcePrincipalDomain):

Whether to enforce user principal matching with the defined principal domain

<Note>
  **Deprecated.** Use `allowedEmailDomains` instead.
</Note>

## Allowed Domains (allowedDomains):

Domains allowed to access Collate.

<Note>
  **Deprecated.** Use `allowedEmailDomains` instead.
</Note>

## 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 Collate role names. Roles sync on every login, not just the first, so a role change at the provider takes effect the next time the user signs in. If the token omits the roles claim entirely, Collate leaves existing role assignments untouched. This can promote a user to Admin but never demotes an existing admin assigned through `adminPrincipals`.

## Initial Admins (initialAdmins):

List of initial admin users for the system

## JWT Principal Claims (jwtPrincipalClaims):

JWT claims used to identify the principal (user)

<Note>
  **Deprecated.** Use `emailClaim` instead. This setting keeps working until email-first identity turns on, which happens when you set `emailClaim` without `jwtPrincipalClaimsMapping`.
</Note>

For more information, see [Email-First User Identity](#email-first-user-identity).

## JWT Principal Claims Mapping (jwtPrincipalClaimsMapping):

Mapping of JWT claims to application-specific claims

<Note>
  **Deprecated.** Use `emailClaim` and `displayNameClaim` instead. If this setting is present, Collate keeps using the legacy flow even when `emailClaim` is set.
</Note>

## Email-First User Identity

Starting in Collate 2.1, Collate 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. Collate generates the username from the email. For example, `john.doe@company.com` becomes `john.doe`. If that name is already taken, Collate 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, Collate keeps using `jwtPrincipalClaims` as before, so upgrading without changing your configuration doesn't change how users are matched.

| Deprecated setting | Replace with |
| - | - |
| `jwtPrincipalClaims` | `emailClaim` |
| `jwtPrincipalClaimsMapping` | `emailClaim` and `displayNameClaim` |
| `adminPrincipals` | `adminEmails` |
| `principalDomain` | `botDomain` for bots, `allowedEmailDomains` to restrict sign-in |
| `enforcePrincipalDomain`, `allowedDomains` | `allowedEmailDomains` |

Deprecated settings keep working until their replacement takes over. For `jwtPrincipalClaims`, that happens when you set `emailClaim` and have no `jwtPrincipalClaimsMapping` configured. Collate logs a deprecation warning at startup only after you configure the replacement.

### What Email-First Identity Changes

When email-first identity is on:

* Collate 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. Collate doesn't restore or update a deactivated (soft-deleted) user when their email appears in a token.
* Collate rejects unverified emails. It refuses an OIDC token that explicitly has `email_verified: false`. A token without the claim is accepted.
* Collate updates display names only when the provider sends one. Collate doesn't overwrite a display name that a user customized with a value built from their email.
* Self-signup follows `allowedEmailRegistrationDomains` for OIDC and SAML. LDAP self-signup follows it on every deployment, as described in [Changes That Apply to Every Deployment](#changes-that-apply-to-every-deployment).
* `allowedEmailDomains` applies to tokens from your identity provider. Tokens issued by Collate 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, Collate records the provider's unique subject (`sub`) identifier on the user. If a later sign-in presents the same email with a different subject, Collate 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-users-email-address).

### Fix a User's Email Address

You can't change a user's email through the UI or API. Use the `openmetadata-ops.sh` tool instead. Run it from your Collate installation:

```bash theme={null}
./bootstrap/openmetadata-ops.sh change-email \
  --email old.address@company.com \
  --new-email new.address@company.com
```

Add `--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 Collate rather than supplied by your provider. These accounts have an address like `user@principalDomain` that won't match a real address:

```bash theme={null}
./bootstrap/openmetadata-ops.sh list-synthesized-emails
```

Use `-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.com` and `josé@x.com` now match as the same address.
* LDAP sign-in changes. Deactivated accounts can't sign in anymore. `allowedEmailRegistrationDomains` now 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 Collate.
* `POST /v1/users` renames 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, unless `jwtPrincipalClaimsMapping` 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. Collate reads it only when `emailClaim` is set.

**Example**: `name`

**Environment variable**: `AUTHENTICATION_DISPLAY_NAME_CLAIM`. Default: empty.

## Admin Emails (adminEmails):

**Definition**: Email addresses of users who get administrator access. Replaces `adminPrincipals`.

**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 Collate uses for bot accounts it creates, for example `ingestion-bot@{botDomain}`. Replaces `principalDomain` for bots.

**Environment variable**: `AUTHORIZER_BOT_DOMAIN`. Default: empty.

## Enable Self Signup (enableSelfSignup):

Allows users to sign up themselves if not already registered

## Preferred JWT Algorithms (preferredJwsAlgorithm):

Preferred algorithm for JWT signature validation

## Allowed Email Registration Domains (allowedEmailRegistrationDomains):

Specifies allowed domains for email registration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.