Skip to main content

Enabling SSO for Cortex Self-Managed

Cortex Self-Managed comes with support for SSO out of the box with any auth provider that supports OIDC.

Your self-managed instance is auth-less out of the box, to allow for easy iteration. Once you're ready to set up SSO, just adding the right configurations will immediately trigger the SSO gate.

Basic setup​

All providers require essentially the same steps to set up SSO.

  1. Create an app in your SSO provider to be used for Cortex.
  2. Set the redirect URL to be http(s)://[CORTEX BACKEND HOST]/login/oauth2/code/[PROVIDER], for example, on our Cortex Cloud, the Okta URL would be https://api.getcortexapp.com/login/oauth2/code/okta. See below for other PROVIDER values: a. Amazon SAML - amazon b. Azure Active Directory - azuread c. Google SSO - google d. JumpCloud SAML - jumpcloud e. Okta SSO - okta f. Generic OIDC - auth0
  3. Copy the Client ID, Client Secret, and Issuer URI. (See individual provider sections below for details).
  4. Navigate to Settings → OpenID Connector in your Cortex workspace.
  5. Select your provider and add the ID, Secret, and Issuer URI.
  6. If you log out and try to log back in, you'll now hit the SSO screen!
tip

If the Cortex settings screen doesn't include the provider you're using, just select any of the providers in the dropdown.

Change the redirect URL in step 2 to include the provider you chose, like okta, even if your provider is not the same.

Under the hood, this is using standard OIDC and should work automatically!

Providers​

If you're looking to configure a specific provider, here are some tips for common SSO providers.

Okta​

Okta is fairly simple to set up. Simple create a new app in your Okta admin portal and follow the steps in Basic Setup.

  1. Your Okta Issuer URL will look be [YOUR OKTA URL]/oauth2/default, for example https://dev-123.okta.com/oauth2/default. You must include the /oauth2/default.
  2. In the Cortex dashboard, the OIDC settings are found under OpenID Connector, not Okta. The Okta page is used when setting up Okta as an ownership provider.

Troubleshooting​

If you've borked your instance and are unable to log in to your instance, try the following steps.

  1. If using Okta, make sure that your Issuer URI ends in /oauth2/default, and is not just the Okta domain.

To make changes to your SSO setup after misconfiguring it, you can disable auth again by connecting to the database for your Cortex instance and running DELETE FROM oidc_client_secret_basic_connections;. Refreshing the page will allow you to log back in.