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

# Auth0 SSO | OpenMetadata Authentication Guide

> Learn to configure Auth0 SSO for confidential clients with OIDC, secure token handling, and client secret setup for web and backend apps.

## Overview

Auth0 Single Sign-On (SSO) enables users to log in to OpenMetadata using their Auth0 credentials via OAuth 2.0 and OpenID Connect (OIDC). This guide covers both **Public** and **Confidential** clients. Confidential clients use both a client ID and a client secret for secure backend authentication, and public clients have no client secret.

## Configure Auth0 SSO

Complete the following steps to configure Auth0 SSO.

1. Navigate to **Settings** > **SSO**.

   ![Settings, SSO page with the Choose Provider list](https://mintcdn.com/openmetadata/3PpSys_jqwwEnY4U/public/images/how-to-guides/admin-guide/choose-provider.png?fit=max\&auto=format\&n=3PpSys_jqwwEnY4U\&q=85\&s=7cb38e3c81e081ad29b7bdb3ecb7a0ec)

2. Click **Auth0**, and then click **Configure**.

3. Enter the configuration details. For more information, see [Configuration Fields](#configuration-fields).

4. Click **Test Login** and complete the sign-in. For more information, see [Test Login](https://docs.open-metadata.org/v2.1.x-SNAPSHOT/how-to-guides/admin-guide/sso.md#test-login).

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

### Authentication Configuration

Configure the identity provider connection and basic authentication behavior.

#### Provider Name

* **Definition**: A human-readable name for this Auth0 SSO configuration instance.
* **Example**: `Auth0 SSO`, `Company Auth0`, `Custom Identity Provider`
* **Why it matters**: Helps identify this specific SSO configuration in logs and user interfaces.
* **Note**: This is a display name and doesn't affect authentication functionality.

#### Client Type

* **Definition**: Defines whether the application is public (no client secret) or confidential (requires client secret).
* **Options**: Public | Confidential
* **Example**: Confidential
* **Why it matters**: Determines security level and authentication flow. Confidential clients can securely store secrets.
* **Note**:
  * Use `Confidential` for backend services and web applications.
  * Use `Public` for single-page applications (SPAs) and mobile apps.
  * Auth0 typically uses **Confidential** client type.
  * You can't change **Client Type** after you save the configuration.

#### Enable Self Signup

* **Definition**: Allows users to automatically create OpenMetadata accounts on their first SSO login.
* **Options**: Enabled | Disabled
* **Example**: Enabled
* **Why it matters**: Controls whether new users join automatically or need manual provisioning.
* **Note**: Disable for stricter control over user access.

#### Authority

* **Definition**: Auth0 endpoint that issues tokens for your tenant.
* **Example**: `https://dev-abc123.us.auth0.com`
* **Why it matters**: Tells OpenMetadata which Auth0 tenant to authenticate against.
* **Note**: Replace `dev-abc123` with your actual Auth0 tenant domain.

### Public Client Configuration

When **Client Type** is set to **Public**, the form shows the following fields instead of **OIDC Configuration**.

#### Client ID

* **Definition**: The client ID of the Auth0 application that OpenMetadata uses to identify itself.
* **Why it matters**: A public client has no client secret, so the client ID is the only application credential.

#### Callback URL

* **Definition**: The redirect URL where Auth0 sends authentication responses after login.
* **Note**:
  * **This field is read-only**: OpenMetadata fills it in as `{your-domain}/callback`.
  * Copy this URL and register it as an authorized redirect URI in your Auth0 application.
  * Use HTTPS in production.

#### Authority

* **Definition**: The URL of the Auth0 authorization server.
* **Why it matters**: Specifies where OpenMetadata sends authentication requests.

#### Public Key URLs

* **Definition**: One or more URLs where Auth0 publishes its JSON Web Token (JWT) signing keys.
* **Why it matters**: OpenMetadata uses the keys to verify the signature of the tokens that Auth0 issues.

#### Token Validation Algorithm

* **Options**: `RS256` | `RS384` | `RS512`
* **Note**: The value must match the signing algorithm that Auth0 uses. Most providers use `RS256`.

### OIDC Configuration

Configure the OIDC client credentials and token handling. These fields appear when **Client Type** is set to **Confidential**.

#### OIDC Client ID

* **Definition**: Application (client) ID for OIDC authentication with Auth0.
* **Example**: `abc123def456ghi789jkl012mno345pqr`
* **Why it matters**: Identifies your application to Auth0 in OIDC flows.
* **Note**: Found in **Auth0** > **Applications** > **Your app** > **Settings** under **Client ID**.

#### OIDC Client Secret

* **Definition**: Secret key for confidential client authentication with Auth0.
* **Example**: `abc123def456ghi789jkl012mno345pqr678st`
* **Why it matters**: Required for confidential clients to securely authenticate with Auth0.
* **Note**:
  * Found in **Auth0** > **Applications** > **Your app** > **Settings** (scroll to **Client Secret**).
  * Store securely and rotate regularly.

#### Scope

* **Definition**: Permissions requested from Auth0 during authentication.
* **Default**: `openid email profile`
* **Example**: `openid email profile`
* **Why it matters**: Determines what user information OpenMetadata can access.
* **Note**: `openid email profile` is sufficient for most use cases.

#### OIDC Discovery URI

* **Definition**: Auth0's OpenID Connect metadata endpoint.
* **Example**: `https://dev-abc123.us.auth0.com/.well-known/openid-configuration`
* **Why it matters**: Allows OpenMetadata to automatically discover Auth0's OIDC endpoints.
* **Note**: Replace `dev-abc123` with your actual Auth0 tenant domain.

#### OIDC Callback URL

* **Definition**: URL where Auth0 redirects after authentication.
* **Example**: `https://openmetadata.company.com/callback`
* **Why it matters**: Must be registered in your Auth0 configuration.
* **Note**:
  * **This field is read-only**: it is auto-populated as `{your-domain}/callback`.
  * Copy this URL and add it to Auth0's allowed redirect URIs list.

#### OIDC Prompt

* **Definition**: Controls Auth0'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 `none` itself when it re-authenticates a user silently.
* **Example**: `select_account`
* **Why it matters**: Defines how the login experience behaves for users.
* **Note**:
  * `login`: Always prompt for credentials.
  * `consent`: Prompt for permissions.
  * `select_account`: Show account picker.

#### OIDC Custom Parameters

* **Definition**: Additional parameters to include in OIDC authentication requests.
* **Example**: `{"prompt": "select_account", "domain_hint": "company.com"}`
* **Why it matters**: Allows customization of Auth0 authentication behavior.
* **Note**: Common parameters include `prompt`, `domain_hint`, `login_hint`.

#### Advanced Configuration

The following fields are grouped under **Advanced Config** in the UI (collapsed by default):

##### OIDC Use Nonce

* **Definition**: Security feature to prevent replay attacks in OIDC flows.
* **Default**: `false`
* **Why it matters**: Enhances security by ensuring each authentication request is unique.

##### OIDC Disable PKCE

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

##### OIDC Max Clock Skew

* **Definition**: Maximum allowed time difference in seconds between systems when validating tokens.
* **Example**: `0`
* **Why it matters**: Prevents token validation failures due to minor clock differences between servers.

##### OIDC Token Validity

* **Definition**: Duration in seconds that tokens remain valid.
* **Default**: `3600`
* **Example**: `3600`
* **Why it matters**: Balances token lifetime against security requirements.
* **Note**: The value must be positive. OpenMetadata rejects a zero or negative value, and falls back to `3600` at runtime if an invalid value is ever persisted.

##### OIDC Max Age

* **Definition**: The `max_age` request 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 `0` is treated as not set. To force users to re-enter their credentials, set **OIDC Prompt** to `login`.

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

##### End Session With Identity Provider

* **Definition**: Controls whether OpenMetadata ties a user session to the identity provider's session.
* **Default**: `false`
* **Note**:
  * Available for confidential OIDC clients only.
  * When on, OpenMetadata renews the identity provider's tokens on the provider's schedule while the user is active. It signs the user out when the provider rejects the refresh token. The token that OpenMetadata issues is shortened to that schedule, with a minimum of 120 seconds. A renewal never extends the session beyond **OIDC Session Expiry**.
  * When off, a session lasts for the configured **OIDC Session Expiry**.
  * The sign-out depends on the provider. Keycloak revokes refresh tokens together with the provider session, and Microsoft Entra ID doesn't.

### JWT Claims

Map identity token claims to OpenMetadata user identities and team assignments.

#### JWT Principal Claims

* **Definition**: JWT fields used to identify users in OpenMetadata. The first claim that returns a value is used.
* **Default**: `["email", "name", "sub"]`
* **Example**: `["email", "name", "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.
  * Common Auth0 claims: `email`, `name`, `sub`, `nickname`.
  * Order matters: the first matching claim is used.

> [!WARNING]
>
> **Important**: Incorrect claims will lock out all users including admins. The default values (`email`, `name`, `sub`) work for most Auth0 configurations. Only change if you have custom claim requirements.

#### JWT Principal Claims Mapping

**Definition**: Maps JSON Web Token (JWT) claims to OpenMetadata user profile fields.

**Supported keys**: Only `email` and `username` are valid mapping targets in `jwtPrincipalClaimsMapping`.

**Example**:

```yaml theme={null}
["email:email", "username:preferred_username"]
```

**Why it matters**: Controls how SSO login data maps to user profiles in OpenMetadata.

**Format**: `openmetadata_field:jwt_claim` (for example, `"email:email"`).

> [!NOTE]
>
> **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 Auth0 includes `given_name` and `family_name` as claims in the ID token. OpenMetadata picks them up automatically.

> [!WARNING]
>
> **Important**: Using any other key (for example, `name` or `firstName`) will cause the service to fail on startup with a validation error. JWT Principal Claims Mapping is rarely needed. The default JWT Principal Claims handle user identification correctly for most Auth0 configurations.

#### JWT Team Claim Mapping

* **Definition**: Auth0 claim containing team or department information for automatic team assignment in OpenMetadata.
* **Example**: `department`, `groups`, `organization`
* **Why it matters**: Automatically assigns users to existing OpenMetadata teams based on their Auth0 user profile at login.
* **Note**:
  * Standard Auth0 profile fields: `department`, `organization`.
  * For group-based teams, use `groups` or `roles` claims (configure via Auth0 Rules or Actions).
  * 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.

### Authorizer Configuration

Control which users and domains are permitted to access OpenMetadata.

#### Admin Principals

* **Definition**: Users granted admin access in OpenMetadata.
* **Example**: `["admin", "superuser"]`
* **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, for `admin@company.com`, enter `admin`).

#### Principal Domain

* **Definition**: Default domain for user principals.
* **Example**: `company.com`
* **Why it matters**: Used to construct full user identifiers when only a username is provided.

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

#### 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 Auth0.
* **Note**: Recommended in production environments.

#### Allowed Domains

* **Definition**: List of email domains permitted to authenticate with OpenMetadata.
* **Example**: `["company.com", "partner-company.com"]`
* **Why it matters**: Provides fine-grained control over which email domains can log in via Auth0.
* **Note**:
  * Works in conjunction with **Enforce Principal Domain**.
  * Leave empty if you only use a single domain configured in **Principal Domain**.

#### Use Roles From Provider

* **Definition**: Use roles returned by Auth0 in the token to assign OpenMetadata roles.
* **Default**: `false`
* **Why it matters**: Enables role-based access control driven by your Auth0 role assignments.
* **Note**: Roles must be included in the Auth0 token and must match existing OpenMetadata role names.
  * Roles sync on every login. A role change in Auth0 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.

| Field | Example / Default |
| - | - |
| Provider Name | Auth0 SSO |
| Client Type | Confidential |
| Enable Self Signup | Enabled |
| Authority | [https://dev-abc123.us.auth0.com](https://dev-abc123.us.auth0.com) |
| OIDC Client ID | abc123def456ghi789jkl012mno345pqr |
| OIDC Client Secret | abc123def456... |
| Scope | openid email profile |
| OIDC Discovery URI | [https://dev-abc123.us.auth0.com/.well-known/openid-configuration](https://dev-abc123.us.auth0.com/.well-known/openid-configuration) |
| OIDC Callback URL | `https://openmetadata.company.com/callback` (read-only) |
| OIDC Prompt | select\_account |
| OIDC Custom Parameters | `{"prompt": "select_account"}` |
| OIDC Use Nonce | false |
| OIDC Disable PKCE | false |
| OIDC Max Clock Skew | 0 |
| OIDC Token Validity | 3600 |
| OIDC Max Age | Leave empty |
| OIDC Session Expiry | 604800 |
| JWT Principal Claims | `["email", "name", "sub"]` |
| JWT Principal Claims Mapping | `["email:email"]` |
| JWT Team Claim Mapping | department |
| Admin Principals | `["admin", "superuser"]` |
| Principal Domain | company.com |
| Enforce Principal Domain | false |
| Enable Secure Socket Connection | true |
| Allowed Domains | `["company.com"]` |
| Use Roles From Provider | false |
| Default OAuth Role | DataConsumer |

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

```

./bootstrap/openmetadata-ops.sh remove-security-config --force

```

After executing the command, **restart the server**. The authentication values from your YAML or Helm chart will then be reapplied on startup. The following tiles detail how to apply this configuration across Docker, Kubernetes, and Bare Metal deployments:

> **[Docker Security](https://docs.open-metadata.org/v2.1.x-SNAPSHOT/deployment/docker/security.md)**
>
> Configure SSO for your Docker deployment.

> **[Bare Metal Security](https://docs.open-metadata.org/v2.1.x-SNAPSHOT/deployment/bare-metal/security.md)**
>
> Configure SSO for your bare metal deployment.

> **[Kubernetes Security](https://docs.open-metadata.org/v2.1.x-SNAPSHOT/deployment/kubernetes/security.md)**
>
> Configure SSO for your Kubernetes deployment.


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