The user-authn module: configuration

• Updates from version 1 to 2:

  Replace publishAPI.enable with publishAPI.enabled.

Schema version: 2

• 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.highAvailability

    boolean

    Manually enable the high availability mode.

    By default, Deckhouse automatically decides whether to enable the HA mode. Click here to learn more about the HA mode for modules.

    Examples:

    highAvailability: true
    

    highAvailability: false
    

  • settings.https

    object

    What certificate type to use with Dex/kubeconfig-generator.

    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.https.certManager.clusterIssuerName

        string

        What ClusterIssuer to use for Dex/kubeconfig-generator.

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

        Default: letsencrypt

    • settings.https.customCertificate

      object
      • settings.https.customCertificate.secretName

        string

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

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

        Default: false

    • settings.https.mode

      string

      The HTTPS usage mode:

      • CertManager — Dex/kubeconfig-generator will use HTTPS and get a certificate from the ClusterIssuer defined in the certManager.clusterIssuerName parameter.
      • CustomCertificate — Dex/kubeconfig-generator will use HTTPS using the certificate from the d8-system namespace.
      • Disabled — Dex/kubeconfig-generator will work over HTTP only;
      • OnlyInURI — Dex/kubeconfig-generator will work over HTTP (thinking that there is an external HTTPS load balancer in front that terminates HTTPS traffic). All the links in the user-authn will be generated using the HTTPS scheme. Load balancer should provide a redirect from HTTP to HTTPS.

      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.

    Should be less than 6 hours (Dex signing keys rotate every 6 hours). A value of 6 hours or more raises the D8UserAuthnIDTokenTTLTooLong alert.

    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.

    The next version of the module settings (spec.version of the ModuleConfig) accepts only values less than 6 hours. When a ModuleConfig of an earlier settings version is converted to it, a value of 6 hours or more is replaced with 5h59m, which Dex and DexAuthenticator then use. Lowering idTokenTTL from 6 hours or more, in the ModuleConfig or by this conversion, has the following effects:

    • DexAuthenticator sessions whose keepUsersLoggedInFor is less than the previous idTokenTTL become shorter. A session lasts keepUsersLoggedInFor or idTokenTTL + 1s, whichever is longer. For example, when idTokenTTL goes from 24h to 5h59m, a session with keepUsersLoggedInFor: 12h lasts 12 hours instead of 24 hours and 1 second.
    • ID tokens that Dex signed before the change with the signing key current at that moment can be rejected about 6 to 12 hours after the change, before they expire, because Dex then keeps a replaced signing key only for as long as the new idTokenTTL requires. A client that refreshes an ID token only when it expires, such as kubectl with auth-provider: oidc in the kubeconfig, keeps sending the rejected token until the token expires. To make such a client request a new token, remove id-token from its kubeconfig.

    To choose when this happens, lower idTokenTTL in the ModuleConfig in advance.

    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/kubeconfig-generator.

    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

      If you plan to use a TCP proxy, then you must configure a certificate on the API server’s side for the TCP proxy address. Suppose your API servers use three different addresses (192.168.0.10, 192.168.0.11, and 192.168.0.12) while the client uses a TCP load balancer (say, 192.168.0.15). In this case, you have to re-generate the API server certificates:

      • edit kubeadm-config: d8 k -n kube-system edit configmap kubeadm-config and add 192.168.0.15 to .apiServer.certSANs;
      • save the resulting config: kubeadm config view > kubeadmconf.yaml;
      • delete old API server certificates: mv /etc/kubernetes/pki/apiserver.* /tmp/;
      • reissue new certificates: kubeadm init phase certs apiserver --config=kubeadmconf.yaml;
      • restart the API server’s container: docker ps -a | grep 'kube-apiserver' | grep -v pause| awk '{print $1}' | xargs docker restart;
      • repeat this step for all master nodes.
  • settings.nodeSelector

    object

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

    If the parameter is omitted or false, it will be determined automatically.

  • settings.passwordPolicy

    object

    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. Its state is stored in the Password resource and does not need to be opted in here.

        For the listed external connectors, the failed-attempt counter and the lock state are tracked in the OfflineSessions resource of the corresponding user (one object per (user, connector) pair).

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

        • 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

    Settings for exposing the Kubernetes API server using Ingress or Gateway API.

    Important. Starting with version DP 1.77, use the apiserver.publishAPI parameter of the control-plane-manager module to publish the Kubernetes API server.

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

    • settings.publishAPI.addKubeconfigGeneratorEntry

      boolean

      Setting it to false will remove an entry in kubeconfig-generator.

      Default: true

    • settings.publishAPI.enabled

      boolean

      Setting it to true will create an Ingress resource in the d8-user-authn namespace in the cluster (it exposes the Kubernetes API).

      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.

        Use the following command to get the certificate: d8 k -n d8-user-authn get secrets kubernetes-api-ca-key-pair -oyaml.

        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, a per-IP token-bucket rate limiter is installed in front of the POST /token and POST /auth/{connector}/login endpoints. The client IP address is taken from the X-Real-IP header set by the platform Ingress controller.

    The limit applies to failed authentication attempts only: tokens reserved before the request reaches the Dex handler are returned to the bucket on a successful response (HTTP 2xx/3xx). Therefore, successful logins and refresh-token exchanges do not consume the per-IP budget.

    Limits are tracked in memory in each Dex replica. In HA setups, the effective per-IP rate is multiplied by the number of replicas, which is fine as a brute-force backstop and is complemented by the account-level lockout.

    • 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.

    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.staticUsers2FA

    object
    • settings.staticUsers2FA.enabled

      boolean

      Required value

      If set to true, the static users will be required to use two-factor authentication (2FA) when logging in. This option is useful for enhancing security by requiring an additional verification step during the login process.

      Default: false

    • settings.staticUsers2FA.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).

      Default: Deckhouse

  • settings.tolerations

    array of objects

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

    If the parameter is omitted or false, it will be 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