Upgrade Identity Server

Prepare the Docker Compose specification files

Update the specification files to use Sitecore Identity Server 9.0.X.

Starting with Identity Server 8.0, the name of container image has been changed from sitecore-idX to sitecore-identity. Its tag is now aligned with the version of the Sitecore Identity Server itself, for example: sxp/sitecore-identity:9.0-ltsc2022.

For Sitecore XP 10.0 only, update the healthcheck probe for the 'id' service in the docker-compose.yml file from:

["CMD", "powershell", "-command", "C:/Healthchecks/Healthcheck.ps1"]

to:

["CMD", "pwsh", "-command", "C:/Healthchecks/Healthcheck.ps1"]

Encrypted Communication with SQL Server

Starting from version 8.0, Sitecore Identity Server requires encrypted communication with SQL Server by default. This change is due to the adoption of a newer version of Microsoft.Data.SqlClient that enforces stricter security measures, as described in Microsoft’s Breaking changes in EF Core 7.0 article.

Follow these steps to configure and implement an encryption certificate:

1. Obtain certificates for the encryption. Prepare two certificate files:

   • mssql.pfx - contains the private key and public certificate that will be used by SQL Server for encryption.
   • RootCA.crt - public certificate of the certification authority (CA) that issued the encryption certificate.

   These must meet specific requirements to be used with SQL Server. For more information, refer to the Certificate requirements for SQL Server article.

2. Configure an encryption certificate for the SQL Server deployment. If your container deployment is using the mssql-developer image, you can use the latest version of this image that supports configuring the encryption certificate. Perform the following:

   1. Pull the latest version of the mssql-developer image, by running the following command:

      docker pull scr.sitecore.com/sxp/nonproduction/mssql-developer:2022-<version>

   2. Mount the certificate for encryption as a c:\certs\mssql.pfx file into the SQL Server container.
   3. Set the following SQL Server container environment variables:

      • NAME – name of the SQL Server instance.

      • TLS_CERTIFICATE_PASSWORD – password for the certificate file

      If your deployment uses an image of the SQL Server with another name, create a custom image on top of the original one. It should perform an initialization similar to that of a stand-alone SQL Server. For more information, refer to Microsoft’s Secure SQL Server Linux containers article.

3. Ensure the certificate is trusted in the Identity Server deployment. Mount the CA certificate that was used to issue the encryption certificate as a C:\certs\RootCA.crt file into the Identity Server container, in the docker-compose.yml file.

   For example, if the certificate file is stored in the compose/<version>/<topology>/id/certs folder, then the configuration should be:

   
   id:
     ...
     volumes:
       - type: bind
         source: .\id\certs
         target: c:\certs
   

4. [Optional] Enforce Sitecore Identity Server to use an encrypted connection to SQL Server. In the compose/<version>/<topology>/docker-compose.yml file, update the value of the Sitecore_Sitecore__IdentityServer__SitecoreMemberShipOptions__ConnectionString environment variable by appending the parameters: 

   ...;Encrypt=true;TrustServerCertificate=false;

Alternatively, it is possible to use default self-signed encryption certificates which SQL Server generates at startup if custom certificates are not provided. This may simplify the installation process for non-production deployments, but this approach is not recommended for production environments.

To accommodate this configuration in Sitecore Identity Server, it is sufficient to apply one of the following configuration changes to Docker Compose configuration:

1. To disable encryption: Update the value of the Sitecore_Sitecore__IdentityServer__SitecoreMemberShipOptions__ConnectionString environment variable by appending the parameter:

   ...;Encrypt=false;

2. Enable encryption but disable certificate trust validation. Update the value of the Sitecore_Sitecore__IdentityServer__SitecoreMemberShipOptions__ConnectionString environment variable by appending the parameter:     

   ...;Encrypt=true;TrustServerCertificate=true;

For Sitecore XP 10.0 only, the only available option is to use the default self-signed encryption certificates generated by SQL Server.

Run upgrade script on security database

To run the upgrade script on security database:

1. Unpack the Sitecore.IdentityServer.UpgradeScripts.9.0.zip file. The package contains a database upgrade script CMS_security_IdentityServer.sql. The script applies changes to the Core database that are required for Sitecore Identity Server 9.0.

2. Execute the upgrade scripts against the Core database used in the deployment. For example, it can be done in the following way:

   
   docker cp ./CMS_security_IdentityServer.sql <mssql container>:/CMS_security_IdentityServer.sql
   docker exec -it <mssql container> sqlcmd -S localhost -U <database username> -P '<database password>' -d <security database> -i ./CMS_security_IdentityServer.sql
   

You should now be able to log in to the CM server and log out without any errors displayed.