v4.x to v5.x (IIS)

This page details the upgrade process for Cinchy v4.x to v5.x on IIS.

Upgrading on IIS (v4 to v5+)

Warning: If you are upgrading from Cinchy v5.1 or lower to Cinchy v5.2** or higher, please see the Cinchy Upgrade Utility and follow the directives on that page. This process can be run when upgrading your IIS v4 instance to any v5+ instance

If you are upgrading to 5.4+ on an SQL Server Database, you will need to make a change to your connectionString in steps 3.2.2 and 3.3.2. 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"

Prerequisites

Follow this guide to take a backup of your database.
Extract the new build for the version you wish to upgrade to.

Update the CinchySSO appsettings.json

Open the C:\CinchySSO\appsettings.json file in a text editor and update the values below.

AppSettings

Under AppSettings section, update the values outlined in the table.
Wherever you see <base url> in the value, replace this with the actual protocol (HTTP or HTTPS) and the domain name (or IP address) you plan to use.

Ex:. if you're using HTTPS with the domain app.cinchy.co, then <base url> should be replaced with https://app.cinchy.co

Key Value

Key	Value
CinchyUri	<base url>
CertificatePath	Adjust the certificate path to point to the CinchySSO v5 folder. C:\CinchySSO\cinchyidentitysrv.pfx
StsPublicOriginUri	Base URL used by the .well-known discovery. If left blank will match the request URL. /cinchysso
CinchyAccessTokenLifetime	Duration for the Cinchy Access Token. This determines how long a user can be inactive until they need to re-enter their credentials. It defaults to `0.00:30:00`
DB Type	Set this to "TSQL"

CinchyUri

CertificatePath

Adjust the certificate path to point to the CinchySSO v5 folder. C:\CinchySSO\cinchyidentitysrv.pfx

StsPublicOriginUri

Base URL used by the .well-known discovery. If left blank will match the request URL.

/cinchysso

CinchyAccessTokenLifetime

Duration for the Cinchy Access Token. This determines how long a user can be inactive until they need to re-enter their credentials. It defaults to 0.00:30:00

DB Type

Set this to "TSQL"

4.18.0+ includes session expiration based on the CinchyAccessTokenLifetime. For the default of 0.00:30:00, this means that if you have been inactive in Cinchy for 30 minutes, your session will expire and you will need to log in again.

SSO values

The values below are only required for SSO, otherwise leave them as blank.

Key Value

Key	Value
SAMLClientEntityId	Client Entity Id
SAMLIDPEntityId	Identity Provider Entity Id
SAMLMetadataXmlPath	Identity Provider metadata XML file path
SAMLSSOServiceURL	Configure service endpoint for SAML authentication
AcsURLModule	This parameter is needs to be configured as per your SAML ACS URL. For example, if your ACS URL looks like this - `https:///CinchySSO/identity/AuthServices/Acs`, then the value of this parameter should be "/identity/AuthServices"

SAMLClientEntityId

Client Entity Id

SAMLIDPEntityId

Identity Provider Entity Id

SAMLMetadataXmlPath

Identity Provider metadata XML file path

SAMLSSOServiceURL

Configure service endpoint for SAML authentication

AcsURLModule

This parameter is needs to be configured as per your SAML ACS URL. For example, if your ACS URL looks like this - https:///CinchySSO/identity/AuthServices/Acs, then the value of this parameter should be "/identity/AuthServices"

Connection String

In order for the application to connect to the database, the "SqlServer" value needs to be set.

If you are upgrading to 5.4+ on an SQL Server Database, you will need to make a change to your connectionString. 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"

Ensure your database type is set to TSQL.

Find and update the value under the "ConnectionStrings" section:

SQL Server Authentication Example:

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

SQL Server Windows Authentication Example:

"SqlServer" : "Server=MyServer;Database=Cinchy;Trusted_Connection=True;Connection Timeout=30;Min Pool Size=10;"

External identity claim section

Under the "ExternalIdentityClaimSection" section you'll see the following values.

These values are used for SAML SSO. If you aren't using SSO, keep these values as blank

Key	Value
ExternalIdentityClaim > FirstName > ExternalClaimName
ExternalIdentityClaim > LastName > ExternalClaimName
ExternalIdentityClaim > Email > ExternalClaimName
ExternalIdentityClaim -> MemberOf -> ExternalClaimName

Key

Value

ExternalIdentityClaim > FirstName > ExternalClaimName

ExternalIdentityClaim > LastName > ExternalClaimName

ExternalIdentityClaim > Email > ExternalClaimName

ExternalIdentityClaim -> MemberOf -> ExternalClaimName

Serilog

"Serilog" has a property that allows you to configure where it logs to. In the below code, update the following:
1. "Name" must be set to "File" so it writes to a physical file on the disk.
2. "Path" must be set to the file path to where you want it to log.

  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System.Net": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "C:\\CinchyLogs\\Cinchy\\log.json",
          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
        }
      }
    ]
  }

Update the Cinchy appsettings.json

Navigate to C:\Cinchy
Delete the appsettings.Development.json
Navigate to the appsettings.json file and update the following properties:

1.3.1 AppSettings

Key	Value
StsAuthorityUri	This should match your Cinchy SSO URL
UseHttps	This is "false" by default.
DB Type	Set this to "TSQL"

Key

Value

StsAuthorityUri

This should match your Cinchy SSO URL

UseHttps

This is "false" by default.

DB Type

Set this to "TSQL"

Connection String

In order for the application to connect to the database, the "SqlServer" value needs to be set.

If you are upgrading to 5.4+ on an SQL Server Database, you will need to make a change to your connectionString in steps . 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"

Ensure your database type is set to TSQL

Find and update the value under the "ConnectionStrings" section:

SQL Server Authentication Example:

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

SQL Server Windows Authentication Example:

"SqlServer" : "Server=MyServer;Database=Cinchy;Trusted_Connection=True;Connection Timeout=30;

1.3.3 Serilog

"Serilog" has a property that allows you to configure where it logs to. In the below code, update the following:
- "Name" must be set to "File" so it writes to a physical file on the disk.
- "Path" must be set to the file path to where you want it to log.

  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System.Net": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "C:\\CinchyLogs\\Cinchy\\log.json",
          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
        }
      }
    ]
  }

You can also use an alternative setting if you want to have rolling log files with retention settings by adding in the following parameters:

          "preserveLogFilename": true,
          "shared": "true",
          "rollingInterval": "Day",
          "rollOnFileSizeLimit": true,
          "fileSizeLimitBytes": 100000000,
          "retainedFileCountLimit": 30,

Your full "Serilog" property, if you choose to use the alternative settings, would look like this, inputting your own variables as required:

"Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System.Net": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "C:\\CinchyLogs\\Cinchy\\log.txt",
          "preserveLogFilename": true,
          "shared": "true",
          "rollingInterval": "Day",
          "rollOnFileSizeLimit": true,
          "fileSizeLimitBytes": 100000000,
          "retainedFileCountLimit": 30,
          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
        }
      }
    ]
  }

Configure the IIS Manager and running your upgrade

Open your Internet Information Services (IIS) Manager.
Navigate to Connections > Sites.
Right click on the Cinchy site and select Manage Application > Advanced Settings.
Change the Cinchy folder path to that of the version you're deploying.
Right click on the CinchySSO site and select Manage Application > Advanced Settings
Ensure that both Applications Pools for Cinchy and CinchySSO have their .NET CLR Versions set to No Managed Code.
Change the Cinchy SSO folder path to that of the version you're deploying.
Execute the following command:

iisreset -stop

Execute the following command:

iisreset -start

Open your Cinchy URL in your browser.

Because Cinchy v5 creates new tables and assets in the background upon initialization, this first startup may take longer to fully load than usual.

Ensure that you can log in.

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

Previousv4.21 (IIS)Nextv5.1 (IIS)

Last updated 1 year ago