为 OIDC 身份验证设置舰队成员集群

本文档介绍集群管理员或应用运维人员如何配置集群以支持使用第三方 OpenID Connect (OIDC) 提供方进行身份验证。

限制

您必须使用支持 OIDC 的集群类型。

准备工作

  1. Install the Google Cloud CLI.

  2. 如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

  3. 如需初始化 gcloud CLI，请运行以下命令： 

    gcloud init

  4. 初始化 gcloud CLI 后，对其进行更新并安装所需组件： 

    gcloud components update
gcloud components install kubectl
  5. 请确保平台管理员已为您提供所需的所有提供方信息。如需了解详情，请参阅分享身份提供方详细信息。
  6. 如需通过 Google Cloud 控制台进行身份验证，请向项目舰队注册要配置的每个集群。如需了解详情，请参阅舰队创建概览。
  7. 如需通过堡垒主机连接到当前 VPC 网络外部的 AWS 或 Azure 集群的控制平面，请确保您已创建堡垒主机并在端口 8118 上启动 SSH 隧道。在本文档中运行 kubectl 命令时，请在命令前添加 HTTPS_PROXY=http://localhost:PORT，其中 PORT 是您在启动 SSH 隧道时使用的端口号。
  8. 对于 Google Cloud上的 GKE 集群，请将集群注册到舰队。

配置集群

如需使用 OIDC 配置集群的身份验证，请将以下信息添加到名为 ClientConfig 的 Kubernetes 自定义资源中：

  • 有关身份提供方的信息，例如客户端 ID 和 Secret。
  • 有关身份提供方用于身份验证的 JSON Web 令牌 (JWT) 的信息。
  • 特定于身份提供商的任何其他范围或参数。

如需详细了解您需要从平台管理员或组织中管理身份的人员处获取哪些信息，请参阅共享身份提供方详细信息。

集群使用 ClientConfig 自定义资源中的字段与身份提供方进行交互。每个集群在 kube-public 命名空间中都有一个名为 default 的 ClientConfig。您修改的具体字段取决于您的身份提供商。

如要修改 default ClientConfig，请确保您可以连接到集群 kubectl，然后运行以下命令：

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

将 KUBECONFIG_PATH 替换为集群的 kubeconfig 文件的路径，例如 $HOME/.kube/config。

文本编辑器会加载集群的 ClientConfig 资源。添加 spec.authentication.oidc 对象，如以下示例所示。请勿修改已写入的任何默认数据。

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL
# Rest of the resource is managed by Google. DO NOT MODIFY.

例如，我们来看看以下身份令牌字段：

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  # Multiple lines are omitted here
}

在此示例中，iss 是身份提供方 URI，sub 用于标识用户，groupList 用于列出用户所属的安全群组。此示例仅显示了实际令牌可能包含的部分字段。

对于上述示例令牌，您需要更新 ClientConfig 的 spec.authentication.oidc 对象中的以下字段：

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

您可以向同一 ClientConfig 添加多个 OIDC、LDAP 和 SAML 身份提供方配置。集群会按照配置的定义顺序依次尝试进行身份验证，并在首次成功完成身份验证后停止尝试。以下示例 ClientConfig 按特定顺序定义了多个身份提供方：

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

ClientConfig OIDC 字段

下表介绍了 ClientConfig oidc 对象的字段。您需要添加的字段取决于您的身份提供方令牌以及平台管理员配置提供方的方式。

字段 必需 说明 格式
name 是 您要用于标识此配置的名称，通常是身份提供方名称。配置名称必须以字母开头，后面最多可跟 39 个小写字母、数字或连字符，但不能以连字符结尾。 字符串
certificateAuthorityData 否 如果平台管理员提供，则该字段为身份提供方的 PEM 编码证书字符串。将生成的字符串作为单独的一行添加到 certificateAuthorityData 中。 字符串
clientID 是 身份提供方的客户端 ID。 字符串
clientSecret 否 OIDC 客户端应用和 OIDC 提供方之间的共享密钥令牌。 字符串
deployCloudConsoleProxy 否 指定是否部署一个代理，该代理允许 Google Cloud 控制台连接到无法通过互联网公开访问的本地身份提供方。默认情况下，该设置为 false。 布尔值
extraParams 否 要发送到身份提供方的其他键值对参数，以英文逗号分隔列表的形式指定，例如“prompt=consent,access_type=offline”。 英文逗号分隔列表
groupsClaim 否 您的提供方用于返回账号的安全群组的 JWT 声明（字段名称）。 字符串
groupPrefix 否 如果您有多个身份提供方的配置（通常是提供方名称），则该字段为您要附加到安全群组名称的前缀，以避免与访问权限控制规则中的现有名称冲突。 字符串
issuerURI 是 用于向您的身份提供方发出授权请求的 URI。URI 必须使用 HTTPS，且不应以尾随斜杠结尾。 网址字符串
kubectlRedirectURI 是 gcloud CLI 使用的重定向网址和端口，由平台管理员在注册时指定，通常采用 http://localhost:PORT/callback 形式。 网址字符串
scopes 是 要发送到 OpenID 提供方的其他范围。例如，Microsoft Azure 和 Okta 需要 offline_access 范围。 英文逗号分隔列表
userClaim 否 您的提供方用于识别用户账号的 JWT 声明（字段名称）。如果您未在此处指定值，则默认值为“sub”，这是许多提供方使用的用户 ID 声明。您可以选择其他声明，例如“电子邮件”或“名称”，具体取决于 OpenID 提供方。“电子邮件”以外的声明会以颁发者网址作为前缀，以防止命名冲突。 字符串
userPrefix 否 如果您不想使用默认前缀，则该字段为您要附加到用户声明的前缀，以防止与现有名称冲突。 字符串
enableAccessToken 否 启用后，当用户从命令行登录时，集群可以使用身份提供方的 userinfo 端点获取群组信息。如果您的提供方（例如 Okta）提供来自此端点的群组声明，您便可以使用安全群组进行授权。如果未设置，则视为 false。 布尔值
proxy 否 用于连接到身份提供方的代理服务器地址（如适用）。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供方，则可能需要设置此字段。例如：http://user:password@10.10.10.10:8888。 字符串

修改 ClientConfig 后，保存文件以更新集群的 ClientConfig。如果有任何语法错误，系统会提示您修正这些错误并保存文件。

特定于提供方的配置

本部分提供一些常见 OIDC 提供方的配置指南，包括您可以复制和使用自己的详细信息修改的示例配置。

Microsoft Entra ID

这是使用 Microsoft Entra ID 设置集群以进行身份验证的默认配置。通过使用此配置，集群可以从 Microsoft Entra ID 获取用户和群组成员资格信息，此外，您可以根据群组设置 Kubernetes 基于角色的访问控制 (RBAC)。不过，如果使用此配置，对于每位用户，您最多只能检索大约 200 个群组。

如果对于每位用户，您需要检索 200 个以上的群组，请参阅 Microsoft Entra ID（高级）部分的说明。

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

替换以下内容：

  • CLIENT_ID：Microsoft Entra ID 中的客户端 ID。
  • CLIENT_SECRET：OIDC 客户端应用和 OIDC 提供方之间的共享密钥。
  • TENANT_ID：要进行身份验证的 Microsoft Entra ID 账号的种类。支持的值为租户 ID，或属于特定租户的账号的租户名称。租户名称也称为主域名。如需详细了解如何查找这些值，请参阅查找 Microsoft Entra 租户 ID 和主域名。
  • PORT：为 gcloud CLI 使用的重定向网址选择的端口号，由平台管理员在注册时指定。

Microsoft Entra ID（高级）

通过 Microsoft Entra ID 的此可选配置，集群可以使用 Microsoft Graph API 检索用户和群组信息，并且对于可针对每位用户检索的群组数量，没有任何限制。

如需了解支持此配置的平台，请参阅 Microsoft Entra ID 的高级设置。

如果需要针对每位用户检索的群组数量少于 200 个，则建议您使用默认配置，即在您的 ClientConfig 中使用一个 oidc 锚标记。如需了解详情，请参阅 Microsoft Entra ID 的相关说明。

以下示例配置中的所有字段都是必填字段。

# Multiple lines are omitted here.
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM
# Multiple lines are omitted here. Do not modify any pre-filled data.

替换以下内容：

  • NAME：您要用于标识此配置的名称，通常是身份提供方名称。配置名称必须以字母开头，后面最多可跟 39 个小写字母、数字或连字符，但不能以连字符结尾。
  • PROXY_URL：用于连接到身份提供方的代理服务器地址（如适用）。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供方，则可能需要设置此字段。例如：http://user:password@10.10.10.10:8888。
  • CLIENT_ID：Microsoft Entra ID 中的客户端 ID。
  • CLIENT_SECRET：OIDC 客户端应用和 OIDC 提供方之间的共享密钥。
  • TENANT：要进行身份验证的 Microsoft Entra 账号的种类。支持的值为租户 ID，或属于特定租户的账号的租户名称。租户名称也称为主域名。如需详细了解如何查找这些值，请参阅查找 Microsoft Entra 租户 ID 和主域名。
  • PORT：为 gcloud CLI 使用的重定向网址选择的端口号，由平台管理员在注册时指定。
  • GROUP_FORMAT：您要检索群组信息的格式。此字段可以接受与用户群组的 ID 或 NAME 相对应的值。请注意，此设置仅适用于裸金属 Google Distributed Cloud 部署中的集群。
  • USER_CLAIM（可选）：您的提供方用于识别账号的 JWT 声明（字段名称）。如果您未在此处指定值，则集群会依次使用“email”“preferred_username”或“sub”的值，以获取用户详细信息。此属性可从 1.28 版开始使用。

Okta

下面向您展示了如何使用用户和群组设置身份验证，并将 Okta 作为您的身份提供方。此配置允许集群使用访问令牌和 Okta 的 userinfo 端点检索用户和群组声明。

# Multiple lines are omitted here.
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

群组访问限制

对于 Okta 用户，集群可以检索群组名称（如果串联起来）长度小于 170,000 个字符的用户的群组信息。考虑到 Okta 的最大群组长度，这对应于大约 650 个群组的成员资格。如果用户是过多群组的成员，则身份验证调用将失败。

后续步骤

应用配置后，继续设置用户对集群的访问权限。