SAML with Google Workspace

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 Google Workspace

Follow Google's instructions to create a new custom SAML app

Specifically, use the following settings:

1. ACS URL: https://<your cortex url>/saml-assertion
2. Entity ID: https://<your cortex url>
3. Start URL: (blank)
4. All other settings can be left with the default value.

Be sure to download the IdP metadata.

Configure Cortex

note

For simplicity, the configuration options on this page 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).

1. Set either Authentication:Saml:IdpMetadataFile or Authentication:Saml:IdpMetadataContents to be the path to the Idp Metadata XML file or the contents of that file (respectively). Only one of these settings needs to be set.

2. Set Authentication:Saml:PublicUri to https://<your cortex url>.

3. Set Authentication:LookUpBy to Email.

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.

• 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.