Sitecore Experience Commerce 10 .0 and 10.1 Compatibility Update for Sitecore XP Identity Server


Description

Sitecore Experience Platform (XP) update releases SXP 10.0 Update-3 and SXP 10.1 Update-2 introduce a new Sitecore Identity Server version 4.1.1, which is based on .NET Core 3.1. These Sitecore XP update releases require minor configuration changes in Sitecore Experience Commerce (XC) to connect to the new Sitecore Identity Server version.

For updating the existing deployments, the Sitecore XC file Sitecore.Commerce.IdentityServer.Host.xml must be replaced or manually updated.

Apart from this Sitecore XC configuration change, there are no code changes required within Sitecore XC for compatibility with these Sitecore XP update releases, therefore there are no new corresponding Sitecore XC update releases.

Updated Experience Commerce Identity Server Host file

The updated Sitecore.Commerce.IdentityServer.Host.xml file is located within the Sitecore.Identity.Config.Commerce.[release].scwdp.zip package, available for download here:

Installation steps for on-premise deployments – with out-of-box Host File

If the Sitecore.Commerce.IdentityServer.Host.xml file has not been modified in your deployment, for example for a new Sitecore XC deployment, then deploy the updated Sitecore.Identity.Config.Commerce.[release].scwdp.zip package to the location where you host your release .zip packages.

Installation steps for on-premise deployments – with modified Host File

If the Sitecore.Commerce.IdentityServer.Host.xml file has already been modified in your deployment, then follow the manual instructions below to merge the changes into your customized file. If you follow these manual instructions, then the updated Sitecore.Commerce.IdentityServer.Host.xml file (provided earlier in this document) is not needed, other than as a reference.

  1. Find the original Sitecore.Commerce.IdentityServer.Host.xml file in your original Identity Server installation.
  2. Copy the Sitecore.Commerce.IdentityServer.Host.xml file from the original Identity Server and install it under \config\production.
  3. Make the following changes:
    Add as follows: 
          <ApiScopes>
            <EngineApiScope>
              <Name>EngineAPI</Name>
              <DisplayName>Commerce Engine API</DisplayName>
            </EngineApiScope>
            <PostmanApiScope>
              <Name>postman_api</Name>
              <DisplayName>Postman API</DisplayName>
            </PostmanApiScope>
          </ApiScopes>
    Add the following bolded <Scopes> under existing <ApiResources>
          <ApiResources>
            <EngineApiResource>
              <Name>EngineAPI</Name>
              <DisplayName>Engine API</DisplayName>
              <ApiSecrets>
                <ApiSecret1>secret</ApiSecret1>
              </ApiSecrets>
              <UserClaims>
                <UserClaim1>name</UserClaim1>
                <UserClaim2>email</UserClaim2>
                <UserClaim3>role</UserClaim3>
              </UserClaims>
              <Scopes>
                <Scope1>EngineAPI</Scope1>
              </Scopes>
            </EngineApiResource>
            <PostmanApiResource>
              <Name>postman_api</Name>
              <DisplayName>Postman API</DisplayName>
              <ApiSecrets>
                <ApiSecret1>secret</ApiSecret1>
              </ApiSecrets>
              <UserClaims>
                <UserClaim1>name</UserClaim1>
                <UserClaim2>email</UserClaim2>
                <UserClaim3>role</UserClaim3>
              </UserClaims>
              <Scopes>
                <Scope1>postman_api</Scope1>
              </Scopes>
            </PostmanApiResource>
          </ApiResources>
  4. Copy the changed Sitecore.Commerce.IdentityServer.Host.xml file to the new Identity Server install under \config\production.
  5. If the new Identity Server URL has been changed, you need to update the URL in the following places to replace the existing references in Sitecore XC:
    • Commerce Engine: Change "SitecoreIdentityServerUrl" in wwwroot\config.json.
    • BizFX: Change "IdentityServerUri" in assets\config.json.
    • Postman: Change "SitecoreIdServerHost" variable under existing environments (for example, Habitat Environment).

Installation steps for container deployments

The Identity Server image names from Sitecore XP 10.0 Update-3 and Sitecore XP 10.1 Update-2 have been changed with the "IS6" suffix. New versions of the Sitecore Commerce Container SDK have been released with the reference to new Sitecore XP Identity Server names. Follow the steps below to rebuild your Sitecore Commerce container images:

  1. Download the applicable new version of the Sitecore Commerce Container SDK:

    SXC Sitecore Commerce Container SDK 10.0.1.60238.1126

    SXC Sitecore Commerce Container SDK 10.1.0.70162.20171

  2. Download the new Sitecore.Identity.Config.Commerce.[release].scwdp.zip package (provided earlier in this document).
  3. Follow the guidance in the topic "Workflow for creating custom Commerce container images" to rebuild images. Make sure before executing PrepContainerbuild.ps1 (under "Get content for container images" section), you replace the original Sitecore.Identity.Config.Commerce.x.x.x.scwdp.zip inside the release package with the file you downloaded from the previous step.
  4. Deploy and test your custom containers.