Upgrade Considerations for CSM 10.1.0

Find important information to help plan your upgrade to the latest version of CSM.

Unified SAML Authentication through Cherwell REST API

The information in this section applies to upgrades from earlier than CSM 10.0.0. If you are upgrading to this release from CSM 10.0.0, you can ignore this information.

Starting with CSM 10.0.0, SAML authentication flows through a single endpoint on the Cherwell REST API, no longer through the Cherwell Web Service. This change in endpoint is part of an effort to unify the authentication process of Cherwell applications and services through the Cherwell REST API, simplifying configuration, maintenance, and troubleshooting.

Due to this change in authentication, if SAML is already configured and enabled in your environment, you are presented with the SAML login window during upgrade; however, that login window will display a server error by default. To move forward with the upgrade, either cancel or close the SAML login window and then log in with your internal CSM credentials.

To resolve the server error on the SAML login window after upgrade, the SAML endpoint must be updated in both CSM and the SAML Service Provider.

Update CSM with SAML Endpoint

To assist with the CSM update, the existing SAML web service URL is automatically updated to match the Cherwell REST API URL in the upgrade prompt. For example, if the REST API URL is https://host.domain/CherwellAPI/api/, the SAML web service URL will be updated to https://host.domain/CherwellAPI (without the /api at the end of the path).

If you cancel the prompt for the REST API URL during upgrade, and then later set the URL either in the Security section of CSM Administrator or through the command line, you must manually configure the SAML Service Provider web service URL in the SAML Settings window in CSM Administrator in the following format: https://host.domain/CherwellAPI. For more information, see Configure SAML as a CSM Service Provider.

Update SAML Service Provider Assertion Endpoint

After the SAML Service Provider web service URL is updated in CSM, the SAML assertion endpoint must be updated in your SAML Service Provider. The endpoint is the URL to the Cherwell web service page that is used as the assertion consumer. This URL is the domain followed by CherwellAPI/saml/assertion. For example, if the previous URL is https://www.mycompany.com/CherwellService/saml/assertion.aspx, the new URL should be changed to https://www.mycompany.com/CherwellAPI/saml/assertion.
The Cherwell REST API endpoint is the only required endpoint. If the Cherwell Web Service endpoint still exists, simply delete it, as it is no longer supported. Also, file extensions such as .cshtml are no longer valid.

For more information, see Manually Add CSM as a Relying Party.

Upgrade Considerations for Earlier Versions