Skip to main content
Version: Next

Authentication

Cortex supports the following authentication modes.

None

Allow all visitors in as the built-in CSDAdmin user (this user must exist).

Internal

Internal Cortex Authentication with manually created user accounts.

Guest / Demo User Mode

Let unauthenticated visitors demo the application as a nominated user, with Internal or SAML authentication.

Windows Authentication via IIS

Supported, but SAML with ADFS or Azure AD is strongly recommended instead.

SAML using ADFS

SAML using Azure AD (Entra ID)

SAML using Okta

SAML using Google Workspace

OpenID Connect using Keycloak

Where the authentication settings live​

Cortex reads its authentication settings when it starts, and you can set them in either of two places:

  • In Cortex - Admin → System Settings → Authentication. The screen becomes read-only when appsettings.json already sets Authentication:Type, and says so, so a deployment managed by the file cannot be changed from the browser by accident.
  • On the server - the Cortex System Manager (Windows) writes the same values into appsettings.json and validates them before saving, or you can edit appsettings.json directly. Cortex reads these at startup, so IIS must be restarted to apply them.

The screen offers every authentication type Cortex supports - none, internal, windows, saml, keycloak and oidc - together with the lookup mode (username or email address), the demo user used by guest mode, and automatic redirection. Depending on the type it also takes:

  • OpenID Connect and Keycloak - authority, client ID, client secret and identifier claim.
  • SAML - the IdP metadata URI, or an IdP metadata file when the metadata is kept on the server; the public URI; the certificate file and password; and the certificate validation mode (None, PeerTrust, ChainTrust or PeerOrChainTrust).

The Authentication screen also has a Show Password field for accounts (not using Internal authentication) option, which is shown whenever the effective authentication type is not internal:

  • Enabled - the Password column is available in Admin → Users, so you can set or rotate an account's local password even though sign-in is handled elsewhere (for example by SAML, Windows Authentication or OpenID Connect). This is the supported way to set a local password for the default admin account without switching the authentication type or deleting the account.
  • Disabled (default) - the Password column is hidden for those authentication types.
  • With internal authentication the Password column is always shown and this option does not appear.
note

appsettings.json stays authoritative for the authentication type, and the Authentication screen becomes read-only when the file sets it. For SAML certificate validation, a mode other than None in appsettings.json takes precedence over the in-app setting; None is treated as unset, so Cortex uses the in-app setting instead.

If no authentication type is configured​

Cortex resolves the effective authentication type in this order:

  1. Authentication:Type in appsettings.json, when it names a type.
  2. The type selected in Cortex - Admin → System Settings → Authentication.
  3. internal - the fallback when no type is named in either place.

An installation that names no authentication type anywhere therefore requires users to sign in with internal accounts, rather than running with authentication off.

When you choose the type in the Cortex System Manager, an appsettings.json that names no type appears in the Type list as Unset - Web UI. Saving that selection writes no Type key at all, which leaves the choice to Cortex instead of pinning a type from the file.

Other authentication services, like Okta, Azure AD, and Shibboleth, are likely to work (with either SAML or OpenID Connect), but have not been tested. If you have questions about a particular authentication scenario, please contact us. If it worked with Cherwell, it likely works with Cortex, but may require additional (undocumented) configuration.

If you use SAML authentication, you may be interested in configuring automatic redirection to the SAML provider. By default, users will see a screen showing that they are currently logged out and need to click to be redirected to the SAML authentication provider, but there is a setting available to have users automatically redirected instead.