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.

    • 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

    The TTL of the id token (use s for seconds, m for minutes, h for hours).

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

    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.

      Default: Fair

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

    • settings.passwordPolicy.lockout

      object

      Temporary user lockout settings after consecutive failed login attempts.

      • 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

    object

    Settings for exposing the API server using Ingress.

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