SAML with Azure AD (Entra ID)

Prerequisites

• Cortex must be running at a URL that won't change. You'll be using this URL as part of the configuration; Azure AD will assume this is where authentication requests will be coming from and where authentication responses should be redirected. (In the instructions below, this is referred to as <your cortex url> and in configuration as PublicUri)
• Cortex should be running on an HTTPS site with a valid certificate.

Configure Cortex as an Enterprise Application

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

   • Provide "Cortex" for the name
   • Choose the option to integrate an application not found in the gallery

2. Once the application is created, choose "Single Sign-on" under "Manage", then choose "SAML". Update the following items under the box marked "1":

   • Use the URL you'll use to access Cortex (referred to as <your cortex url> throughout this page) as the "Identifier (Entity ID)". This should include the https://.
   • Use <your cortex url>/saml-assertion as the "Reply URL"
   • Leave all other options blank (if you plan to use IdP-initiated SAML, enter your cortex url under "Sign on URL")

3. Copy the "App Federation Metadata URL" in the box labeled "3". This will be entered for the setting in Cortex marked IdpMetadataUri.

Configure Cortex to find the IdP

1. In appsettings.json, set the Authentication type to "saml":

   {
     // ...
     "Authentication": {
       "Type": "saml",
       // ...
     }
   }

2. In the "Saml" settings block (in the "Authentication" block), set values for the following settings:

   • IdPMetadataUri - the URI of the IdP's metadata (copied from step 3 in the last section)
   • PublicUri - the publicly accessible URL of the server running Cortex (<your cortex url>)
   • CertificateValidationMode - "None"

3. Likely, you'll also need to set the LookUpBy setting in the main Authentication block to have the value "Email". Try without; if you appear logged into Cortex but with no access to any business objects (and you see an email address in the bottom left corner), add this setting.

Additional Options

Depending on your specific configuration, you may or may not need the below options. Start by following the setup above, then changing a single option at a time, then re-testing. Depending on the type of misconfiguration (or "incomplete" configuration), you may see feedback in the UI, or in the logs.

note

For simplicity, the following options are listed in Block:SubBlock:Setting format. If you're configuring Cortex by modifying appsettings.json, that means you'll set the Setting in the JSON block SubBlock within the JSON block Block, e.g.:

{
   "Block": {
      "SubBlock": {
         "Setting": "value"
      }
   }
}

If you're configuring Cortex via environment variables, you'll set an environment variable named Block:SubBlock:Setting in Powershell or Block__SubBlock__Setting in any environment (that is, replacing the single colon with two underscores).

• Authentication:LookUpBy - either "Email" or empty. If your IdP identifies users by email address (do you see an email address in the bottom left Corner when you log into Cortex?), set this to "Email".
• Authentication:IdentifierClaim - the name of the claim that your IdP sends to identify your users. It could be something simple, like emailAddress, or something that looks like a URL. Your IdP documentation might help you figure this out.
• Authentication:Saml:RevocationMode - do you want to verify that the IdP's certificate is unexpired and has not been revoked?
• Authentication:Saml:ForceAuthn - require the user to enter their username and password on the IdP's login screen regardless of whether they are already logged in. This is equivalent to Cherwell's "Authentication: Force" setting.