Configuring SAML single sign-on

Security Assertion Markup Language (SAML) is an open security standard for managing authentication and access. SAML for single sign-on allows team members to log in to the Sitecore Cloud Portal using their existing SAML identity provider.

Sitecore supports service provider (SP) initiated SAML.

Note

Sitecore does not support just-in-time (JIT) provisioning, single logout (SLO), request signing, or response encryption.

In SAML single sign-on setup (SSO), there are two main entities:

  • Service provider (SP) - The app or website that a user wants to access. In our case, Sitecore Cloud Portal is the SP.

  • Identity provider (IdP) - The entity that stores user information and credentials and provides authentication. Popular IdPs include Microsoft Entra and Okta.

To allow team members to log in using a SAML identity provider, you need to configure SAML SSO.

When setting up SAML SSO, you'll need SP metadata to configure your IdP and you'll need IdP metadata to configure your SSO connection. Sitecore generates the the SP metadata when you add a new connection. In general, your IdP generates the IdP metadata when you create a SAML app to register Sitecore Cloud Portal with your IdP.

Warning

Before enabling an SSO connection, we highly recommend reading about what happens when you enable SSO.

This walkthrough describes how to:

  1. Add an SSO connection in Sitecore Cloud Portal

  2. Register Sitecore Cloud Portal with your SAML identity provider

  3. Configure your SSO connection

  4. Map Sitecore attributes to your identity provider's SAML attributes

  5. Test the SSO connection

  6. Verify the domains

  7. Enable the SSO connection

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.

  • Your IdP must support SAML 1.1 or SAML 2.0.

Add an SSO connection in Sitecore Cloud Portal

To configure SAML SSO, you need to create a new SSO connection in Sitecore Cloud Portal. When you add a SAML SSO connection, Sitecore generates metadata that you use to register Sitecore Cloud Portal with your SAML 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 SAML.

  3. In the Add SAML connection dialog, enter the email domains, up to 50, for your connection, then click Add and configure.

    Note

    You cannot make changes to the email domains associated with an SSO connection. You will need to delete the connection and add a new one.

  4. Copy the values in the Service provider (SP) metadata URL, Audience URI, and Assertion Consumer Service (ACS) URL fields. You'll need these when you register Sitecore Cloud Portal with your identity provider.

Register Sitecore Cloud Portal with your SAML identity provider

After adding a SAML 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:

  1. Create a SAML app in your IdP (some providers call it an app integration, client, or SAML profile).

    Example: Ping Identity

  2. Configure your SAML app with the service provider (SP) metadata you copied when you added a new SSO connection.

    Your IdP asks for one of the following:

    • Service provider metadata URL.

    • Audience URI (also called service provider sign-on callback, post-back URL, or callback URL) and the assertion consumer service URL (also called service provider entity ID or audience restriction).

Configure your SSO connection

After registering Sitecore Cloud Portal with your identity provider, you'll need to find the IdP metadata and add it to the SSO connection you created earlier.

To configure the SSO connection:

  1. Copy the IdP metadata from your identity provider.

    Example: Ping Identity

  2. Navigate to the Sitecore Cloud Portal SSO page, find the SSO connection you created earlier, and click Configure.

  3. In Step 2: Add the identity provider metadata, select the metadata type, then paste the IdP metadata in the provided field.

  4. Click Save.

Map Sitecore attributes to your identity provider's SAML attributes

Note

If your Identity provider's SAML response includes email, family_name, and given_name, no further configuration is required and you can test the SSO connection now.

When a user tries to log in, Sitecore Cloud Portal expects the email, given_name, and family_name attributes in your IdP's SAML response. Attributes are case-sensitive.

Sitecore attribute

Map to IdP attribute name

Priority

email

User's email.

Required

given_name

User's given name(s) or first name(s).

Optional

family_name

User's surname(s) or last name(s).

Identity providers might have different names for these attributes or not provide them by default.

  • If your IdP's SAML response does not include the email attribute, your SSO connection will fail.

  • If the SAML response does not include family_name and given_name, your team members might have missing details in the Sitecore Cloud Portal.

If your IdP's SAML response does not include an expected attribute or has an attribute that provides the wrong information:

  • Modify your identity provider’s SAML response to include the expected attributes by configuring attribute mapping within your identity provider.

    Example: Okta

If your IdP does not support attribute mapping and uses a different attribute name for the same information (for example, emailAddress instead of email):

  • Use the Attribute mapping section of the SSO connection config to define the IdP SAML attribute that matches the Sitecore attribute.

Test the SSO connection

Note

If you have multiple domains in your SSO connection, repeat these steps with all your domains.

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 domains

Note

You can verify a 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 a TXT record from the Verify domains dialog to your domain's DNS record.

To verify the domains:

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

  2. In the Verify domains dialog, copy each TXT record, then add them 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 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 SSO connection

After you've verified the domains 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,