Skip to main content

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.