v5.6 (IIS)

1. Upgrading on IIS

The following process can be run when upgrading any v5.x instance to v5.6 on IIS.

Warning: If you are upgrading from Cinchy v5.1 or lower to Cinchy v5.6, you must first run a mandatory process (Upgrade 5.2) using the Cinchy Utility and deploy version 5.2.

If you are upgrading from Cinchy v5.3 or lower to v5.5+ on an SQL Server Database, you will need to make a change to your connectionString in your SSO and Cinchy appsettings. Adding TrustServerCertificate=True will allow you to bypass the certificate chain during validation.

Ex:

"SqlServer" : "Server=MyServer;Database=Cinchy;User ID=cinchy;Password=password;Trusted_Connection=False;Connection Timeout=30;Min Pool Size=10;TrustServerCertificate=True"

Warning: If you are upgrading from Cinchy v5.4 or lower to Cinchy v5.6, you must first run a mandatory process (Upgrade 5.5) using the Cinchy Utility and deploy version 5.5.

The upgrade of any version to Cinchy v5.6 requires changes to be made to the App Settings of your Worker/Listener/Connections setup. See section 1.2, step 3, for further details.

1.1 Prerequisites

1. Take a backup of your database.

2. Extract the new build for the version you wish to upgrade to.

3. Download .NET 6.0

1.2 Upgrade Process

1. Merge the following configs with your current instance configs:

   • Cinchy/web.config

   • Cinchy/appsettings.json

   • CinchySSO/appsettings.json

   • CinchySSO/web.config

2. If you are upgrading to 5.6 on an SQL Server Database and did not do so in any previous updates, you will need to make a change to your connectionString in both your SSO and Cinchy appsettings. Adding TrustServerCertificate=True will allow you to bypass the certificate chain during validation.

   Ex:

   "SqlServer" : "Server=MyServer;Database=Cinchy;User ID=cinchy;Password=password;Trusted_Connection=False;Connection Timeout=30;Min Pool Size=10;TrustServerCertificate=True"

3. When upgrading to 5.6, you are required to make the following changes to various appsettings.json files:

CinchySSO\appsettings.json

Navigate to your CinchySSO\appsettings.json file and make the following changes:

• ADD the following value:

  • "StsPrivateOriginUri" - This should be the private base URL used by the .well-known discovery. If left blank will match the request URL. /cinchysso

    "AppSettings": {
      "CinchyUri": "http://localhost",
      "CertificatePath": "C:\\inetpub\\wwwroot\\cinchysso\\cinchyidentitysrv.pfx",
      "CertificatePassword": "",
      "SAMLClientEntityId": "",
      "SAMLIDPEntityId": "",
      "SAMLMetadataXmlPath": "",
      "SAMLSSOServiceURL": "",
      "SAMLEncryptedCertificatePath": "",
      "SAMLEncryptedCertificatePassword": "",
      "SAMLSignCertificatePath": "",
      "SAMLSignCertificatePassword": "",
      "HstsMaxAge": 2592000,
      "HstsIncludeSubDomains": false,
      "HstsPreload": false,
      "SAMLSignCertificateMinAlgorithm": "",
      "SAMLSignCertificateSigningBehaviour": "",
      "AcsURLModule": "",
      "StsPublicOriginUri": "",
      // Add in the below "StsPrivateOriginUri" value. 
      // This should be the private base URL used by the .well-known discovery. 
      // If left blank will match the request URL. /cinchysso
      "StsPrivateOriginUri": "",
      "MaxRequestHeadersTotalSize": 65536,
      "MaxRequestBufferSize": 65536,
      "MaxRequestBodySize": -1,
      "MachineKeyXml": "",
      "DpApiKeyRingPath": "",
      "TlsVersion": "",
      "CinchyAccessTokenLifetime": "7.00:00:00",
      "DataChangeCallbackTimeout": 7,
      "RefreshCacheTimeInMin": 10,
      "DefaultExpirationCacheTimeInMin": 360,
      "DBType": "PostgreSQL"

Cinchy\appsettings.json

Navigate to your Cinchy\appsettings.json file and make the following changes:

• REMOVE the following values:

  • "StsAuthorityUri"

  • "RequireHttpsMetadata"

• ADD the following values:

  • "StsPrivateAuthorityUri" - This should match your private Cinchy SSO URL.

  • "StsPublicAuthorityUri" - This should match your public Cinchy SSO URL.

  • "CinchyPrivateUri" - This should match your private Cinchy URL.

  • "CinchyPublicUri" - This should match your public Cinchy URL.

    "AppSettings": {
    // Add the below "StsPrivateAuthorityUri" value.
    // This should match your private Cinchy SSO URL.
      "StsPrivateAuthorityUri": "",
   // Add the below "StsPublicAuthorityUri" value.
   // This should match your public Cinchy SSO URL. 
      "StsPublicAuthorityUri": "",
   // Add the below "CinchyPrivateUri" value.
   // This should match your private Cinchy URL.
      "CinchyPrivateUri": "",
   // Add the below "CinchyPublicUri" value.
   // This should match your public Cinchy URL.
      "CinchyPublicUri": "",
      "AllowLogFileDownload": false,
      "LogDirectoryPath": "C:\\CinchyLogs\\CinchyWeb",
      "SSOLogPath": "C:\\CinchyLogs\\CinchySSO\\log.json",
      "UseHttps": true,      
      "HstsMaxAge": 2592000,
      "HstsIncludeSubDomains": false,
      "HstsPreload": false,
      "TlsVersion": "",
      "RouteDebuggerEnabled": false,
      "RefreshCacheTimeInMin": 10,
      "DefaultExpirationCacheTimeInMin": 360,
      "DBType": "PostgreSQL",
      "StorageType": "Local", // Local | S3 | AzureBlobStorage
      "MaxRequestBodySize": 1073741824 // 1gb
    }

Worker Directory appsettings.json

Navigate to your appsettings.json file within your Cinchy Worker directory and make the following changes:

• ADD a new section titled "CinchyClientSettings", following the below code snippet as a guide:

{
  "CinchyClientSettings": {
    "Url": "",      // Cinchy Url
    "Username": "", // For Cinchy v4 only, remove otherwise
    "Password": ""  // For Cinchy v5, this should be the password for the user [e-mail]. For v4 this will be the desired user's password.
  },

• REMOVE the following:

  • "AuthServiceDomain"

  • "UseHttps"

Event Listener Directory appsettings.json

Navigate to your appsettings.json file within your Cinchy Listener directory and make the following changes:

• ADD a new section titled "CinchyClientSettings", following the below code snippet as a guide:

  "CinchyClientSettings": {
    "Url": "", // Cinchy Url
    "Username": "", // For Cinchy v4, remove otherwise
    "Password": "" // For Cinchy v5, this should be the password for the user [e-mail]. For v4 this will be the desired user's password.
  }

• REMOVE the following:

  • "StateFileLocation"

  • "Path"

1. Execute the following command:

iisreset -stop 

1. Replace the Cinchy and CinchySSO folders with the new build and your merged configs.

2. Execute the following command:

iisreset -start 

1. Open your Cinchy URL in your browser.

2. Ensure you can log in.

If you encounter an error during this process, restore your database backup and contact Cinchy Support.