Set Up External Authentication

This document describes how to use an external identity provider such as an LDAP service or Active Directory service on KubeSphere.

KubeSphere provides a built-in OAuth server. Users can obtain OAuth access tokens to authenticate themselves to the KubeSphere API. As a KubeSphere administrator, you can edit the kubesphere-config ConfigMap to configure OAuth and specify identity providers.

Prerequisites

You need to deploy a Kubernetes cluster and install KubeSphere in the cluster. For details, see Installing on Linux and Installing on Kubernetes.

Procedure

  1. Log in to KubeSphere as admin, move the cursor to Set Up External Authentication - 图1 in the bottom-right corner, click Kubectl, and run the following command to edit the kubesphere-config ConfigMap:

    1. kubectl -n kubesphere-system edit cm kubesphere-config

  2. Configure fields in the data:kubesphere.yaml:authentication section.

    Example:

    1. apiVersion: v1
    2. data:
    3.   kubesphere.yaml: |
    4.     authentication:
    5.       authenticateRateLimiterMaxTries: 10
    6.       authenticateRateLimiterDuration: 10m0s
    7.       loginHistoryRetentionPeriod: 168h
    8.       maximumClockSkew: 10s
    9.       multipleLogin: true
    10.       jwtSecret: "********"
    11.       oauthOptions:
    12.         accessTokenMaxAge: 1h
    13.         accessTokenInactivityTimeout: 30m
    14.         identityProviders:
    15.         - name: ldap
    16.           type: LDAPIdentityProvider
    17.           mappingMethod: auto
    18.           provider:
    19.             host: 192.168.0.2:389
    20.             managerDN: uid=root,cn=users,dc=nas
    21.             managerPassword: ********
    22.             userSearchBase: cn=users,dc=nas
    23.             loginAttribute: uid
    24.             mailAttribute: mail

    The fields are described as follows:

    • authenticateRateLimiterMaxTries: Maximum number of consecutive login failures allowed during a period specified by authenticateRateLimiterDuration. If the number of consecutive login failures of a user reaches the limit, the user will be blocked.

    • authenticateRateLimiterDuration: Period during which authenticateRateLimiterMaxTries applies.

    • loginHistoryRetentionPeriod: Retention period of login records. Outdated login records are automatically deleted.

    • maximumClockSkew: Maximum clock skew for time-sensitive operations such as token expiration validation. The default value is 10s.

    • multipleLogin: Whether multiple users are allowed to log in from different locations. The default value is true.

    • jwtSecret: Secret used to sign user tokens. In a multi-cluster environment, all clusters must use the same Secret.

    • oauthOptions: OAuth settings.

      • accessTokenMaxAge: Access token lifetime. For member clusters in a multi-cluster environment, the default value is 0h, which means access tokens never expire. For other clusters, the default value is 2h.
      • accessTokenInactivityTimeout: Access token inactivity timeout period. An access token becomes invalid after it is idle for a period specified by this field. After an access token times out, the user needs to obtain a new access token to regain access.
      • identityProviders: Identity providers.
        • name: Identity provider name.
        • type: Identity provider type.
        • mappingMethod: Account mapping method. The value can be auto or lookup.
          • If the value is auto (default), you need to specify a new username. KubeSphere automatically creates a user according to the username and maps the user to a third-party account.
          • If the value is lookup, you need to perform step 3 to manually map an existing KubeSphere user to a third-party account.
        • provider: Identity provider information. Fields in this section vary according to the identity provider type.

  3. If mappingMethod is set to lookup, run the following command and add the labels to map a KubeSphere user to a third-party account. Skip this step if mappingMethod is set to auto.

    1. kubectl edit user <KubeSphere username>
    1. labels:
    2.   iam.kubesphere.io/identify-provider: <Identity provider name>
    3.   iam.kubesphere.io/origin-uid: <Third-party username>

  4. After the fields are configured, run the following command to restart ks-apiserver.

    1. kubectl -n kubesphere-system rollout restart deploy/ks-apiserver