> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getunleash.io/single-sign-on/how-to-add-sso-open-id-connect/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getunleash.io/_mcp/server. # Set up SSO with OpenID Connect > Set up OpenID Connect SSO for Unleash with Okta: configure discovery URL, client ID, client secret, users, and group sync. Enterprise This guide walks you through setting up single sign-on (SSO) for Unleash using the OpenID Connect (OIDC) protocol, with Okta as the identity provider (IdP). Unleash supports a variety of identity providers and protocols; visit our [reference documentation](/concepts/sso) to explore other options. ## Prerequisites To follow along, you'll need: * An Unleash instance with [Admin access](/concepts/rbac). * An Okta account with permission to create applications. ## Create an OIDC application in Okta To create a new OIDC application in Okta, do the following: 1. Sign in to your Okta account and go to **Admin > Applications**. 2. Click **Add Apps**, then **Create Application**. 3. Select **OIDC - OpenID Connect**, choose **Web Application** as the application type, and click **Create**. ![Okta: Add Apps](/_fern-img/5121fccacdd82c6f1d2a2ba18f9d740fd80640a198cd6284887f24e89d9122d6.webp) ![Okta: Create Apps](/_fern-img/cf74e4fa7577e81e533eb79abbdf3c5c9f501c91c9219f9e7a9384d64f83b1a6.webp) ## Configure the Okta application To configure the application, do the following: 1. Give your application a name. 2. Set **Sign-in redirect URI** to `https://[region].app.unleash-hosted.com/[instanceName]/auth/oidc/callback`. For self-hosted instances, the URL must match your `UNLEASH_URL` configuration. 3. Optional: set **Sign-out redirect URI** to `https://[region].app.unleash-hosted.com/[instanceName]/`. 4. Click **Save**. ![Okta: Configure OpenID Connect](/_fern-img/836d2da77b68a94904c80858f15d6eb4a7d873a32b60c3d63c59c876be88092e.webp) After saving, Okta provides the **Discover URL**, **Client ID**, and **Client Secret** you need to configure the Unleash side. ![Okta: Configure OpenID Connect](/_fern-img/ce559908add1d4109dd32780e044da764c98f6d0e021dc0c68f42c3ba9ff9153.webp) ## Configure the OpenID Connect provider in Unleash To finalize the configuration, do the following: 1. In the Unleash Admin UI, go to **Admin settings > Single sign-on > OpenID Connect**. 2. Enter the **Discover URL**, **Client ID**, and **Client Secret** from your Okta application. 3. Optional: To automatically create users for first-time sign-ins, select **Auto-create users**. Provide a list of valid email domains and choose a default root role for new users. The default root role is **Editor**. 4. Click **Save**. > **Note** > > The **Discover URL** must be a valid URL and include the `https://` prefix. For example, `https://dev-example-okta.com` is a valid Discover URL. ![Unleash: Configure OpenID Connect](/_fern-img/4d5685d4ca1cb0593796d28d8e64726082d3aad917fc962893ea6a92d0bfb98d.webp) ## Test your configuration To test that things are working as expected, log out of Unleash and verify that the login screen gives you the option to sign in with OpenID Connect. Click **Sign in with OpenID Connect** and complete the sign-in flow. If something is not working, you can still sign in with your username and password. ![Verify SSO](/_fern-img/c60997576814c5c057e5302ac098fdfae698e58f40c6b3716fab5831b647f9e1.webp) ## Configure OIDC through environment variables v6.1 Instead of configuring OIDC through the Admin UI, you can configure it through environment variables. > **Warning** > > Configuring OIDC through environment variables disables editing the settings in the Admin UI. To fall back to the UI, unset `OIDC_ENABLED` and restart Unleash. ### Required configuration **`OIDC_ENABLED`** `boolean` — required Tells Unleash to use environment variables to configure OIDC. Setting this to `false` turns off OIDC login. --- **`OIDC_DISCOVER_URL`** `string` — required URL used to dynamically retrieve the OIDC configuration. For example, `https://myoidchost.azure.com/.well-known/openid-configuration`. --- **`OIDC_CLIENT_ID`** `string` — required The OIDC client ID of this application. For example, `FB87266D-CDDB-4BCF-BB1F-8392FD0EDC1B`. --- **`OIDC_CLIENT_SECRET`** `string` — required Shared secret from the OpenID server, used to authenticate login requests. --- ### Auto-create users Configure these optional variables to automatically create Unleash users for SSO sign-ins from specific email domains. **`OIDC_AUTO_CREATE`** `boolean` — default: false Tells Unleash to auto-create users from the domains in `OIDC_AUTO_CREATE_EMAIL_DOMAINS`. --- **`OIDC_AUTO_CREATE_EMAIL_DOMAINS`** `string` A comma-separated list of domains to auto-create users for. If not set, all domains are accepted. For example, `getunleash.io,getunleash.ai`. --- **`OIDC_DEFAULT_ROOT_ROLE`** `string` — default: Viewer The root role to grant users auto-created through SSO. Allowed values: `Viewer`, `Editor`, `Admin`. --- ### Group syncing Configure these optional variables to sync groups from your identity provider to Unleash. **`OIDC_ENABLE_GROUP_SYNCING`** `boolean` — default: false Tells Unleash to set up group syncing from OIDC login requests. --- **`OIDC_GROUP_JSON_PATH`** `string` A JSON path expression that tells Unleash where to find the group membership information in the response. For example, `groups`. --- **`OIDC_ADD_GROUPS_SCOPE`** `boolean` — default: false Tells Unleash to add the `groups` access scope to the request. --- ### Additional options The following variables are optional. **`OIDC_ACR_VALUES`** `string` Authentication Context Class Reference. Used to request extra values in the `acr` claim returned from the server. If multiple values are required, they should be space-separated. --- **`OIDC_ID_TOKEN_SIGNING_ALGORITHM`** `string` Use this only if your provider is failing with an unsupported algorithm; the default should be fine. Allowed values: `RS256`, `RS384`, `RS512`. --- **`OIDC_ENABLE_SINGLE_SIGN_OUT`** `boolean` — default: false Whether Unleash should call the OIDC single sign-out endpoint. Requires Unleash v8 or later. --- **`OIDC_EXTRA_SCOPES`** `string` Space-separated list of additional scopes to request during login, beyond the default `openid email profile` and the `groups` scope if group syncing is enabled. For example, `custom1 custom2`. Requires Unleash v8 or later. --- > Set up OpenID Connect SSO for Unleash with Okta: configure discovery URL, client ID, client secret, users, and group sync.