Skip to main content
Version: 3.2

SAML with Okta

Prerequisites​

  • Cortex must be running at a stable URL that will not change. This URL is referred to throughout this page as <your cortex url> and in configuration as PublicUri.
  • Cortex should be running on HTTPS with a valid certificate.

Step 1 - Configure Cortex as an Application in Okta​

  1. In Okta, go to Applications > Applications and click Create App Integration. Select SAML 2.0 and click Next.

    Create a new app integration

  2. Enter Cortex as the application name and click Next.

    Step 1 - App name

  3. Enter the following values and click Next:

    • Single sign-on URL - <your cortex url>/saml-assertion
    • Audience URI (SP Entity ID) - <your cortex url>
    • Name ID format - EmailAddress

    Step 2 - SAML settings

  4. Complete step 3 at your discretion (this is optional feedback for the Okta team) and click Finish.

  5. On the application settings page, go to the Sign On tab and copy the Metadata URL. You will use this as IdPMetadataUri in the next section.

    Step 3 - Metadata URL

  6. Assign users or groups to the application.

    Application assignments

Step 2 - Configure Cortex​

On Windows, the preferred way to set these values is the Cortex System Manager - it writes the same settings to appsettings.json for you and validates them before saving. If Cortex is not running on Windows, or you would rather edit the file directly, use the appsettings.json option instead.

Option 1 - Configure with Cortex System Manager (Windows)​

  1. Open Cortex System Manager. You can find it from the desktop shortcut, or by running Cortex.Config.exe directly from the Cortex installation directory.

  2. Click Authentication....

    Cortex System Manager main window

  3. Set Type to saml. The SAML section appears.

  4. Fill in the SAML section:

    • IdPMetadataUri - the Okta metadata URL you copied in Step 1.
    • PublicUri - <your cortex url>.
    • CertificateValidationMode - None, unless your environment requires a stricter mode.

  5. If Okta identifies users by email address, set LookUpBy to email.

  6. Click SAVE.

Option 2 - Edit appsettings.json​

In appsettings.json, set the authentication type to saml:

{
  "Authentication": {
    "Type": "saml",
    "Saml": {
      "IdPMetadataUri": "https://your-okta-domain/app/your-app-id/sso/saml/metadata",
      "PublicUri": "https://your-cortex-url",
      "CertificateValidationMode": "None"
    }
  }
}

You will also likely need to set LookUpBy to Email in the Authentication block. Try without it first - if you appear logged in but have no access to any Business Objects and see an email address in the bottom-left corner, add this setting.

Restart IIS to apply the changes​

Cortex reads these settings when it starts, so the change does not take effect until IIS is restarted:

  • In Cortex System Manager, click Restart IIS at the bottom of the window.
  • In an elevated command prompt, run iisreset.
  • In IIS Manager, recycle the Cortex application pool.

If you edited appsettings.json by hand, save the file before restarting.

Additional Options​

Start with the setup above, then change one option at a time and re-test. Depending on the type of misconfiguration, you may see feedback in the UI or in the logs.

note

The following options are listed in Block:SubBlock:Setting format. In appsettings.json this maps to nested JSON blocks. In environment variables, replace : with __ (for example, Authentication__Saml__ForceAuthn).

SettingDescription
Authentication:LookUpBySet to Email if your IdP identifies users by email address
Authentication:IdentifierClaimThe name of the claim your IdP sends to identify users - could be emailAddress or a URL-style claim
Authentication:Saml:CertificateValidationModeSet to None to disable certificate validation entirely
Authentication:Saml:RevocationModeControls whether the IdP's certificate is checked for expiry and revocation
Authentication:Saml:ForceAuthnForces the user to re-enter credentials on the IdP login screen even if they already have an active session. Equivalent to Cherwell's "Authentication: Force" setting.

Troubleshooting​

If login fails or users are not recognised, see:

Administration Troubleshooting