Available in editions:  Open/CE, BE, SE, SE+, Ultimate/EE, Core

Included in extensions: Billing

The module lifecycle stage: General Availability

The module has 15 alerts.

The module is enabled by default in the Default bundle. The module is disabled by default in the following bundles: Managed, Minimal.

How to explicitly enable the module...

You may explicitly enable or disable the module in one of the following ways:

  • Via Deckhouse web UI. In the “System” → “System Management” → “Deckhouse” → “Modules” section, open the user-authn module and enable (or disable) the “Module enabled” toggle. Save changes.

    Example:

    Module enable/disable interface

  • Via Deckhouse CLI (d8).

    Use the d8 system module enable command for enabling, or d8 system module disable command for disabling the module (you need Deckhouse CLI (d8), configured to work with the cluster).

    Example of enabling the module:

    d8 system module enable user-authn
    
  • Using ModuleConfig user-authn.

    Set spec.enabled to true or false in ModuleConfig user-authn (create it if necessary);

    Example of a manifest to enable module user-authn:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: user-authn
    spec:
      enabled: true
    

How to configure the module...

You can configure the module in one of the following ways:

  • Via Deckhouse web UI.

    In the “System” → “System Management” → “Deckhouse” → “Modules” section, open the user-authn module and enable the “Advanced Settings” switch. Fill in the required fields in the “Configuration” tab or specify the module settings in YAML format on the “YAML” tab, excluding the settings section. Save the changes.

    Example:

    Module Setup Interface

    You can also edit the ModuleConfig object user-authn on the “YAML” tab in the module settings window (“System” → “System Management” → “Deckhouse” → “Modules”, open the module user-authn) by specifying the schema version in the spec.version parameter and the necessary module parameters in the spec.settings section.

  • Via Deckhouse CLI (d8) (requires Deckhouse CLI (d8) configured to work with the cluster).

    Edit the existing ModuleConfig user-authn (for more details on configuring Deckhouse, see the documentation) by executing the following command:

    d8 k edit mc user-authn
    

    Make the necessary changes in the spec.settings section. If necessary, specify the schema version in the spec.version parameter. Save the changes.

    You can also create a file with manifest for ModuleConfig user-authn using the example below. Fill in the spec.settings section with the required module parameters. If necessary, specify the schema version in the spec.version parameter.

    Apply the manifest using the following command (indicate the manifest file name):

    d8 k apply -f <FILENAME>
    

    Example of a manifest for ModuleConfig user-authn:

    apiVersion: deckhouse.io/v1alpha1
    kind: ModuleConfig
    metadata:
      name: user-authn
    spec:
      version: 4
      enabled: true
      settings: # Module parameters from the "Parameters" section below.
    

Conversions

The module is configured using the ModuleConfig resource, the schema of which contains a version number. When you apply an old version of the ModuleConfig schema in a cluster, automatic transformations are performed. To manually update the ModuleConfig schema version, the following steps must be completed sequentially for each version :

  • Updates from version 1 to 2:

    Replace publishAPI.enable with publishAPI.enabled.

  • Updates from version 2 to 3:

    An idTokenTTL of 6 hours or more is replaced with 5h59m: Dex rotates its signing keys every 6 hours.

  • Updates from version 3 to 4:

    The staticUsers2FA parameter is renamed twoFactor. The second factor can now be turned on for more than the local users.

Parameters

Schema version: 4

  • settings
    object
    • settings.controlPlaneConfigurator
      object

      Parameters of the control-plane-manager module for automatic configuration of kube-apiserver.

      • settings.controlPlaneConfigurator.dexCAMode
        string

        How to determine the CA that will be used when configuring kube-apiserver.

        • Custom — use the CA explicitly set via the dexCustomCA parameter (see below). This option comes in handy if you use an external HTTPS load balancer in front of Ingresses, and this load balancer relies on a self-signed certificate.
        • DoNotNeed — a CA is not required (e.g., when using a public LE or other TLS providers).
        • FromIngressSecret — extract the CA of certificate from the Secret that is used in the Ingress. This option comes in handy if you use self-signed certificates with Ingresses.

        Default: DoNotNeed

        Allowed values: Custom, DoNotNeed, FromIngressSecret

      • settings.controlPlaneConfigurator.dexCustomCA
        string

        The CA to use if dexCAMode is Custom. Plain text (no base64).

      • settings.controlPlaneConfigurator.enabled
        boolean

        Defines if the control-plane-manager module should be used to configure OIDC for the kube-apiserver.

        Default: true

    • settings.devices
      object

      Devices of a user: the browsers and the other clients (kubeconfig, d8 login) the user signed in from.

      • settings.devices.maxPerApplication
        integer

        The maximum number of devices on which a user can be simultaneously logged in to a single application (DexAuthenticator, DexClient, kubeconfig).

        A device is a browser with a Dex session together with all application domains it has logged in to, or a refresh token without a browser session, e.g. a kubeconfig file.

        If a user logs in from a new device and the limit specified in the parameter has been reached, the device that has been unused the longest is logged out of the application. Non-trusted devices are logged out first (for details, see the description of the trustedAfter parameter).

        Default: 10

        Allowed values: 1 <= X <= 1000

        Examples:

        maxPerApplication: 10
        
        maxPerApplication: 3
        
      • settings.devices.rememberedBrowsers
        integer

        How many browsers of a user Dex remembers with their first sign-in.

        A remembered browser that signs in again keeps its age: the time until it is trusted (trustedAfter) counts from its first sign-in. Past the limit, the browser seen longest ago is forgotten and counts as new at its next sign-in.

        0 remembers no browser: every sign-in is a new device.

        Default: 20

        Allowed values: 0 <= X <= 1000

        Examples:

        rememberedBrowsers: 20
        
        rememberedBrowsers: 0
        
      • settings.devices.trustedAfter
        string

        Time after which a device of the user is trusted, counted from the first sign-in from its browser (from the sign-in for a device without a browser).

        Only a trusted device lets the user sign out of all devices, of the other devices or of another device, and request a password change on their own. A device signed in more recently can sign the user out only of itself. Someone who has just signed in with a stolen password therefore can neither sign the owner out nor change the password, while the owner sees the new device on a trusted one and signs it out. A stolen session is not covered: a copied cookie of Dex or of the web interface has the age of the owner’s device. The operations of an administrator are not limited.

        When an application reaches the limit of devices of a user, the devices that are not trusted yet are signed out of it first.

        0s trusts every device at once: any device can sign out the others and request a password change.

        Set as a string of whole hours, minutes, and seconds, in this order: 30m, 2h30m, 24h.

        Default: 24h

        Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

        Examples:

        trustedAfter: 24h
        
        trustedAfter: 1h
        
        trustedAfter: 0s
        
    • settings.highAvailability
      boolean

      Manually enable the high availability mode.

      By default, Deckhouse automatically decides whether to enable the HA mode. Learn more about the high availability mode for modules.

      Examples:

      highAvailability: true
      
      highAvailability: false
      
    • settings.https
      object

      What certificate type to use with Dex.

      This parameter completely overrides the global.modules.https settings.

      Examples:

      https:
        mode: CustomCertificate
        customCertificate:
          secretName: foobar
      
      https:
        mode: CertManager
        certManager:
          clusterIssuerName: letsencrypt
      
      • settings.https.certManager
        object

        Settings of the CertManager mode.

        • settings.https.certManager.clusterIssuerName
          string

          What ClusterIssuer to use for Dex.

          Currently, letsencrypt, letsencrypt-staging, selfsigned are available. Also, you can define your own.

          Default: letsencrypt

      • settings.https.customCertificate
        object

        Settings of the CustomCertificate mode.

        • settings.https.customCertificate.secretName
          string

          The name of the Secret in the d8-system namespace to use with Dex.

          This Secret must have the kubernetes.io/tls format.

          Default: false

      • settings.https.mode
        string

        The HTTPS usage mode:

        • CertManager: Dex uses HTTPS and gets a certificate from the ClusterIssuer set in the certManager.clusterIssuerName parameter.
        • CustomCertificate: Dex uses HTTPS with the certificate from the d8-system namespace.
        • Disabled: The module is turned off, because it works only with HTTPS.
        • OnlyInURI: Dex works over HTTP behind an external load balancer that terminates HTTPS. All user-authn links use the HTTPS scheme. The load balancer must redirect HTTP to HTTPS.

        If you set the https section without mode, Disabled applies and the module is turned off.

        Default: Disabled

        Allowed values: Disabled, CertManager, CustomCertificate, OnlyInURI

    • settings.idTokenTTL
      string

      TTL of the ID token.

      Set as a string specifying hours, minutes, or seconds: 30m, 20s, 2h30m10s, 5h.

      Must be greater than zero and strictly less than 6 hours (Dex signing keys rotate every 6 hours). A ModuleConfig of an earlier settings version (spec.version 1 or 2) with a value of 6 hours or more is still accepted: its value is converted to 5h59m.

      Defines the minimum possible user session lifetime (via keepUsersLoggedInFor in the DexAuthenticator resource and parameters like auth.sessionTTL, for example, in the console module).

      If the session TTL is less than or equal to idTokenTTL, the effective logout time is idTokenTTL + 1s.

      To force logout sooner than the default idTokenTTL, decrease this parameter value as well.

      Default: 10m

      Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

    • settings.ingressClass
      string

      The class of the Ingress controller that will be used for Dex.

      An optional parameter; by default, the modules.ingressClass global value is used.

      Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

    • settings.kubeconfigGenerator
      array of objects

      An array in which additional possible methods for accessing the API server are specified.

      This option comes in handy if you prefer not to grant access to the cluster’s API via Ingress but rather do it by other means (e.g., using a bastion host or over OpenVPN).

      • settings.kubeconfigGenerator.description
        string

        A couple of words how this authentication method differs from others.

      • settings.kubeconfigGenerator.id
        string

        Required value

        The name of the method for accessing the API server (no spaces, lowercase letters).

        Pattern: ^[\@\.\:0-9a-z._-]+$

      • settings.kubeconfigGenerator.masterCA
        string

        A CA for accessing the API:

        • If the parameter is not set, Kubernetes CA is used.
        • We recommend using a self-signed certificate (and specify it as masterCA) if an HTTP proxy (that terminates HTTPS traffic) is used for exposing.
      • settings.kubeconfigGenerator.masterURI
        string

        Required value

        API server address that kubeconfig files generated for this access method point to, for example https://192.168.0.15:6443.

        If clients reach the API server through a TCP proxy or a load balancer, add its address to the apiserver.certSANs parameter of the control-plane-manager module.

    • settings.nodeSelector
      object

      The same as in the Pods’ spec.nodeSelector parameter in Kubernetes.

      If the parameter is omitted, it is determined automatically.

    • settings.passwordPolicy
      object

      Password policy for local users.

      Default:

      • settings.passwordPolicy.complexityLevel
        string

        Password complexity level.

        Depending on the complexity level, a password must meet the following minimum requirements:

        • None: 1 character.
        • Low: 8 characters.
        • Fair: 8 characters, 1 uppercase letter (A–Z), 1 lowercase letter (a–z), 1 digit.
        • Good: 8 characters, 1 uppercase letter (A–Z), 1 lowercase letter (a–z), 1 digit, 1 special character (!@#$%^&*).
        • Excellent: 8 characters, 1 uppercase letter (A–Z), 1 lowercase letter (a–z), 1 digit, 1 special character (!@#$%^&*), no more than 2 identical characters in a row.
        • Custom: requirements are defined by the custom field.

        Default: Fair

        Allowed values: None, Low, Fair, Good, Excellent, Custom

      • settings.passwordPolicy.custom
        object

        Custom password complexity rules.

        Applied only when complexityLevel is set to Custom. Any combination of the rules below can be enabled independently.

        • settings.passwordPolicy.custom.capitalized
          boolean

          If true, a password must contain at least one uppercase letter (A–Z).

          Default: false

        • settings.passwordPolicy.custom.minLength
          integer

          Minimum number of characters in a password.

          Default: 8

          Allowed values: 1 <= X

        • settings.passwordPolicy.custom.numbers
          boolean

          If true, a password must contain at least one digit.

          Default: false

        • settings.passwordPolicy.custom.repeatedChars
          boolean

          If true, a password must not contain more than 2 identical characters in a row (the same rule the Excellent level applies).

          Default: false

        • settings.passwordPolicy.custom.specialCharacters
          boolean

          If true, a password must contain at least one special character (anything that is neither a letter nor a digit).

          Default: false

      • settings.passwordPolicy.lockout
        object

        Automatic temporary lockout after consecutive failed login attempts.

        This section only controls lockout after a failed password. An administrator lock via UserOperation (d8 iam user lock) works independently and does not require passwordPolicy or this lockout block.

        • settings.passwordPolicy.lockout.applyToConnectors
          array of strings

          External (non-local) connector types the lockout additionally applies to.

          The built-in Local connector is always covered by the lockout policy when this section is configured and does not need to be listed here.

          For the listed connector types, Dex counts failed attempts and locks each pair of a provider and a user separately. The UserAccount object of the user shows the counter and the lock.

          Manually unlocking a user is supported for every provider type via a UserOperation.

          • Element of the array
            string

            Allowed values: LDAP, Crowd

        • settings.passwordPolicy.lockout.lockDuration
          string

          Required value

          Temporary lockout duration. Can be set in seconds, minutes, hours, or days: 10s, 5m, 1h, 3d.

          Pattern: ^(?:(?:[1-9]|[1-9][0-9]+)d)?(?:(?:[1-9]|[1-9][0-9]+)h)?(?:(?:[1-9]|[1-9][0-9]+)m)?(?:(?:[1-9]|[1-9][0-9]+)s)?$

        • settings.passwordPolicy.lockout.maxAttempts
          integer

          Required value

          Number of consecutive failed login attempts after which the user will be temporarily locked out.

      • settings.passwordPolicy.passwordHistoryLimit
        integer

        Number of the user’s previous passwords stored in history to prevent their reuse.

        Default: 5

        Allowed values: 0 <= X

      • settings.passwordPolicy.rotation
        object

        Password rotation settings.

        • settings.passwordPolicy.rotation.interval
          string

          Required value

          Time interval after which the password must be changed. Can be set in seconds, minutes, hours or days: 10s, 5m, 1h, 3d.

          Pattern: ^(?:(?:[1-9]|[1-9][0-9]+)d)?(?:(?:[1-9]|[1-9][0-9]+)h)?(?:(?:[1-9]|[1-9][0-9]+)m)?(?:(?:[1-9]|[1-9][0-9]+)s)?$

    • settings.publishAPI
      Deprecated
      object

      Obsolete. The module does not publish the Kubernetes API. The API is published with the apiserver.publishAPI parameter of the control-plane-manager module. Move existing settings there.

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

      • settings.publishAPI.addKubeconfigGeneratorEntry
        boolean

        Obsolete. Use the apiserver.publishAPI.ingress.addKubeconfigGeneratorEntry parameter of the control-plane-manager module.

        Default: true

      • settings.publishAPI.enabled
        boolean

        Obsolete. Does not create an Ingress.

        Default: false

      • settings.publishAPI.https
        object

        The HTTPS mode for the API server Ingress.

        Examples:

        https:
          mode: SelfSigned
        
        https:
          mode: Global
          global:
            kubeconfigGeneratorMasterCA: plainstring
        
        • settings.publishAPI.https.global
          object

          An additional parameter for the Global mode.

          • settings.publishAPI.https.global.kubeconfigGeneratorMasterCA
            string

            If there is an external load balancer in front of the Ingress that terminates HTTPS traffic using non-public CA, then you need to specify the CA so it will be included in kubectl-config.

            If you are using certificates issued by the cert-manager module and Let’s Encrypt in your cluster, you should set an empty string "" as the value.

            Also, you can set the external LB’s certificate itself as a CA if you can’t get the CA that signed it for some reason. Note that after the certificate is updated on the LB, all the previously generated kubeconfigs will stop working.

        • settings.publishAPI.https.mode
          string

          The mode of issuing certificates for the Ingress resource.

          In the SelfSigned mode, a CA-signed certificate will be issued for the Ingress resource.

          In the Global mode, the policies specified in the global.modules.https.mode global parameter will be applied. Thus, if the global parameter has the CertManager mode set (with letsencrypt as the ClusterIssuer), then the Let’s Encrypt certificate will be issued for the Ingress resource.

          Default: SelfSigned

          Allowed values: SelfSigned, Global

      • settings.publishAPI.ingressClass
        string

        The Ingress class that will be used to expose the Kubernetes API via Ingress.

        Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$

      • settings.publishAPI.whitelistSourceRanges
        array of strings

        An array of CIDRs that are allowed to connect to the API server.

        • Element of the array
          string

          Pattern: ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))?$

    • settings.rateLimit
      object

      Brute-force protection for the password endpoints of Dex.

      When enabled, Dex limits the failed requests from each client IP address to the following endpoints:

      • /token: Token endpoint: client authentication and the password grant. Other requests of an authenticated client, such as refresh-token requests, do not count.
      • /auth/{connector}/login: Sign-in form of the local, LDAP and Crowd providers.
      • /password/change: Password change page.
      • /mfa and the paths under it: Steps of two-factor authentication (2FA).

      The client IP address is taken from the X-Real-IP header that the platform Ingress controller sets. Dex trusts the header only from the proxies of the platform. The Ingress controller proves itself with its client certificate, which the platform CA issued for the ingress-nginx:auth organization. The controller presents it to any backend an Ingress asks it to, so whoever can create an Ingress with configuration snippets on that controller can set the address too. The Gateway sends a secret stored in the HTTPRoute object of the module in d8-user-authn: whoever can read it can set the address too. For any other request, for example from a pod that calls the Dex Service directly, Dex counts the address of the connection. Through the Gateway API (the alb module) Dex counts the last address of X-Forwarded-For: the address the ALB saw, or the one a balancer passed when the ALB instance trusts it in originalIPDetection.setRealIPFrom. Behind a balancer the ALB instance does not trust, every client is counted by the address of the balancer. Basic Authentication to the Kubernetes API through an LDAP provider is counted per address of the client that the platform Ingress controller or Gateway saw: basic-auth-proxy passes on the last hop of X-Forwarded-For. The Ingress controller has to see the address of the client itself: behind a balancer that replaces it, all users are counted together (see Which client address does Dex see?).

      The limit applies to failed authentication attempts only. Each request takes a token from the bucket of its IP address, and a successful response (HTTP 2xx or 3xx) returns the token. Successful logins and refresh-token exchanges do not consume the per-IP budget. When the bucket is empty, Dex answers with the 429 status code and the Retry-After header.

      Limits are tracked in memory in each Dex replica. In HA setups, the effective per-IP rate is multiplied by the number of replicas. Account lockout complements this limit.

      • settings.rateLimit.enabled
        boolean

        Enable per-IP rate limiting on Dex password endpoints.

        Default: false

      • settings.rateLimit.perIP
        object

        Per-source-IP token-bucket configuration.

        Both requestsPerMinute and burst parameters count failed authentication attempts only.

        • settings.rateLimit.perIP.burst
          integer

          Maximum bucket size defining the allowed number of failed authentication attempts from a single IP address before the throttling activates.

          Default: 10

          Allowed values: 1 <= X

        • settings.rateLimit.perIP.requestsPerMinute
          integer

          Maximum rate of failed authentication attempts tolerated per IP address (in attempts per minute).

          Successful logins and refresh-token exchanges do not consume the budget.

          Default: 10

          Allowed values: 1 <= X

    • settings.refreshTokenAbsoluteLifetime
      string

      Maximum lifetime of refresh tokens (maps to Dex expiry.refreshTokens.absoluteLifetime).

      This setting controls how long user sessions can persist. After this period expires, users will need to re-authenticate, even if they have active refresh tokens.

      A refresh token that is not used for refreshTokenValidIfNotUsedFor expires earlier.

      The value must not be shorter than idTokenTTL.

      It is specified as a string containing the time unit in hours, minutes and seconds: 30m, 20s, 2h30m10s, 24h.

      Default: 4380h

      Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

    • settings.refreshTokenValidIfNotUsedFor
      string

      Time after which a refresh token that is not used expires (maps to Dex expiry.refreshTokens.validIfNotUsedFor).

      A kubeconfig file or an application that has not refreshed its tokens for this time signs in again. By default, about 3 months.

      The value must be greater than zero and not longer than refreshTokenAbsoluteLifetime.

      It is specified as a string containing the time unit in hours, minutes and seconds: 30m, 20s, 2h30m10s, 24h.

      Default: 2190h

      Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

      Examples:

      refreshTokenValidIfNotUsedFor: 2190h
      
      refreshTokenValidIfNotUsedFor: 720h
      
    • settings.retention
      object

      How long the records of the module are kept.

      • settings.retention.revocations
        string

        How long a record of a revocation (the end of the sessions and tokens of a user by an operation or a sign-out) is kept for the components that end the sessions of the user from it: DexAuthenticator objects, Basic Authentication to the Kubernetes API, the authorization webhook.

        By default, and at least, idTokenTTL and an hour, but not less than 70 minutes: until every token issued before the revocation expired. A shorter value is raised to this minimum.

        Set as a string of whole hours, minutes, and seconds, in this order: 30m, 2h30m, 24h.

        Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

        Example:

        revocations: 24h
        
      • settings.retention.userOperations
        string

        How long a UserOperation object is kept after its creation. Then it is deleted, and the history of operations of the web interface no longer shows it.

        Set as a string of whole hours, minutes, and seconds, in this order: 30m, 2h30m, 24h.

        Default: 24h

        Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

        Examples:

        userOperations: 24h
        
        userOperations: 720h
        
    • settings.sessions
      object

      Browser sessions of Dex.

      With sessions on, Dex remembers the user signed in to a browser:

      • The web interfaces of Deckhouse (the DexAuthenticator objects of the platform modules, such as the console or Grafana) share the sign-in: the user enters the password and the second factor once and opens the others without them (see sso). For a user of an external provider, this lasts while the stored user data is fresh (see identityRefresh).
      • The sign-in form shows the “Remember me” checkbox. With it, the session survives closing the browser.
      • Signing out of an application of a DexAuthenticator object ends the session: the browser is signed out of all the applications of DexAuthenticator objects it signed in to through this session within seconds.

      What does not change:

      • Access tokens for kubectl (kubeconfig, d8 login) and applications of the DexClient objects that request offline access are issued only after an interactive sign-in, never from a session of the browser. A DexClient with refreshTokenLifetime: Session is the exception.
      • An application signed in through a DexAuthenticator stays signed in for keepUsersLoggedInFor, even after the session of Dex expires. The session limits only signing in without a password.
      • Signing out of Dex does not sign the user out of an external OIDC provider unless the provider has upstreamLogout enabled.
      • settings.sessions.absoluteLifetime
        string

        Maximum lifetime of a session, counted from the sign-in.

        However much the browser is used, the session ends after this time, and the next application asks for the password and the second factor again. By default, a user who works every day enters them once a week.

        Set as a string of whole hours, minutes, and seconds, in this order: 30m, 2h30m, 24h.

        Default: 168h

        Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

      • settings.sessions.enabled
        boolean

        Turns the browser sessions of Dex on.

        Default: false

      • settings.sessions.identityRefresh
        object

        Freshness of the user data that Dex stores at the sign-in, such as the groups of the user.

        Dex serves the stored data until it is older than maxAge, and then reads it from the provider again. This holds with sessions on or off: a refresh of the tokens of an application reaches the provider only when the stored data is older than maxAge. A user disabled at the provider therefore keeps refreshing the tokens until then. If the provider answers that the user no longer exists or is no longer allowed in, Dex ends all the sessions and tokens of the user of this provider. The data of local users is read again every time.

        A provider that answers with a server error (HTTP 5xx) looks to Dex like a provider that is down. Once the stored data is older than maxAge, Dex answers the refresh of the tokens with 503 and keeps the tokens, and DexAuthenticator sends the user to the sign-in idTokenTTL after the first such error. Dex of the upstream project (dexidp/dex) and Deckhouse Dex before version 1.78 may answer the refresh of a deleted local or LDAP user this way. Behind such a provider, a deleted user sees an error page for about idTokenTTL and then the sign-in page.

        A sign-in from a session needs fresh data too. Dex keeps no credentials of a user of an external provider to read the data in the background, so once the data is older than maxAge, such a user signs in to the next application with the password again. Every sign-in and every refresh of the tokens of an application that reads the provider renews the data: a user who keeps working in an application of a DexAuthenticator keeps the single sign-on. To keep it through longer breaks, raise maxAge.

        • settings.sessions.identityRefresh.gracePeriod
          string

          How much longer than maxAge Dex serves the stored data when the provider does not answer.

          After this period, Dex refuses to refresh the tokens of the user until the provider answers.

          Set as a string of whole hours, minutes, and seconds, in this order: 30s, 5m, 1h.

          Default: 0s

          Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

        • settings.sessions.identityRefresh.maxAge
          string

          Age of the stored data after which Dex reads it from the provider again.

          Defaults to idTokenTTL.

          Set as a string of whole hours, minutes, and seconds, in this order: 30m, 2h30m, 24h.

          Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

      • settings.sessions.rememberMeCheckedByDefault
        boolean

        Whether the “Remember me” checkbox of the sign-in form is selected by default.

        Without “Remember me”, the session ends when the browser is closed.

        Default: false

      • settings.sessions.sso
        string

        Sharing of the sign-in between applications.

        • Platform: The web interfaces of Deckhouse share the sign-in. These are the applications of the DexAuthenticator objects in the d8-* namespaces. User DexAuthenticator and DexClient objects do not share it.
        • None: Every application asks for the sign-in. A session only spares the password when the user signs in to the same application again.

        Default: Platform

        Allowed values: Platform, None

      • settings.sessions.validIfNotUsedFor
        string

        Time after which an unused session ends.

        A session is used when the browser signs in to an application through it, and when an application signed in through it refreshes its tokens: an application of a DexAuthenticator object or of a DexClient with refreshTokenLifetime: Session. Such an application refreshes its tokens while it is open and sends requests; an application closed, or open in a browser of a sleeping computer, does not use the session. While the browser uses the session, it lasts up to absoluteLifetime.

        With the default of a day, a session survives a night but not a weekend. For stricter requirements, set a shorter time, for example 1h: the user then enters the password again after each break of an hour.

        Must not be longer than absoluteLifetime. When only absoluteLifetime is set and is shorter than a day, an unused session ends after absoluteLifetime.

        Set as a string of whole hours, minutes, and seconds, in this order: 30m, 2h30m, 24h.

        Default: 24h

        Pattern: ^([0-9]+h)?([0-9]+m)?([0-9]+s)?$

    • settings.tolerations
      array of objects

      The same as in the Pods’ spec.tolerations parameter in Kubernetes.

      If the parameter is omitted, it is determined automatically.

      Example:

      tolerations:
      - key: key1
        operator: Equal
        value: value1
        effect: NoSchedule
      
      • settings.tolerations.effect
        string
      • settings.tolerations.key
        string
      • settings.tolerations.operator
        string
      • settings.tolerations.tolerationSeconds
        integer
      • settings.tolerations.value
        string
    • settings.twoFactor
      object

      Two-factor authentication (2FA) with a one-time code (TOTP) from an authenticator application, with a security key (WebAuthn), or with both, as methods and require set.

      The parameter replaces staticUsers2FA of the earlier versions of the settings, which covered local users only. The module converts staticUsers2FA to this parameter.

      • settings.twoFactor.enabled
        boolean

        Required value

        If set to true, the users of the providers listed in providerTypes will be required to use two-factor authentication (2FA) when logging in.

        Default: false

      • settings.twoFactor.issuerName
        string

        The issuer name for the two-factor authentication (2FA) tokens. This name is visible to users in the 2FA application (e.g., Google Authenticator) and in the dialog of the browser that registers a security key.

        Default: Deckhouse

      • settings.twoFactor.methods
        array of strings

        Second factors of the users of the types in providerTypes, unless providerTypeOverrides sets others for a type:

        • TOTP: A one-time code from an authenticator application (for example, Google Authenticator).
        • WebAuthn: A security key (for example, YubiKey), or the Touch ID or Windows Hello of the device. The key confirms a sign-in only for the domain it is bound to, so a fake sign-in page on another domain gets no response it can reuse.

        With two methods, require sets how they combine.

        A user registers a method at the first sign-in that asks for it (and until then anyone who knows the password can register their own device). The secret or the keys the user had for a method that is no longer asked for stay until a Reset2FA operation, so asking for the method again brings them back.

        Default: ["TOTP"]

        • Element of the array
          string

          Allowed values: TOTP, WebAuthn

      • settings.twoFactor.providerTypeOverrides
        array of objects

        Second factors of the users of one type of provider, instead of methods and require. The type must be listed in providerTypes, and each type appears once.

        • settings.twoFactor.providerTypeOverrides.methods
          array of strings

          Required value

          Second factors of the users of this type, as methods.

          • Element of the array
            string

            Allowed values: TOTP, WebAuthn

        • settings.twoFactor.providerTypeOverrides.providerType
          string

          Required value

          Type of provider, one of providerTypes.

          Allowed values: Local, LDAP, Crowd

        • settings.twoFactor.providerTypeOverrides.require
          string

          How the two methods combine, as require. Required with two methods, and not allowed with one.

          Allowed values: Any, All

      • settings.twoFactor.providerTypes
        array of strings

        Types of the providers whose users have to pass the second factor:

        • Local: The local users (User).
        • LDAP: The users of every DexProvider of the LDAP type.
        • Crowd: The users of every DexProvider of the Crowd type.

        A user enrolls the authenticator at the first sign-in after the second factor is turned on. Until then, anyone who knows the password can enroll their own device, so ask the users to sign in right after the switch.

        Adding a type does not end the refresh tokens or the Dex browser sessions issued before it. A refresh token keeps issuing tokens without the code until it expires, and a browser session created earlier passes without the code. After enabling 2FA, run a UserOperation of type Logout for the users of the providers of the listed types.

        The second factor is not possible together with Basic Authentication to the Kubernetes API, which has no page for a code. A provider of a listed type cannot have enableBasicAuth: true. The module refuses a DexProvider that would have both, and refuses this setting while such a DexProvider exists.

        The OIDC, SAML, GitHub, GitLab and Bitbucket Cloud providers are not on the list. The identity provider handles the second factor for them.

        Default: ["Local"]

        • Element of the array
          string

          Allowed values: Local, LDAP, Crowd

      • settings.twoFactor.require
        string

        How the two methods of methods combine.

        With Any, the user passes one of them. At the first sign-in the user chooses the method and registers it; later Dex asks for a registered method, the one used last first, and a user who has registered both can sign in another way. A user who has registered one method cannot register the other at a sign-in. To change the method, run a Reset2FA operation for the registered method or set All. With All, the user passes both, the code first and then the key. A user who has only one of them confirms the sign-in with it first and only then registers the other.

        Allowed values: Any, All

      • settings.twoFactor.webAuthn
        object

        Parameters of the WebAuthn method.

        • settings.twoFactor.webAuthn.maxCredentials
          integer

          How many keys a user may register.

          The first key is registered at the first sign-in that asks for one. A user adds a further key on the page that confirms a sign-in with a key, after a registered key has confirmed it. A password alone never adds a key.

          Lowering the limit keeps the keys users have; a user with as many keys as the limit, or more, adds none.

          Default: 3

          Allowed values: 1 <= X <= 10

        • settings.twoFactor.webAuthn.rpID
          string

          Domain a registered key is bound to (the relying party ID). A key works only for this domain and its subdomains.

          The browser takes a domain that is the domain of the Dex address (dex.<PUBLIC_DOMAIN>) or its parent, down to a registrable domain (example.com), and refuses any other. By default, it is the domain of the Dex address, so a change of publicDomainTemplate makes every registered key useless, and every user has to register again. Set it to the stable parent domain to keep the keys through such a change.

          Setting or changing the parameter makes the keys registered before it useless as well.

          A user whose key has become useless can neither sign in nor register a new key, because Dex offers the registration only to an account that has no keys, and the old key cannot be used. Reset the second factor of such a user with a UserOperation of type Reset2FA; the user registers a key again at the next sign-in.

          Dex accepts localhost and a lowercase domain of two or more labels, such as example.com or dex.example.com. It refuses any other single label, a final label that is a number (corp.123, and a hexadecimal, binary or octal form such as 0x1), and an IP address.

          Pattern: ^(localhost|[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+)$

          Maximum length: 253

          Example:

          rpID: example.com
          

The module works only with HTTPS, because OpenID Connect over HTTP is a serious security threat and the Kubernetes API server does not support OIDC over HTTP. With https.mode set to Disabled, the module is turned off.

Set https.mode to a value other than Disabled at the cluster level (modules.https.mode) or in the module. If you set the https section of the module, set mode in it too. Without mode, Disabled applies.