---
title: "Configuring OpenID Connect (OIDC)"
slug: "configuring-openid-connect--oidc-"
abstract: "Describes how to prepare and set up an OpenID Connect (OIDC) SSO provider in the Sitecore Cloud Portal, then test and verify the connection before enabling it."
---
# Configuring OpenID Connect (OIDC)

OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol. It enables client applications to rely on authentication that is performed by an OpenID Connect provider to verify the identity of a user.

To configure SSO, you must have an *Organization Admin* or *Organization Owner* role. You must also have the ability to register Sitecore Cloud Portal with your identity provider (IdP) and the ability to create a TXT record with your domain host.

To allow users to log in using an OIDC identity provider, you need to configure OpenID Connect.

> [!warning]
> Before enabling an SSO connection, we strongly recommend reading about [what happens when you enable SSO](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-.html#UUID-ef17d465-08c0-d1e7-5ddf-415134bd2607_section-idm4661349863516833684732279403 "Enabling an SSO connection").

This walkthrough describes how to:

:::walkthrough
1. [Register Sitecore Cloud Portal with your OIDC identity provider](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configuring-openid-connect--oidc-.html#register-sitecore-cloud-portal-with-your-oidc-identity-provider)
2. [Add an OIDC connection in Sitecore Cloud Portal](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configuring-openid-connect--oidc-.html#add-an-oidc-connection-in-sitecore-cloud-portal)
3. [Test the connection](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configuring-openid-connect--oidc-.html#test-the-connection)
4. [Verify the domains](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configuring-openid-connect--oidc-.html#verify-the-domains)
5. [Enable the connection](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configuring-openid-connect--oidc-.html#enable-the-connection)
:::

> [!note]
> You can verify a domain before or after you test the SSO connection.

> [!note]
> **Before you begin**
> -   You must be an *Organization Admin* or *Organization Owner* in your Sitecore Cloud Portal organization.
>
> -   You must have the ability to register Sitecore Cloud Portal with your identity provider (IdP).
>
> -   You must have the ability to create a TXT record with your domain host.

## Register Sitecore Cloud Portal with your OIDC identity provider

Before you can add an SSO connection, you need to register Sitecore Cloud Portal with your identity provider. This process varies depending on the identity provider, but in general, you must create an application (some providers call it an *app integration* or *client*) to receive a `client ID` and `client secret`.

You might need to register `https://auth.sitecorecloud.io/login/callback` as an allowed callback URL (some providers call this a *redirect URI*) when you create the application.

The following are configuration guides for some common OpenID Connect identity providers:

- [Microsoft Entra ID (formerly Azure Active Directory)](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oidc)
- [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)
- [Auth0](https://auth0.com/docs/get-started/auth0-overview/create-applications)

## Add an OIDC connection in Sitecore Cloud Portal

Now you registered Sitecore Cloud Portal with your identity provider, you need to create an OIDC connection using the information from your identity provider.

> [!important]
> Sitecore Cloud Portal does not allow more than one SSO connection to use the same email domain. If you want to add a specific domain to a connection, you must delete any connection that currently uses it.

To add an OIDC connection:

1. Navigate to the [Sitecore Cloud Portal SSO page](https://portal.sitecorecloud.io/admin/sso) and click **Add SSO connection**.
2. In the drop-down menu, click **OpenID Connect**.
3. In the **Add SSO connection** dialog, enter the details for your connection, then click **Save**. You can [edit an SSO connection's settings](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/edit-or-delete-an-sso-connection.html#UUID-c290052c-e805-5bb5-005a-db8bc4ba64fe_section-idm4506609962417633684684181902 "Edit an SSO connection") later.

    | Field | Description |
    | --- | --- |
    | Email domains | Up to 50 email domains associated with this SSO connection.<br><br>Email addresses of users authenticating using the identity provider must belong to one of the specified email domains, otherwise authentication will fail. |
    | Connection type | Determines how the authorization server of the identity provider (IdP) returns result parameters from the authorization endpoint.<br><br>Check your IdP's documentation for information on which option to choose.<br><br>**Back Channel** ([Authorization Code flow](https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/)) uses `response_type=code`. JSON Web Tokens (JWTs) are transferred via server-to-server communication, reducing the risk of token exposure. This is the preferred method for most applications.<br><br>**Front Channel** ([Implicit flow](https://developer.okta.com/docs/guides/implement-grant-type/implicit/main/)) uses `response_mode=form_post` and `response_type=id_token`. JSON Web Tokens are transferred via browser, exposing tokens. This method is less secure and should only be used if the IdP does not support Authorization Code flow. |
    | Discovery URL | The URL of the discovery document of the identity provider you want to connect with (some providers call this the *metadata address*). Check your IdP's documentation for the correct URL.<br><br>Auth0 example: `https://{YOUR_DOMAIN}/.well-known/openid-configuration` |
    | Scopes | A space-separated list of scopes to request via the OpenID Connect scope parameter. The required scopes are `openid` and the scope that returns the `email` claim.<br><br>We recommended that you also include the scopes that will return the following claims: `name`, `given_name`, `family_name`, and `nickname`.<br><br>The claims returned by each scope value depends on your IdP. For example, if your IdP is Auth0 or Microsoft Entra ID, you would enter the following scopes: `openid profile email`. |
    | Client ID | The `client ID` of the application created when you registered the Sitecore Cloud Portal with your identity provider. |
    | Client secret | The `client secret` of the application created when you registered the Sitecore Cloud Portal with your identity provider. This field is required if using Back Channel (Authorization Code flow). |
    | Callback URL | The location where the identity provider will send the authentication response. You might need to add this URL (some providers call it a *redirect URI*) when you register the Sitecore Cloud Portal with your identity provider. |

## Test the connection

Testing your OIDC connection is optional, but we strongly recommend it to ensure that the connection works. You can test an SSO connection at any time by trying to sign in using your identity provider.

> [!note]
> If you have multiple domains in your SSO connection, repeat these steps with all your domains.

To test the connection:

1. Navigate to the [Sitecore Cloud Portal SSO page](https://portal.sitecorecloud.io/admin/sso) and click **Test** for the connection you want to test.
2. In the **Test SSO connection** dialog, click **Start test**.
3. On the tab that opens, sign in using your identity provider.

If the test fails, verify that your SSO connection settings are correct and try again.

## Verify the domains

To make sure that no one else uses your domain to create an SSO connection, you must verify domain ownership by adding a TXT record from the **Verify domains** dialog to your domain's DNS record.

> [!note]
> You can verify a domain before or after you test the SSO connection.

To verify the domains:

1. Navigate to the [Sitecore Cloud Portal SSO page](https://portal.sitecorecloud.io/admin/sso).
2. For the connection you want to verify, click **Verify domains**.
3. In the **Verify domains** dialog, copy each TXT record, then add them to your domain's DNS record.

    The method for adding a TXT record depends on your domain host.

    In general:

    - Sign in to your domain registrar with the account and password you used to buy your domain.
    - Go to the section where you can update your domain's TXT records. This is typically called **DNS settings**, **DNS management**, or **Advanced settings**.
    - Create a new TXT record.

    For some examples, see [Google's custom instructions for many popular domain registrars](https://support.google.com/a/topic/1409901).

4. Click **Verify domains**.

    > [!note]
    > Domain verification usually takes a few seconds. However, it can take the domain host up to 72 hours to make a TXT record publicly available. After verifying the domain, you can remove the TXT record.

## Enable the connection

After you've verified the domains and (optionally) tested your SSO connection, you can enable it.

To enable the connection:

1. Navigate to the [Sitecore Cloud Portal SSO page](https://portal.sitecorecloud.io/admin/sso).
2. Next to the chosen SSO connection, click **Enable**.

When you enable your SSO connection, users that have email addresses with the email domain of an enabled SSO connection can log in using their identity provider.

After you enable an SSO connection, you can:

- [Invite users to your Sitecore Cloud Portal organization](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/invite-users-to-your-sitecore-cloud-portal-organization.html "Invite users to your Sitecore Cloud Portal organization").
- Configure [claims mapping](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/claims-mapping.html "Claims mapping") to [automatically assign SitecoreAI roles to users that log in to your organization using SSO](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/assign-sitecoreai-roles-with-claims-mapping.html).