Walkthrough: Configuring OpenID Connect (OIDC)

OpenID Connect 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 team members 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.

This walkthrough describes how to:

  • Register Sitecore Cloud Portal with your OIDC identity provider

  • Add a new SSO connection

  • Test the SSO connection (optional, but strongly recommended)

  • Verify the domain

  • Enable the SSO connection

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)

Okta

Auth0

Add an SSO connection in Sitecore Cloud Portal

After you've registered Sitecore Cloud Portal with your identity provider, you create an SSO connection using the information from your identity provider.

To add an SSO connection:

  1. Navigate to the Sitecore Cloud Portal SSO page 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 later.

    Field

    Description

    Email domain

    The email domain associated with this SSO connection.

    Email addresses of team members authenticating using the identity provider must belong to the specified email domain, otherwise authentication will fail.

    Connection name

    The name for your new SSO connection. This name is shown when you view the list of SSO connections in your Sitecore Cloud Portal organization.

    Connection type

    Determines how the authorization server of the identity provider returns result parameters from the authorization endpoint.

    Check your IdP's documentation for information on which option to choose.

    Front Channel (Implicit flow) will use OIDC protocol with response_mode=form_post and response_type=id_token.

    Back Channel (Authorization Code flow) will use response_type=code.

    Issuer URL

    The URL of the discovery document of the identity provider you want to connect with (some providers call this the metadata address).

    Example: https://{yourDomain}/.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.

    We recommended that you also include the scopes that will return the following claims: name, given_name, family_name, nickname

    The claims returned by each scope value depends on your IdP. For example, if your IdP is Auth0 or Azure AD, 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 SSO connection

Testing your SSO 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.

To test the connection:

  1. Navigate to the Sitecore Cloud Portal SSO page 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 SSO connection test failed, try again or verify that your SSO connection settings are correct.

Verify the domain

Note

You can verify the domain before or after you test the SSO connection.

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

To verify the domain:

  1. Navigate to the Sitecore Cloud Portal SSO page and for the connection you want to verify, click Verify domain.

  2. In the Verify domain dialog, copy the TXT record, then add it to your domain's DNS record.

    The way that you add a TXT record varies, depending 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.

  3. Click Verify domain.

    Note

    Domain verification usually takes a few seconds. However, it can take the domain host up to 72 hours to make the TXT record publicly available.

Enable the SSO connection

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

To enable the SSO connection:

When you enable your SSO connection, team members 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 team members to your Sitecore Cloud Portal organization.

Do you have some feedback for us?

If you have suggestions for improving this article,