---
title: "Configure SAML single sign-on"
slug: "configure-saml-single-sign-on"
abstract: "How to prepare and set up a Security Assertion Markup Language (SAML) SSO provider in the Sitecore Cloud Portal, then test and verify the connection before enabling it."
---
# Configure 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 users to log in to the Sitecore Cloud Portal using their existing SAML identity provider.

Sitecore supports *service provider (SP) initiated SAML*.

> [!important]
> 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](https://learn.microsoft.com/en-us/entra/architecture/auth-saml) and [Okta](https://help.okta.com/oie/en-us/content/topics/apps/apps-about-saml.htm).

To allow users to log in using a SAML identity provider, you need to configure SAML SSO. SAML certificates will expire over time, so you must [renew and update](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on/update-a-saml-certificate.html "Update a SAML certificate") them with your identity provider as needed to ensure uninterrupted access.

> [!tip]
> Unlike SAML, [Open ID Connect (OIDC) connections](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configuring-openid-connect--oidc-.html "Configuring OpenID Connect (OIDC)") do not rely on temporary certificates. Consider using OIDC instead if you prefer to avoid updating certificates.

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

> [!warning]
> Before enabling an SSO connection, we highly 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-/single-sign-on--sso-.html#UUID-ef17d465-08c0-d1e7-5ddf-415134bd2607_section-idm4661349863516833684732279403 "Enabling an SSO connection").

This walkthrough describes how to:

:::walkthrough
1. [Add an SSO connection in Sitecore Cloud Portal](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#add-an-sso-connection-in-sitecore-cloud-portal)
2. [Register Sitecore Cloud Portal with your SAML identity provider](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#register-sitecore-cloud-portal-with-your-saml-identity-provider)
3. [Configure your SSO connection](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#configure-your-sso-connection)
4. [Map Sitecore attributes to your identity provider's SAML attributes](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#map-sitecore-attributes-to-your-identity-providers-saml-attributes)
5. [Test the SSO connection](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#test-the-sso-connection)
6. [Verify the domains](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#verify-the-domains)
7. [Enable the SSO connection](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#enable-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.
>
> -   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.

> [!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 SSO 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 **SAML**.
3. In the **Add SAML connection** dialog, enter up to 50 email domains 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. Depending on your identity provider, you'll need some of these when you register Sitecore Cloud Portal with them.

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

    Here's one example using Ping Identity.

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

    Your IdP requires either of the following:

    - *Service provider metadata URL*.
    - *Audience URI* (also called service provider sign-on callback, post-back URL, or callback URL) and *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 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.

    Here's an example of how to do this, using Ping Identity.

2. Navigate to the [Sitecore Cloud Portal SSO page](https://portal.sitecorecloud.io/admin/sso), find the SSO connection you created earlier, and click **Configure**.
3. In **Step 2: Add the identity provider metadata**, select the metadata type and then, in the field provided, paste the IdP metadata.

    > [!important]
    > SAML certificates expire over time. Make sure you [renew and update your certificates](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on/update-a-saml-certificate.html "Update a SAML certificate") to ensure uninterrupted use of your connections.

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*](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on.html#UUID-353e48b4-7e46-eac2-9f54-1eeedd874312_N1707730363698), 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 users 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](https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement)

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](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 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](https://portal.sitecorecloud.io/admin/sso) 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](https://support.google.com/a/topic/1409901).

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:

- Navigate to the [Sitecore Cloud Portal SSO page](https://portal.sitecorecloud.io/admin/sso), locate the SSO connection you want to enable, and 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).

> [!important]
> To ensure uninterrupted access with a SAML connection, make sure you [renew and update](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/portal-administration/authentication/single-sign-on--sso-/configure-saml-single-sign-on/update-a-saml-certificate.html "Update a SAML certificate") your expired or expiring certificates whenever necessary.