Skip to main content
Version: 3.2

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​

On Windows, the preferred way to set these values is the Cortex System Manager - it writes the same settings to appsettings.json for you and validates them before saving. If Cortex is not running on Windows, or you would rather edit the file directly, use the appsettings.json option instead.

Option 1 - Configure with Cortex System Manager (Windows)​

  1. Open Cortex System Manager. You can find it from the desktop shortcut, or by running Cortex.Config.exe directly from the Cortex installation directory.

  2. Click Authentication....

    Cortex System Manager main window

  3. Set Type to saml. The SAML section appears.

  4. Fill in the SAML section:

    • IdPMetadataFile - the path to the IdP metadata XML file you downloaded from Google Workspace. Use the ... button to browse for it.
    • PublicUri - https://<your cortex url>.

  5. Set LookUpBy to email.

  6. Click SAVE.

Note that Cortex System Manager writes the metadata file path as Authentication:Saml:IdpMetadataFile. If you need to embed the metadata contents directly with Authentication:Saml:IdpMetadataContents, set that in appsettings.json instead.

Option 2 - Edit appsettings.json​

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.

Restart IIS to apply the changes​

Cortex reads these settings when it starts, so the change does not take effect until IIS is restarted:

  • In Cortex System Manager, click Restart IIS at the bottom of the window.
  • In an elevated command prompt, run iisreset.
  • In IIS Manager, recycle the Cortex application pool.

If you edited appsettings.json by hand, save the file before restarting.

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