Skip to main content
Version: Next

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​

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.

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