Configure Authentication

Objective

This guide demonstrates how to set up authentication. You can use external identity providers such as LDAP or Active Directory for KubeSphere.

Prerequisites

KubeSphere needs to be installed in your machines.

Overview

KubeSphere includes a built-in OAuth server. Users obtain OAuth access tokens to authenticate themselves to the API.

As an administrator, you can configure OAuth by editing configmap to specify an identity provider.

Authentication Configuration

KubeSphere has an internal account management system. You can modify the kubesphere authentication configuration by the following command:

Example Configuration:

  1. kubectl -n kubesphere-system edit cm kubesphere-config
  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: "xxxxxxxxxxxx"
  11.       oauthOptions:
  12.         accessTokenMaxAge: 1h
  13.         accessTokenInactivityTimeout: 30m
  14.         identityProviders:
  15.           ...

For the above example:

ParameterDescription
authenticateRateLimiterMaxTriesAuthenticateRateLimiter defines under which circumstances we will block user.
authenticateRateLimiterDurationA user will be blocked if his/her failed login attempt reaches AuthenticateRateLimiterMaxTries in AuthenticateRateLimiterDuration for about AuthenticateRateLimiterDuration.
loginHistoryRetentionPeriodRetention login history, records beyond this amount will be deleted.
maximumClockSkewControls the maximum allowed clock skew when performing time-sensitive operations, such as validating the expiration time of a user token. The default value for maximum clock skew is 10 seconds.
multipleLoginAllow multiple users login from different location at the same time. The default value for multiple login is true.
jwtSecretSecret to sign user token. Multi-cluster environments need to use the same secret.
accessTokenMaxAgeAccessTokenMaxAge control the lifetime of access tokens. The default lifetime is 2 hours. Setting the accessTokenMaxAge to 0 means the token will not expire, it will be set to 0 when the cluster role is member.
accessTokenInactivityTimeoutInactivity timeout for tokens. The value represents the maximum amount of time that can occur between consecutive uses of the token. Tokens become invalid if they are not used within this temporal window. The user will need to acquire a new token to regain access once a token times out.

After modifying the identity provider configuration, you need to restart the ks-apiserver.

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

Identity Providers

You can define additional authentication configuration in the identityProviders section.

LDAP Authentication

Set LDAPIdentityProvider in the identityProviders section to validate username and password against an LDAPv3 server using simple bind authentication.

During authentication, the LDAP directory is searched for an entry that matches the provided username. If a single unique match is found, a simple bind is attempted using the DN of the entry plus the provided password.

There are four parameters common to all identity providers:

ParameterDescription
nameThe name of the identity provider is associated with the user label.
mappingMethodThe account mapping configuration. You can use different mapping methods, such as:
- auto: The default value. The user account will be automatically created and mapped if the login is successful.
- lookup: Using this method requires you to manually provision accounts.

Example Configuration Using LDAPIdentityProvider:

  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: "xxxxxxxxxxxx"
  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: 4p4@XuP#dP6U
  22.             userSearchBase: cn=users,dc=nas
  23.             loginAttribute: uid
  24.             mailAttribute: mail

For the above example:

ParameterDescription
hostThe name and port of the LDAP server.
managerDNDN to use to bind during the search phase.
managerPasswordPassword to use to bind during the search phase.
userSearchBaseThe search base is the distinguished name (DN) of a level of the directory tree below which all users can be found.
loginAttributeUser naming attributes identify user objects, will be mapped to KubeSphere account name.
mailAttributeThe mail attribute will be mapped to the KubeSphere account.

提示

LDAPS is not supported now. Planned at v3.1.0.