Introduction

Cortex can be configured to connect to a database using Microsoft SQL Server, PostgreSQL, or SQLite. Microsoft SQL Server is recommended.

For everything that can be configured within Cortex, you will need to specify a "Cortex" connection string in your appsettings.json configuration file.

If you're using Cortex for Cherwell, you will need to specify a "Default" connection string, pointing to your Cherwell database, in addition to the "Cortex" connection string.

Constructing a Connection String

Cortex accepts a standard .NET connection string, which is a series of semicolon-separated key-value pairs. The official microsoft documentation and these examples can be helpful, but a valid Cortex connection string tends to look like the following:

server=server-hostname,1433;uid=username;password=the-password;database=Cherwell;MultipleActiveResultSets=true

Required settings

• server - the hostname/FQDN and port of a SQL Server instance on another machine, or the name of a named instance on the local machine
• Authentication (mirrors "Database Login Account Credentials" here. Your DBA might know which option is correct; if you're unsure, please ask us)
  • If you use SQL Authentication (this is recommended)
    • uid or user id - the SQL username to connect with
    • password - the password to use to connect
  • If you use Windows Authentication (this is prevalent in high-security environments, but requires additional IIS configuration; see below)
    • Integrated Security=true
• database or initial catalog - the name of the database that holds your Cherwell data
• MultipleActiveResultSets - this MUST be true

Alternate database engines

By default, all connection strings are treated as Microsoft SQL Server connections. Cortex also supports PostgreSQL and SQLite for the Default/Cherwell data connection and the Cortex data connection, though functionality is limited when using SQLite for the Default/Cherwell data connection (we also don't have a supported migration from MSSQL to SQLite like we do for MSSQL to Postgres).

To indicate that a specific connection string refers to a different database engine, specify the engine option with either postgres or sqlite as the value. For example, the following connection string specifies a Postgres connection:

engine=postgres;server=server-hostname,5432;uid=username;password=the-password;database=Cherwell

Note that aside from server, uid, password, and database, many options are engine-specific. Of note, MultipleActiveResultSets=true is MSSQL-specific and will cause Postgres and SQLite connections to fail.

Windows Authentication (for your SQL Server connection)

warning

Using Windows Authentication for the SQL Server connection affects only the SQL Server connection. User authentication to Cortex still has to be configured separately via Open ID Connect or SAML.

warning

This is only applicable when running Cortex on Windows using IIS and connecting to Microsoft SQL Server. This configuration is not supported when using a Postgres or SQLite database.

1. In IIS manager, configure the AppPool that Cortex will run under to use a specific user account. This user account must have access to the SQL server you wish to connect to (typically this is a domain account).

2. Update your SQL connection string to look like the following:

   server=server-hostname,1433;Integrated Security=true;database=Cherwell;MultipleActiveResultSets=true

   Specifically, the uid and password options are omitted and replaced by the Integrated Security option. Depending on your setup, you may also need one or more of the options listed below.

Optional (or "maybe-required" settings)

These settings may be required depending on your specific configuration (or desired security requirements).

• Encrypt - recommended to be true but can be false if the database is on the local machine
• TrustServerCertificate - set to true (i.e. TrustServerCertificate=true) if your certificate is self-signed or doesn't use a trusted chain (see troubleshooting for situations when this might be required)