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:
- LDAP (for example, Active Directory);
- OIDC (for example, Okta, Keycloak, Gluu, Blitz Identity Provider);
- SAML 2.0;
- GitHub integration;
- GitLab integration;
- Atlassian Crowd integration;
- Bitbucket Cloud integration.
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.
- Create an OAuth application in the authentication provider:
- Set the redirect URI to
https://dex.<publicDomainTemplate>/callback. - Obtain the
clientIDandclientSecret.
Important: When specifying the redirect URI, substitute the actual value of
publicDomainTemplatewithout%s.
For example, ifpublicDomainTemplate: '%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}" - Set the redirect URI to
-
Create a DexProvider resource tailored to the specifics of your selected identity provider.
-
Enable the
user-authnmodule (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-authnExample output:
NAME STAGE SOURCE PHASE ENABLED READY user-authn Embedded Available True TrueEnable the module via CL:
d8 system module enable user-authn -
Configure the
user-authnmodule.-
Open the
user-authnmodule settings (create a ModuleConfig resource nameduser-authnif it doesn’t exist):d8 k edit mc user-authn -
Specify the required module parameters in the
spec.settingssection. For more details about theuser-authnmodule settings, refer to the module reference.Example
user-authnconfiguration: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.enabledparameter in thecontrol-plane-managermodule 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-managermodule 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:
emailsandemailDomainsdescribe the emails that the provider may assert. Dex refuses sign-in for any other email.groupsdescribes 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
allowedUserGroupsparameter 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:
- In the Client scopes section, create a
scopenamedgroupsand assign it a mapperGroup Membership(“Client scopes” → “Client scope details” → “Mappers” → “Configure a new mapper”). Set values of “Name” and “Token Claim Name” asgroupsand turn off “Full group path”. - In the previously created client, add this
scopein the Client scopes tab (“Clients” → “Client details” → “Client Scopes” → “Add client scope”). - In the “Valid redirect URIs”, “Valid post logout redirect URIs”, and “Web origins” fields in the client configuration, specify
https://dex.<publicDomainTemplate>/*, wherepublicDomainTemplateis the cluster DNS name template defined in theglobalmodule.
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 verifiedmapping (“Client Scopes” → “Email” → “Mappers”). This is required for proper processing of theinsecureSkipEmailVerifiedfield when it’s set totrueand for correct permission assignment to users with unverified emails. -
If you can’t modify or delete the
Email verifiedmapping, create a new Client Scope namedemail_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
- “Name”:
After that, in the client registered for the DP cluster in “Clients”, change
Client scopesfromemailtoemail_dkp.In the DexProvider resource, specify
insecureSkipEmailVerified: trueand in the.spec.oidc.scopesfield, change the Client Scope name toemail_dkpfollowing 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:
- 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:
persistentoremailAddress
- ACS URL (Assertion Consumer Service):
-
Configure attribute mappings in the IdP to send
email,name(username), andgroupsattributes in the SAML assertion. - Export the IdP signing certificate and specify it in the
rootCADatafield 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 specifiedbindDN.
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:
- Basic Authentication for accessing the Kubernetes API using LDAP credentials. To do this, set the
enableBasicAuth: trueparameter in the DexProvider resource. For more information, see Access using Basic Authentication. - Kerberos SSO (SPNEGO) for LDAP. To do this, enable the
spec.ldap.kerberosblock in the DexProvider resource, specify the keytab Secret inkeytabSecretNameand configure the other parameters in it. For more details, see Kerberos SSO (SPNEGO) for LDAP.
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:
- Go to “Settings → Developer settings → OAuth Apps → New OAuth App”, and set the “Authorization callback URL” to
https://dex.<publicDomainTemplate>/callback. - Use the generated
Client IDandClient Secretin the DexProvider resource.
If the organization restricts third-party applications:
- Go to “Settings → Applications → Authorized OAuth Apps →
<APPLICATION_NAME>” and click “Send Request” to submit an approval request. - 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:
- 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. - 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. - Use the obtained
Application IDand 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:
- Go to “Applications → Add application”.
- Specify the obtained “Application Name” and “Password” in the DexProvider resource.
- 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:
- Go to “Personal settings → Access management → OAuth consumers → Add consumer”, and specify
https://dex.<publicDomainTemplate>/callbackas the “Callback URL”. - Grant access:
- “Account: Read” → allows retrieval of basic user information (e.g., email, username).
- “Workspace membership: Read” → allows retrieval of user workspace membership information.
- Use the obtained
Keyand 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