Skip to main content
Version: Next

OpenID Connect with Keycloak

This guide covers configuring Cortex to authenticate users via OpenID Connect (OIDC) using Keycloak.

Prerequisites​

  • A Keycloak instance with at least one realm configured

Step 1 - Configure the Keycloak Realm​

  1. In your Keycloak Realm, create a new OpenID Connect client:

    • Set the Client ID to cortex (this must match what you specify in the Cortex config)
    • Optionally add a Name and Description
    • On the next screen, toggle Client Authentication to On - this is required to generate a client secret
    • Set the following URLs:
      • Root URL: https://your-cortex-server/
      • Home URL: https://your-cortex-server/
      • Valid Redirect URIs: https://your-cortex-server/*
      • Valid post logout redirect URIs: +
      • Web Origins: +

  2. Open the Credentials tab for the newly created client and copy the Client Secret.

Step 2 - Configure Cortex​

In appsettings.json, configure the Authentication block with the following settings:

{
  "Authentication": {
    "Type": "keycloak",
    "Authority": "https://your-keycloak-server/realms/your-realm",
    "ClientId": "cortex",
    "ClientSecret": "your-client-secret-here"
  }
}
note

In some older versions of Keycloak, the authority URL uses the path /auth/realms/your-realm instead of /realms/your-realm.

Troubleshooting​

If login fails or users are not recognised, see:

Administration Troubleshooting