Skip to main content
Version: Next

SAML with Azure AD (Entra ID)

Prerequisites​

  • Cortex must be running at a stable URL that will not change. This URL is used as part of the SAML configuration and 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 Enterprise Application in Azure AD​

  1. In Azure AD, create a new Enterprise Application.

    • Enter Cortex for the name.
    • Choose the option to integrate an application not found in the gallery.

  2. Once created, go to Manage > Single Sign-on and choose SAML. Under section 1, set:

    • Identifier (Entity ID) - your Cortex URL. This should include https://.
    • Reply URL - <your cortex url>/saml-assertion
    • Leave all other fields blank (unless you are using IdP-initiated SAML, in which case enter your Cortex URL under Sign on URL).

  3. Copy the App Federation Metadata URL from section 3. You will use this as the IdPMetadataUri value in Cortex.

  4. Assign users or groups to the enterprise app. This controls who is allowed to authenticate to Cortex at all. Note: this is separate from the security group permissions that control what data a user can access inside Cortex.

Step 2 - Configure Cortex​

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

{
  "Authentication": {
    "Type": "saml",
    "Saml": {
      "IdPMetadataUri": "https://login.microsoftonline.com/YOUR-TENANT-ID/federationmetadata/...",
      "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: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