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 ks-installer
of the CRD ClusterConfiguration
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
Log in to KubeSphere as
admin
, move the cursor to in the lower-right corner, click kubectl, and run the following command to editks-installer
of the CRDClusterConfiguration
:kubectl -n kubesphere-system edit cc ks-installer
Add the following fields under
spec.authentication.jwtSecret
.Example:
spec: authentication: jwtSecret: '' authenticateRateLimiterMaxTries: 10 authenticateRateLimiterDuration: 10m0s loginHistoryRetentionPeriod: 168h maximumClockSkew: 10s multipleLogin: true oauthOptions: accessTokenMaxAge: 1h accessTokenInactivityTimeout: 30m identityProviders: - name: LDAP type: LDAPIdentityProvider mappingMethod: auto provider: host: 192.168.0.2:389 managerDN: uid=root,cn=users,dc=nas managerPassword: ******** userSearchBase: cn=users,dc=nas loginAttribute: uid mailAttribute: mail
The fields are described as follows:
jwtSecret
: Secret used to sign user tokens. In a multi-cluster environment, all clusters must use the same Secret.authenticateRateLimiterMaxTries
: Maximum number of consecutive login failures allowed during a period specified byauthenticateRateLimiterDuration
. If the number of consecutive login failures of a user reaches the limit, the user will be blocked.authenticateRateLimiterDuration
: Period during whichauthenticateRateLimiterMaxTries
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 is10s
.multipleLogin
: Whether multiple users are allowed to log in from different locations. The default value istrue
.oauthOptions
: OAuth settings.accessTokenMaxAge
: Access token lifetime. For member clusters in a multi-cluster environment, the default value is0h
, which means access tokens never expire. For other clusters, the default value is2h
.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 beauto
orlookup
.- 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.
- If the value is
provider
: Identity provider information. Fields in this section vary according to the identity provider type.
If
mappingMethod
is set tolookup
, run the following command and add the labels to map a KubeSphere user to a third-party account. Skip this step ifmappingMethod
is set toauto
.kubectl edit user <KubeSphere username>
labels: iam.kubesphere.io/identify-provider: <Identity provider name> iam.kubesphere.io/origin-uid: <Third-party username>
After the fields are configured, save your changes, and wait until the restart of ks-installer is complete.
Note
In a multi-cluster environment, you only need to configure the host cluster.
Identity provider
You can configure multiple identity providers (IdPs) in the 'identityProviders' section. The identity provider authenticates the user and provides an identity token to kubesphere.
Kubesphere provides the following types of identity providers by default:
GitHub Identity Provider
CAS Identity Provider
Aliyun IDaaS Provider
You can also expand the kubesphere OAuth2 authentication plug-in to integrate with your account system.
Feedback
Was this page Helpful?
Receive the latest news, articles and updates from KubeSphere
Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.