Connecting an external authentication provider allows you to use a single set of credentials to access multiple clusters and simultaneously work with multiple providers.

DP supports integration with the following external authentication providers and protocols:

Password policies (such as complexity requirements, expiration, history, two-factor authentication, etc.) are fully controlled by the external authentication provider.
DP does not manage passwords or interfere with policy enforcement on the provider side.

General integration workflow

The allowedGroups parameter in the DexProvider resource allows you to restrict login access to users who belong to specific groups.
If the allowedGroups list is specified, the user must be a member of at least one of these groups — otherwise, authentication will be considered unsuccessful.
If the parameter is not specified, no group-based filtering will be applied.

  1. Create an OAuth application in the authentication provider:
    • Set the redirect URI to https://dex.<publicDomainTemplate>/callback.
    • Obtain the clientID and clientSecret.

    Important: When specifying the redirect URI, substitute the actual value of publicDomainTemplate without %s.
    For example, if publicDomainTemplate: '%s.sandbox1.deckhouse-docs.flant.com', the actual URI would be:
    https://dex.sandbox1.deckhouse-docs.flant.com/callback.

    To retrieve the Dex address (URI), run:

    d8 k -n d8-user-authn get ingress dex -o jsonpath="{.spec.rules[*].host}"
    
  2. Create a DexProvider resource tailored to the specifics of your selected identity provider.

  3. Enable the user-authn module (if it is currently disabled).

    This can be done either via the Deckhouse admin web interface or through the CLI.
    Below is an example using the Deckhouse CLI (requires kubectl context configured to access the cluster):

    Check the module status:

    d8 k get module user-authn
    

    Example output:

    NAME         STAGE   SOURCE     PHASE       ENABLED   READY
    user-authn           Embedded   Available   True      True
    

    Enable the module via CL:

    d8 system module enable user-authn
    
  4. Configure the user-authn module.

    • Open the user-authn module settings (create a ModuleConfig resource named user-authn if it doesn’t exist):

      d8 k edit mc user-authn
      
    • Specify the required module parameters in the spec.settings section. For more details about the user-authn module settings, refer to the module reference.

      Example user-authn configuration:

      apiVersion: deckhouse.io/v1alpha1
      kind: ModuleConfig
      metadata:
        name: user-authn
      spec:
        version: 3
        enabled: true
        settings:
          kubeconfigGenerator:
          - id: direct
            masterURI: https://159.89.5.247:6443
            description: "Direct access to kubernetes API"
      
    • To publish the Kubernetes API via an Ingress controller or Gateway API, enable the apiserver.publishAPI.ingress.enabled parameter in the control-plane-manager module settings:

      apiVersion: deckhouse.io/v1alpha1
      kind: ModuleConfig
      metadata:
        name: control-plane-manager
      spec:
        version: 3
        enabled: true
        settings:
          apiserver:
            publishAPI:
              ingress:
                enabled: true
      

    For more information on how to expose the Kubernetes API, see the control-plane-manager module documentation.

After setting up integration in the cluster with an external authentication provider, authentication through it will become possible in the platform’s web interfaces. Information on setting up authentication for user applications can be found in the section Usage → IAM → Authentication.

Limiting the identities of a provider

A user who signs in through a DexProvider gets the email and the groups that the identity provider reports. The email is the Kubernetes username. As a result, users of the provider receive all permissions already granted in the cluster to those email addresses and groups.

To restrict the identities a provider can assert, use the spec.allowedIdentities parameter:

  • emails and emailDomains describe the emails that the provider may assert. Dex refuses sign-in for any other email.
  • groups describes the group names that the provider may assert. Dex keeps only the listed groups in the token and refuses sign-in if none is left.

The limits apply to every provider type, in addition to the group filters of the type, such as oidc.allowedGroups, gitlab.groups or crowd.groups. Group names are compared exactly. Nesting of Group objects does not extend the list.

Dex checks the limits at sign-in, at every refresh-token request and at Basic Authentication to the API server through an LDAP provider. Dex revokes refresh tokens for identities that no longer satisfy the limits, so narrowing the limits ends the existing sessions of the excluded users. For a Crowd or OIDC provider, basic-auth-proxy checks the credentials with the provider directly, so the limits do not apply to Basic Authentication.

The same limits define who can create or change the provider: you must be able to assign every role already granted to the emails and groups that the provider can report. Only a SuperAdmin can create or change a provider without an email limit. A Crowd or OIDC provider with enableBasicAuth: true counts as a provider without an email limit, so only a SuperAdmin can create it or turn on enableBasicAuth in it.

Example of a provider limited by an email domain and a group:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: contractors
spec:
  type: OIDC
  displayName: Contractors
  oidc:
    issuer: https://idp.contractor.example
    clientID: dex
    clientSecret: secret
  allowedIdentities:
    emailDomains: [contractor.example]
    groups: [contractors]

The following changes are not checked: changing clientSecret or bindPW, changing displayName, disabling the provider, narrowing the limits, reapplying the same manifest, and deleting the provider. Any other change is checked as connecting a new provider, including enabling a disabled provider.

If the check fails, the error lists the roles that the provider could receive, for example:

dexproviders.deckhouse.io "corp": the provider can assert identities that already carry roles [user-authz:super-admin]; the requester's can-assign range is basic<=ClusterAdmin and does not cover them. Narrow spec.allowedIdentities (emails, emailDomains, groups) or ask a SuperAdmin

Checking provider connectivity

The provider page of the DP web UI has the “Check connection” action. It creates a DexProviderCheck resource and waits until the user-authn controller writes the check result to its status.

The check verifies the following:

  • the specified DexProvider exists and is enabled;
  • the Dex discovery endpoint inside the cluster is reachable;
  • the endpoint of the external provider is reachable.

For OIDC providers, the discovery document and JWKS are also read. For LDAP providers, TCP/TLS/StartTLS reachability is checked and, if Kerberos is enabled, the presence of the keytab Secret. The check also verifies that the provider accepts the client or service account credentials (GitHub, GitLab, Bitbucket Cloud, Crowd, OIDC, bind in LDAP) and warns about disabled TLS verification and certificates that expire soon. The check does not perform a full sign-in flow and does not check the password of a test user.

To run the check without the web UI, create a DexProviderCheck resource:

apiVersion: deckhouse.io/v1
kind: DexProviderCheck
metadata:
  name: check-github
spec:
  providerName: github

Then read its status:

d8 k get dexproviderchecks check-github -o yaml

OIDC (OpenID Connect) integration

Authentication via an OIDC provider requires registering a client (or creating an application). Follow your provider’s documentation to do this (e.g., Okta, Keycloak, Gluu, or Blitz).

Specify the clientID and clientSecret obtained during setup in the DexProvider resource.

When registering an application with any OIDC provider, you must specify a redirect URI.
For integration with DexProvider, use the following format: https://dex.<publicDomainTemplate>/callback, where publicDomainTemplate is the DNS name template of your cluster as defined in the global module.

To ensure proper token revocation on logout and to force re-authentication, set the promptType parameter to login.
This guarantees that the user will be prompted to re-enter credentials during subsequent logins.

To configure fine-grained access control for users in applications:

  • Add the allowedUserGroups parameter to the ModuleConfig of the target application.
  • Assign the appropriate groups to the user, using identical group names on both the provider and Deckhouse sides.

Keycloak

During Keycloak configuration, select the appropriate realm, add a user in the Users section, and create a client in the Clients section with authentication enabled, which is required to generate a clientSecret. Then follow these steps:

  1. In the Client scopes section, create a scope named groups and assign it a mapper Group Membership (“Client scopes” → “Client scope details” → “Mappers” → “Configure a new mapper”). Set values of “Name” and “Token Claim Name” as groups and turn off “Full group path”.
  2. In the previously created client, add this scope in the Client scopes tab (“Clients” → “Client details” → “Client Scopes” → “Add client scope”).
  3. In the “Valid redirect URIs”, “Valid post logout redirect URIs”, and “Web origins” fields in the client configuration, specify https://dex.<publicDomainTemplate>/*, where publicDomainTemplate is the cluster DNS name template defined in the global module.

Example provider configuration for Keycloak integration:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: keycloak
spec:
  type: OIDC
  displayName: My Company Keycloak
  oidc:
    issuer: https://keycloak.my-company.com/realms/myrealm # Use your realm name
    clientID: plainstring
    clientSecret: plainstring
    insecureSkipEmailVerified: true
    getUserInfo: true
    scopes:
      - openid
      - profile
      - email
      - groups

If email verification is not enabled in Keycloak, to properly use it as an identity provider, adjust the Client Scopes settings in one of the following ways:

  • Delete the Email verified mapping (“Client Scopes” → “Email” → “Mappers”). This is required for proper processing of the insecureSkipEmailVerified field when it’s set to true and for correct permission assignment to users with unverified emails.

  • If you can’t modify or delete the Email verified mapping, create a new Client Scope named email_dkp (or any other name) and add two mappings:

    • email: “Client Scopes” → email_dkp → “Add mapper” → “From predefined mappers” → email.
    • email verified: “Client Scopes” → email_dkp → “Add mapper” → “By configuration” → “Hardcoded claim”. Specify the following fields:
      • “Name”: email verified
      • “Token Claim Name”: emailVerified
      • “Claim value”: true
      • “Claim JSON Type”: boolean

    After that, in the client registered for the DP cluster in “Clients”, change Client scopes from email to email_dkp.

    In the DexProvider resource, specify insecureSkipEmailVerified: true and in the .spec.oidc.scopes field, change the Client Scope name to email_dkp following the example:

    scopes:
     - openid
     - profile
     - email_dkp
     - groups
    

With insecureSkipEmailVerified: true, Dex accepts unverified email addresses. Permissions are granted by email, so use this parameter only if the identity provider does not let users set an arbitrary email address.

Blitz Identity Provider

Example configuration of a provider for integration with Blitz Identity Provider:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: blitz
spec:
  displayName: Blitz Identity Provider
  oidc:
    basicAuthUnsupported: false
    claimMapping:
      email: email
      groups: your_claim # Claim for obtaining user groups; groups are configured on the Blitz Identity Provider side.
    clientID: clientID
    clientSecret: clientSecret
    getUserInfo: true
    insecureSkipVerify: false
    issuer: https://yourdomain.idblitz.ru/blitz
    promptType: consent 
    scopes:
    - profile
    - openid
    userIDKey: sub
    userNameKey: email
  type: OIDC

Okta

Example configuration of a provider for integration with Okta:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: okta
spec:
  type: OIDC
  displayName: My Company Okta
  oidc:
    issuer: https://my-company.okta.com
    clientID: plainstring
    clientSecret: plainstring
    getUserInfo: true

After enabling integration with Okta, you can use Okta user groups to manage access rights. For example, you can specify a list of groups whose members are allowed to access Grafana.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  settings:
    auth:
      allowedUserGroups:
        - adm-grafana-access
        - grafana-access

SAML 2.0 integration

The example shows the provider’s settings for integration with a SAML 2.0 Identity Provider (e.g., AD FS, Okta, Keycloak).

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: saml-provider
spec:
  type: SAML
  displayName: Corporate SAML
  saml:
    ssoURL: https://saml-idp.example.com/saml/sso
    rootCAData: |
      -----BEGIN CERTIFICATE-----
      MIIFaDC...
      -----END CERTIFICATE-----
    entityIssuer: https://dex.example.com/callback
    ssoIssuer: https://saml-idp.example.com
    usernameAttr: name
    emailAttr: email
    groupsAttr: groups
    nameIDPolicyFormat: persistent

To configure the SAML Identity Provider:

  1. Register Dex as a Service Provider (SP) in your IdP with the following settings:
    • ACS URL (Assertion Consumer Service): https://dex.<modules.publicDomainTemplate>/callback
    • Entity ID: https://dex.<modules.publicDomainTemplate>/callback
    • NameID format: persistent or emailAddress
  2. Configure attribute mappings in the IdP to send email, name (username), and groups attributes in the SAML assertion.

  3. Export the IdP signing certificate and specify it in the rootCAData field of the DexProvider resource.

SAML does not support refresh tokens. Dex caches the user data from the first SAML assertion and returns it on subsequent refresh-token requests. The session lifetime is limited by the refreshTokenAbsoluteLifetime parameter of the user-authn module.

LDAP integration

To configure authentication, create a read-only account (service account) in your LDAP directory.
This account will be used to perform search queries in the LDAP catalog. You can also configure user lockout after failed sign-in attempts for this type of integration. To do this, specify the provider type in the passwordPolicy.lockout.applyToConnectors parameter of the user-authn module.

In the DexProvider resource, specify the following parameters:

  • bindDN: Full Distinguished Name (DN) of the created service account. For example: cn=readonly,dc=example,dc=org.
  • bindPW: Password for the specified bindDN.

If your LDAP server allows anonymous access for search queries, the bindDN and bindPW parameters can be omitted.
However, using authenticated access is recommended for improved security.

The bindPW parameter must contain the password in plain text. Dex does not support hashed passwords in this field.

You can also enable support for:

Example configuration for integrating with Active Directory (Basic Authentication):

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: active-directory
spec:
  type: LDAP
  displayName: Active Directory
  ldap:
    host: ad.example.com:636
    rootCAData: |
      -----BEGIN CERTIFICATE-----
      MIIFaDC...
      -----END CERTIFICATE-----

    bindDN: cn=dex-readonly,cn=users,dc=example,dc=com
    bindPW: <PASSWORD>

    enableBasicAuth: true

    usernamePrompt: Email Address

    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=group)"
      userMatchers:
      - userAttr: DN
        groupAttr: member
      nameAttr: cn

GitHub integration

You need to create a new application in your GitHub organization.

To do this, follow these steps:

  1. Go to “Settings → Developer settings → OAuth Apps → New OAuth App”, and set the “Authorization callback URL” to https://dex.<publicDomainTemplate>/callback.
  2. Use the generated Client ID and Client Secret in the DexProvider resource.

If the organization restricts third-party applications:

  1. Go to “Settings → Applications → Authorized OAuth Apps → <APPLICATION_NAME>” and click “Send Request” to submit an approval request.
  2. Ask an organization owner to approve the request.

Example configuration for integrating with GitHub:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: github
spec:
  type: Github
  displayName: My Company GitHub
  # Optional: disable the provider without deleting CR
  # enabled: false
  github:
    clientID: plainstring
    clientSecret: plainstring

GitLab integration

You need to create a new application in your GitLab project.

To do this, follow these steps:

  1. For self-hosted GitLab: go to “Admin Area → Applications → New application” and set the “Redirect URI (Callback URL)” to https://dex.<publicDomainTemplate>/callback. Also, select the following scopes: read_user, openid.
  2. For GitLab Cloud (gitlab.com): under the main account of the project, go to “User Settings → Applications → Add new application”, set the “Redirect URI (Callback URL)” to https://dex.<publicDomainTemplate>/callback, and select the scopes: read_user, openid.
  3. Use the obtained Application ID and secret in the DexProvider resource.

For GitLab version 16 and above, enable the “Trusted” option when creating the application.
This option is available under “Admin Area → Applications”. Marking the app as trusted allows skipping the authorization step for users, which can be useful in controlled environments.

Example configuration for integrating with GitLab:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: gitlab
spec:
  type: Gitlab
  displayName: Dedicated Gitlab
  gitlab:
    baseURL: https://gitlab.example.com
    clientID: plainstring
    clientSecret: plainstring
    groups:
    - administrators
    - users

Atlassian Crowd integration

In the relevant Atlassian Crowd project, you need to create a new Generic application.

You can also configure user lockout after failed sign-in attempts for this type of integration. To do this, specify the provider type in the passwordPolicy.lockout.applyToConnectors parameter of the user-authn module.

To do this, follow these steps:

  1. Go to “Applications → Add application”.
  2. Specify the obtained “Application Name” and “Password” in the DexProvider resource.
  3. When specifying groups in the DexProvider resource, make sure their names are written in lowercase.
    This is necessary for correct group matching between Crowd and DP.

Example configuration for integrating with Atlassian Crowd:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: crowd
spec:
  type: Crowd
  displayName: Crowd
  crowd:
    baseURL: https://crowd.example.com/crowd
    clientID: plainstring
    clientSecret: plainstring
    groups:
    - administrators
    - users

Basic Authentication to the Kubernetes API through a Crowd provider (enableBasicAuth) bypasses the identity limits of the provider, so only a SuperAdmin can enable it.

Bitbucket Cloud Integration

To configure authentication, you need to create a new OAuth consumer in the Bitbucket team menu.

Follow these steps:

  1. Go to “Personal settings → Access management → OAuth consumers → Add consumer”, and specify https://dex.<publicDomainTemplate>/callback as the “Callback URL”.
  2. Grant access:
    • “Account: Read” → allows retrieval of basic user information (e.g., email, username).
    • “Workspace membership: Read” → allows retrieval of user workspace membership information.
  3. Use the obtained Key and secret in the DexProvider resource.

Example configuration for integrating with Bitbucket:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: bitbucket
spec:
  type: BitbucketCloud
  displayName: Bitbucket
  bitbucketCloud:
    clientID: plainstring
    clientSecret: plainstring
    includeTeamGroups: true
    teams:
    - administrators
    - users

Additional resources