📚 课程目录第2章身份认证机制解析

2. 身份认证机制解析

OpenShift 的认证体系有一个关键前提：集群本身不保存用户密码。它把“证明你是谁”这件事交给外部身份提供者（Identity Provider，IdP），自己只负责在认证成功后签发集群内的身份记录与访问令牌。理解这一点，才能理解为什么 OpenShift 支持 OAuth、OpenID Connect、LDAP、HTPasswd 等多种机制，以及它们各自适合什么场景。

一、认证与授权的分工

OpenShift 把访问控制拆成两层：认证（Authentication）解决“你是谁”，由 OAuth 服务器与 IdP 协作完成；授权（Authorization）解决“你能做什么”，由 RBAC 基于用户、组和角色绑定完成。认证成功后，OAuth 服务器会创建两类对象：Identity（记录外部身份与集群用户的映射）和 User（集群内的用户对象）。后续所有权限判断都基于 User 及其所属组。

关键点：IdP 只负责验证凭据，OpenShift 不存储外部密码。因此修改 IdP 中的密码不会影响集群，但删除 IdP 用户会导致其无法再次登录。

二、四种身份提供者的定位与配置

HTPasswd 使用一个由 htpasswd 生成的密钥文件保存用户名与 bcrypt 哈希密码，适合实验、演示和小规模固定用户场景。配置时先创建文件：

htpasswd -c -B -b users.htpasswd devuser 'RedHat123!'
htpasswd -B -b users.htpasswd opsuser 'RedHat456!'

然后创建 Secret 并挂载到 OAuth 配置：

oc create secret generic htpass-secret \
  --from-file=htpasswd=users.htpasswd -n openshift-config

oc apply -f - <<'EOF'
apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: my_htpasswd
    mappingMethod: claim
    type: HTPasswd
    htpasswd:
      fileData:
        name: htpass-secret
EOF

LDAP 适合企业已有目录服务的场景。它通过 url、bindDN、baseDN 和过滤条件查询用户，并可用组同步把 LDAP 组映射为 OpenShift 组。典型配置片段如下：

  - name: my_ldap
    type: LDAP
    ldap:
      url: "ldaps://ldap.example.com/ou=users,dc=example,dc=com?uid"
      bindDN: "cn=directory-reader,dc=example,dc=com"
      bindPassword:
        name: ldap-bind-password
      insecure: false
      ca:
        name: ldap-ca-configmap

OAuth / OpenID Connect 面向现代应用与云身份。OpenID Connect 是建立在 OAuth 2.0 之上的身份层，通过 ID Token（JWT）传递用户身份。OpenShift 内置的 oidc 类型可对接 Keycloak、Azure AD、Okta 等。核心参数包括 issuer、clientID、clientSecret 和 claims 映射：

  - name: my_oidc
    type: OpenIDConnect
    openIDConnect:
      issuer: https://keycloak.example.com/realms/corp
      clientID: openshift
      clientSecret:
        name: oidc-client-secret
      claims:
        preferredUsername: ["preferred_username"]
        name: ["name"]
        email: ["email"]

其中 claims 决定把 ID Token 中的哪些字段映射为集群用户名、显示名和邮箱，直接影响 Identity 的生成结果。

三、用户登录流程

以浏览器登录为例，完整链路如下：用户访问 oauth-openshift 路由，OAuth 服务器根据 identityProviders 列表展示登录选项；用户选择某个 IdP 并提交凭据；OAuth 服务器向 IdP 验证，成功后按 mappingMethod 创建或关联 Identity 与 User；随后签发 OAuth Access Token，用户以该令牌访问 API。命令行则通过 oc login 触发同样的流程，令牌缓存在本地配置中。

四、mappingMethod 与身份映射策略

mappingMethod 决定外部身份如何映射为集群 Identity，是配置中最容易出错的部分：

claim（默认）：首次登录时创建 Identity，之后复用。适合大多数场景。
lookup：只允许已存在的 Identity 登录，不会自动创建。适合管理员预先导入用户的受控环境。
add：每次登录都新建 Identity，容易产生重复用户，一般不建议。

如果 IdP 返回的用户名与已有 Identity 冲突，登录会失败并提示身份已被占用。此时需要检查 claims 映射是否稳定，避免同一用户因字段变化被识别为不同身份。

五、配置后的验证与排障

修改 OAuth 配置后，oauth-openshift 会滚动重启，通常需要等待 1～2 分钟。验证时先确认 Pod 状态：

oc get pods -n openshift-authentication
oc get oauth cluster -o yaml | grep -A5 identityProviders

若登录失败，按以下顺序排查：IdP 连通性（LDAP 端口、OIDC issuer 可达性）、Secret 是否存在且键名正确、claims 是否与 IdP 实际返回字段一致、mappingMethod 是否与预期匹配。查看 OAuth Pod 日志可看到具体的验证错误：

oc logs -n openshift-authentication deployment/oauth-openshift --tail=50

修改 identityProviders 会触发 OAuth 服务器重启，期间已有令牌仍然有效，但新登录会短暂不可用。生产环境建议在维护窗口操作，并保留原配置备份。

六、选型建议

IdP 类型	适用场景	关键配置	注意事项
HTPasswd	实验、演示、少量固定用户	Secret + htpasswd 文件	密码变更需重建 Secret
LDAP	企业已有目录服务	url、bindDN、baseDN	需配置 CA 与组同步
OpenID Connect	云身份、SSO、现代应用	issuer、clientID、claims	claims 映射必须稳定
OAuth	对接第三方 OAuth 2.0 服务	clientID、clientSecret、urls	需确认用户信息接口

实际生产中，常见做法是同时配置多个 IdP：用 LDAP 或 OpenID Connect 承载正式用户，用 HTPasswd 保留一个应急管理员账号，避免 IdP 故障时完全无法登录集群。无论选择哪种方式，认证只解决“你是谁”，真正的权限边界仍由 RBAC 决定，这也是下一部分要展开的内容。