KubeSphere 支持通过 LDAP 和 LDAPS 两种方式进行外部身份验证，以便使用 LDAP 或 LDAPS 用户名和密码登录 KubeSphere 企业版 Web 控制台。

平台管理员可以通过 secret（保密字典）配置 LDAP/LDAPS 身份验证。

LDAP 与 LDAPS 的区别

认证方式 连接方式 安全性

LDAP

使用明文传输，默认端口 389

数据传输未加密，不适合生产环境。

LDAPS

使用 SSL/TLS 加密传输，默认端口 636

数据传输加密，提供更高的安全性，建议在生产环境中使用。

LDAPS (SSL/TLS)

  • 端口：636，使用 SSL/TLS 加密通道，URL 格式：ldaps://hostname:636，类似 HTTPS，在建立连接时就进行 SSL/TLS 握手。

STARTTLS

  • 端口：389（与普通 LDAP 相同），先建立普通连接，然后升级为加密连接，URL 格式：ldap://hostname:389，在建立连接后通过 STARTTLS 命令升级为加密连接。

操作步骤

  1. 以具有 platform-admin 角色的用户登录 KubeSphere 企业版 Web 控制台。

  2. 点击集群管理，并进入 host 集群。

  3. 在左侧导航栏选择配置 > 保密字典。

  4. 在页面点击创建。

  5. 在创建保密字典对话框，点击右上角的编辑 YAML 开关，使用 yaml 创建保密字典。

  6. 按照以下示例及参数说明修改 yaml 文件，配置完成后，点击创建。

  7. 登出 KubeSphere 企业版 Web 控制台，在登录页面，点击通过 LDAP 登录，输入 LDAP/LDAPS 用户名和密码进行登录。

    ldap

说明

多集群环境中，只需要在主集群中进行配置。

LDAP 配置

LDAP 基本配置

apiVersion: v1
kind: Secret
metadata:
  namespace: kubesphere-system  # 请勿修改
  name: identity-provider-ldap  # 确保该 Secret 名称在 Kubernetes 集群中唯一
  labels:
    config.kubesphere.io/type: identityprovider # 请勿修改
    config.kubesphere.io/identityprovider: openldap # 与 configuration.yaml 中的 name 字段保持一致
type: config.kubesphere.io/identityprovider # 请勿修改

stringData:
  configuration.yaml: |
    name: openldap
    type: LDAPIdentityProvider
    mappingMethod: auto
    hidden: false
    disabled: false
    displayName: "Third-party login for LDAP"
    provider:
      # ldap.example.com:389 不带协议时，默认使用 ldap 协议
      host: "ldap://ldap.example.com:389"
      managerDN: "cn=admin,dc=example,dc=com"
      managerPassword: "your-password"
      userSearchBase: "ou=Users,dc=example,dc=com"
      loginAttribute: uid
      mailAttribute: mail

LDAP 完整配置

以下仅展示 stringData:configuration.yaml 下 provider 部分的配置，其他部分请与 LDAP 基本配置的相应部分保持相同。

    provider:
      # 必填项
      host: ldap.example.com:389
      managerDN: cn=admin,dc=example,dc=com
      managerPassword: "your-password"
      userSearchBase: ou=Users,dc=example,dc=com
      loginAttribute: uid
      mailAttribute: mail

      # 可选项
      readTimeout: 15000
      startTLS: false
      insecureSkipVerify: false
      rootCA: /path/to/ca.crt
      rootCAData: "base64_encoded_cert_data"
      userSearchFilter: "(objectClass=person)"
      groupSearchBase: ou=Groups,dc=example,dc=com
      groupSearchFilter: "(objectClass=group)"
      userMemberAttribute: memberOf
      groupMemberAttribute: member
      displayNameAttribute: displayName

LDAP 参数说明

此为 stringData:configuration.yaml 下 provider 部分的参数说明。保密字典中其他部分的参数说明，请参阅配置外部身份验证。

参数 类型 必填 默认值 说明

host

string

是

-

LDAP 服务器地址和端口，格式：host: port。

如果不指定端口，默认为 389 (LDAP) 或 636 (LDAPS)

managerDN

string

是

-

管理员用户的 DN（Distinguished Name）

managerPassword

string

是

-

管理员用户的密码

userSearchBase

string

是

-

用户搜索的基准 DN

loginAttribute

string

是

-

用于比较用户条目的登录属性

mailAttribute

string

是

-

用户邮箱属性名称

readTimeout

int

否

15000

从远程服务器读取数据的超时时间(毫秒)

startTLS

bool

否

false

是否使用 StartTLS 连接。如果指定，连接将使用 ldaps:// 协议

insecureSkipVerify

bool

否

false

是否跳过 TLS 证书验证

rootCA

string

否

-

受信任的根证书文件路径。默认使用主机的根 CA

rootCAData

string

否

-

Base64 编码的 PEM 格式根证书数据

userSearchFilter

string

否

-

用于标识用户对象的 LDAP 过滤器，例如 (objectClass=person)

groupSearchBase

string

否

-

组搜索的基准 DN

groupSearchFilter

string

否

-

用于标识组对象的 LDAP 过滤器，例如 (objectClass=group)

userMemberAttribute

string

否

-

用户对象中存储组成员身份信息的属性

groupMemberAttribute

string

否

-

组对象中存储主要组成员身份信息的属性

displayNameAttribute

string

否

-

用户显示名称的属性名称

LDAPS 配置

apiVersion: v1
kind: Secret
metadata:
  namespace: kubesphere-system  # 请勿修改
  name: identity-provider-ldaps  # 确保该 Secret 名称在 Kubernetes 集群中唯一
  labels:
    config.kubesphere.io/type: identityprovider # 请勿修改
    config.kubesphere.io/identityprovider: openldap # 与 configuration.yaml 中的 name 字段保持一致
type: config.kubesphere.io/identityprovider # 请勿修改

stringData:
  configuration.yaml: |
    name: openldap
    type: LDAPIdentityProvider
    mappingMethod: auto
    hidden: false
    disabled: false
    displayName: "Third-party login for LDAP"
    provider:
      host: "ldaps://ldaps.example.com:636"
      managerDN: "cn=admin,dc=example,dc=com"
      managerPassword: "your-password"
      userSearchBase: "ou=Users,dc=example,dc=com"
      loginAttribute: uid
      mailAttribute: mail
      startTLS: false  # 使用 LDAPS 时设置为 false
      insecureSkipVerify: false  # 生产环境建议设置为 false
      # 如果需要指定 CA 证书，可以添加以下配置
      rootCA: <ca-file>
      rootCAData: <ca-data>

LDAPS 特有配置参数说明

参数 说明

startTLS

  • false: 使用 LDAPS (SSL/TLS) 连接

  • true: 使用 STARTTLS 方式加密连接

insecureSkipVerify

  • false: 验证服务器证书（推荐）

  • true: 跳过服务器证书验证（仅用于测试环境）

rootCA

LDAP 服务器的 CA 证书路径（可选）

rootCAData

LDAP 服务器的 CA 证书内容（可选）

STARTTLS 配置

apiVersion: v1
kind: Secret
metadata:
  namespace: kubesphere-system  # 请勿修改
  name: identity-provider-ldaps  # 确保该 Secret 名称在 Kubernetes 集群中唯一
  labels:
    config.kubesphere.io/type: identityprovider # 请勿修改
    config.kubesphere.io/identityprovider: openldap # 与 configuration.yaml 中的 name 字段保持一致
type: config.kubesphere.io/identityprovider # 请勿修改

stringData:
  configuration.yaml: |
    name: openldap
    type: LDAPIdentityProvider
    mappingMethod: auto
    hidden: false
    disabled: false
    displayName: "Third-party login for LDAP"
    provider:
      # ldap.example.com:389 不带协议时，默认使用 ldap 协议
      host: "ldap://ldaps.example.com:389"
      managerDN: "cn=admin,dc=example,dc=com"
      managerPassword: "your-password"
      userSearchBase: "ou=Users,dc=example,dc=com"
      loginAttribute: uid
      mailAttribute: mail
      startTLS: true  # 设置为 true
      insecureSkipVerify: false  # 生产环境建议设置为 false
      # 如果需要指定 CA 证书，可以添加以下配置其中一个
      rootCA: <ca-file>
      rootCAData: <ca-data>

配置区别: LDAP/LDAPS/STARTTLS

协议 host 协议 startTLS insecureSkipVerify

ldap

ldap

false

-

ldaps

ldaps

true/false

true/false

starttls

ldap

true

true/false