Skip to main content
Version: Next

SAML with Google Workspace

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

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

Use the following settings:

  1. ACS URL - https://<your cortex url>/saml-assertion
  2. Entity ID - https://<your cortex url>
  3. Start URL - leave blank
  4. All other settings can be left at their defaults.

Download the IdP metadata file before continuing.

Step 2 - Configure Cortex​

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__PublicUri).

  1. Set either Authentication:Saml:IdpMetadataFile or Authentication:Saml:IdpMetadataContents - the path to the IdP metadata XML file, or the contents of that file directly. Only one of these needs to be set.

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

  3. Set Authentication:LookUpBy to Email.

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.

SettingDescription
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