Azure Entra ID SSO – Setting up Sitecore Cloud Portal

Introduction

Now that the Azure Entra ID side is complete, it’s time to bring Sitecore Cloud Portal into the loop.
This article focuses on the Cloud Portal side of the SAML setup — uploading the IdP metadata, creating the SSO connection, mapping incoming claims (like groups) into target claims Cloud Portal adds to tokens, and running the first authentication tests.

Before you begin, make sure you’ve already collected:

• The Federation Metadata XML exported from Azure: /sso/cloudportal-saml-[ENV].xml
• A list of Azure Group Object IDs and test users from your Preparation Checklist

This is the foundation step for SSO across Sitecore services; the same connection will later drive role propagation into XM Cloud.

1. Add a New SSO Connection in Cloud Portal

1. Sign in to Sitecore Cloud Portal as an organisation or cloud administrator.
2. Navigate to Admin → SSO.
3. Click Add SSO Connection → SAML.
4. Name the connection by environment:
   • Azure-SAML-DEV
   • Azure-SAML-UAT
   • Azure-SAML-PROD
5. Add allowed email domains (e.g., yourcompany.com) so only trusted corporate accounts use SSO.

Pro Tip: Keep your connection names consistent across environments — it simplifies configuration, logging, and certificate management.

2. Upload Federation Metadata

1. Choose Upload IdP Metadata.
2. Select your exported XML: [Cloud Portal Metadata File].
3. Save.

Cloud Portal parses and displays the IdP Issuer, SSO URL, and Certificate.
Double-check these against Azure’s Enterprise Application → Single sign-on → SAML pane to confirm they match.

If you see an error parsing the XML, re-download the metadata from Azure — older cached versions often contain outdated certificates.

3. Claims Mapping for Role Propagation

Cloud Portal can transform IdP claims into new claims attached to the issued Sitecore access token.
This is where you bridge Azure group membership to Sitecore roles by generating an xmc_role claim.

3.1 Design your mapping

Create a mapping table per environment:

Why xmc_role?
The target claim name is arbitrary — xmc_role is a common convention since it’s later referenced in XM Cloud role mappings.
Cloud Portal automatically prefixes it with your SSO Connection ID during token issuance, e.g.:

xmc-connection-12345.xmc_role

3.2 Configure mapping in Cloud Portal UI

1. Go to Claims Mapping in your SSO connection.
2. Click Add Mapping.
3. Add a Source Claim:
   • Name: groups
   • Value (Regex): match the group Object ID (e.g., ^00000001-0001-0001-0001-000000000001$)
4. Add a Target Claim:
   • Name: xmc_role
   • Values: sitecore\\Administrator
5. Save the mapping and repeat for each group/role.

3.3 JSON representation (optional via API)

If you prefer to define mappings via JSON configuration (for automation or documentation):

{
  "claimsMapping": [
    {
      "sourceClaims": [
        { "name": "groups", "value": "^00000001-0001-0001-0001-000000000001$" }
      ],
      "targetClaims": [
        { "name": "xmc_role", "value": "sitecore\\Administrator" }
      ]
    },
    {
      "sourceClaims": [
        { "name": "groups", "value": "^00000001-0001-0001-0001-000000000001$" }
      ],
      "targetClaims": [
        { "name": "xmc_role", "value": "sitecore\\Author" }
      ]
    }
  ]
}

Role Mapping Pro Tip: Claims Mapping in Cloud Portal — you add source claims (from the IdP) and target claims (added by Cloud Portal to ID/access tokens). Target claim names are arbitrary (e.g., xmc_role). Source claim values can use regex; values must be strings or arrays; up to 20 source claims per mapping; and target claim names are prefixed with the SSO connection ID at issue time.

Official documentation:

• Sitecore Cloud Portal – Claims Mapping
• Configure SSO Connections in Cloud Portal

4. Testing SSO and Token Claims

Once mapping is saved:

1. Sign out of Cloud Portal.

2. Sign in again — it should redirect to Azure Entra ID.

3. Use your test accounts:

   • [admin-test@yourcompany.com]
   • [editor-test@yourcompany.com]

4. Confirm:

   • The login flow completes successfully.

   • The token now includes your prefixed target claim:

     "xmc-connection-12345.xmc_role": ["sitecore\\Administrator"]
     

Hot Tip – Token Inspection: Cloud Portal doesn’t always show the full token. To verify claims, copy the Bearer token from your browser’s Network tab (Authorization: Bearer ...) and paste it into jwt.ms for decoding. Sometimes the token appears in the UI under “System Information” — otherwise you must capture it from the network traffic.

5. Troubleshooting Role Mapping

Validate

By this stage, you should have:

• Working SAML trust between Azure Entra ID and Sitecore Cloud Portal
• Valid token inspection showing your xmc_role claim
• A functional base for role propagation into XM Cloud

Summary

You’ve:

1. Created a SAML connection in Cloud Portal
2. Uploaded Azure metadata
3. Configured claims mapping with target xmc_role claims
4. Tested SSO and verified the token
5. Prepared for downstream XM Cloud role mapping

In the next article, we’ll walk through how to setup Content Hub, configure the SAML connection there, and conduct validation checks.