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
oruser id
- the SQL username to connect withpassword
- 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
- If you use SQL Authentication (this is recommended)
database
orinitial catalog
- the name of the database that holds your Cherwell dataMultipleActiveResultSets
- this MUST betrue
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)
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.
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.
-
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).
-
Update your SQL connection string to look like the following:
server=server-hostname,1433;Integrated Security=true;database=Cherwell;MultipleActiveResultSets=true
Specifically, the
uid
andpassword
options are omitted and replaced by theIntegrated 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 betrue
but can befalse
if the database is on the local machineTrustServerCertificate
- set totrue
(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)