Version: 6.4.1

Dex on Cortex

This page provides information about Dex, a provider used for configuring authentication on Cortex.

Starting with Cortex Helm v6.0.0 (alpha) Cortex is using Dex as an identity service to drive single-sign-on (SSO) authentication.

In practical terms this means that Cortex no longer manages identities (username and password combos) internally, this is delegated to Dex and external identity providers (such as LDAP, AD, and GitHub)

Dex Configuration Overview

There are 4 basic steps to configuring Authorization:

  1. Configure the values.yaml (in the dex section) for Dex to communicate with your identity provider. A list of supported providers and links to instructions for configuring those providers is found here(Read the content in the README at this link.)
  2. In the values.yaml (dex section) configure Cortex as the static provider. (instructions are provided below and are commented into the value.yaml override file)
  3. Map your identity provider roles to Cortex groups in a the .cortex.auth.roleMapping section of the values.yaml.
  4. Install Dex - This is packaged as part of the Cortex Fabric Helm chart.

Configure Dex to work with Vault

In the helm chart, the default dex image included is distroless, which is incompatible with vault. Therefore, when utilizing vault, it is necessary to override the image with one that is compatible. This can be achieved by using the following in values.yaml

dex:
image:
tag:

Configure Dex to communicate with an IdP

Example 1: Github Dex Connector

Github can be configured as a connector with dex following their configuration guide.

This requires creating an (Organization-scoped) Oauth Client Application in GitHub with the homepage and redirect uri's matching https://api.<baseDomain> used for the deployment with a callback path of /dex/callback (ex. https://api.cortex.insights.ai/dex/callback).

dex:
config:
connectors:
- type: github
id: "${CLIENT_NAME}"
name: GitHub
config:
orgs:
- name: CognitiveScale
loadAllGroups: false
teamNameField: slug
useLoginAsID: false
clientID: "${CLIENT_ID}"
clientSecret: "${CLIENT_SECRET}"
#redirectURI: https://192.168.64.5:31309/dex/callback
redirectURI: https://api.${CORTEX_DOMAIN}/dex/callback

Example 2: LDAP Dex Connector

Dex can connect to LDAP.

dex:
config:
connectors:
- type: ldap
name: OpenLDAP
id: ldap
config:
# config.host: the host and port of the LDAP server to connect to
# host: cortex-auth-openldap:389
host: ${LDAP_HOST}:${LDAP_PORT}
# No TLS for this setup.
insecureNoSSL: true
# This would normally be a read-only user.
bindDN: cn=admin,dc=example,dc=org
# needs to match openldap.adminPassword
bindPW: secret
usernamePrompt: Email Address
userSearch:
baseDN: ou=People,dc=example,dc=org
filter: "(objectClass=person)"
username: mail
# "DN" (case sensitive) is a special attribute name. It indicates that
# this value should be taken from the entity's DN not an attribute on
# the entity.
idAttr: DN
emailAttr: mail
nameAttr: cn
groupSearch:
baseDN: ou=Groups,dc=example,dc=org
filter: "(objectClass=groupOfNames)"
# A user is a member of a group when their DN matches
# the value of a "member" attribute on the group entity.
userAttr: DN
groupAttr: member
# The group name should be the "cn" value.
nameAttr: cn
openldap:
# needs to match bindPW in dex's LDAP connector config as well
adminPassword: secret

Example 3: Active Directory Dex Connector

Azure Active Directory can be configured as a connector with dex following their configuration guide.

This requires creating an Enterprise application in the Azure Active Directory with the redirect uri matching https://api.<baseDomain> used for the deployment with a callback path of /dex/callback (ex. https://api.cortex.insights.ai/dex/callback).

dex:
config:
connectors:
- config:
clientID: $MICROSOFT_APPLICATION_ID
clientSecret: $MICROSOFT_CLIENT_SECRET
redirectURI: https://api.<baseDomain>/dex/callback
tenant: $MICROSOFT_AZURE_AD_TENANT_ID
groups:
- developers
- devops
id: microsoft
name: Microsoft
type: microsoft

Configure Cortex Auth Static Provider for Dex

The following Dex subchart config must be consistent with the values used to configure your Cortex chart.

auth:
domains:
base: "https://api.${BASE_DOMAIN}"
cortex:
auth:
clientID: "cortex-app"
clientSecret: "${UNIQUE_TOKEN}"
dex:
config:
staticClients:
- id: cortex-app
redirectURIs:
- 'https://api.${BASE_DOMAIN}/login/oidc'
name: 'Cortex'
secret: ${UNIQUE_TOKEN}

Your dex/config/redirectURIs is https://api.<BASE_DOMAIN> of your Cortex cluster, and the secret must be consistent with the secret set in your Cortex Chart.

Mapping IdP roles to Cortex groups

'[{"group":"$GROUP_NAME1","role":"$ROLE_NAME1"},{"group":"$GROUP_NAME2","role":"$ROLE_NAME2"},...]'

Example:

'[{"group":"CognitiveScale:cortex-developers","role":"developer"},{"group":"CognitiveScale:cortex6-test","role":"developer"},{"group":"cortex-developers","role":"developer"},{"group":"cortex-admins","role":"administrator"}]'