使用 OIDC 为 GKE Identity Service 设置集群

本文档适用于希望在单个集群上设置 GKE Identity Service 的集群管理员或应用运维人员，以使开发者和其他用户可以使用来自 OpenID Connect (OIDC) 提供方的现有身份详细信息登录集群。

前提条件

  • 您的集群必须是本地 (VMware 或 Bare Metal)、AWS 或 Azure 上的 GKE 集群。关联集群或 GKE 集群不支持每个集群的 OIDC 配置。
  • 要通过 Google Cloud 控制台进行身份验证，您想要配置进行 OIDC 身份验证的每个集群都必须向项目舰队注册。

准备工作

  • 在开始设置之前，请确保平台管理员已为您提供向您的提供方注册 GKE Identity Service 所需的全部信息，包括 GKE Identity Service 的客户端 ID 和密钥。

  • 确保您已安装以下命令行工具：

    • 最新版本的 Google Cloud CLI，其中包含用于与 Google Cloud 交互的命令行工具 gcloud。如果您需要安装 Google Cloud CLI，请参阅安装指南。
    • kubectl，用于对 Kubernetes 集群运行命令。如果您需要安装 kubectl，请按照这些说明操作。

    如果您使用 Cloud Shell 作为与 Google Cloud 交互的 Shell 环境，则系统会为您安装这些工具。

  • 确保您已初始化要用于在其中注册集群的项目的 gcloud CLI。

  • 如果您需要通过堡垒主机连接到当前 VPC 外部的 AWS 或 Azure GKE 集群的控制平面，请确保在此设置之前创建堡垒主机并在端口 8118 上启动 SSH 隧道。然后在使用本指南时，在 kubectl 命令前面加上 HTTPS_PROXY=http://localhost:8118。如果您在启动 SSH 隧道时使用了其他端口，请将 8118 替换为您选择的端口。

配置集群

如需将集群配置为使用您选择的提供方，GKE Identity Service 需要您指定有关身份提供方的详细信息、为用户识别提供的 JWT 令牌的信息，以及作为客户端应用注册 GKE Identity Service 时提供的其他信息。

例如，如果您的提供方使用以下字段（以及其他字段）创建身份令牌，其中 iss 是身份提供方 URI，sub 用于标识用户，groupList 用于列出用户所属的安全群组：

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

...则您的配置将具有以下相应的字段：

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

您的平台管理员或组织中管理身份的人员应为您提供创建配置所需的大部分信息。

GKE Identity Service 使用名为 ClientConfig 的 Kubernetes 自定义资源 (CRD) 进行集群配置，其中包含 GKE Identity Service 与身份提供方交互所需的全部信息对应的字段。每个 GKE 集群在 kube-public 命名空间中都有一个名为 default 的 ClientConfig 资源，您可以按照以下说明使用配置详情更新该资源。

您可以在特定于提供方的配置中查看常见提供方的一些特定示例配置。

kubectl

如要修改默认的 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_STRING
      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.
...

下表介绍了 ClientConfig oidc 对象的字段。大部分字段是可选的。您需要添加的字段取决于您的身份提供方，以及您的平台管理员在为 GKE Identity Service 配置提供方时选择的设置选项。

字段 必填 说明 格式
name 是 您要用于标识此配置的名称，通常是身份提供方名称。配置名称必须以字母开头，后面最多可跟 39 个小写字母、数字或连字符，但不能以连字符结尾。 字符串
certificateAuthorityData 否 如果平台管理员提供，则该字段为身份提供方的 PEM 编码证书字符串。将生成的字符串作为单独的一行添加到 certificateAuthorityData 中。 字符串
clientID 是 向您的 OIDC 提供方注册 GKE Identity Service 时返回的客户端 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 声明（字段名称）。如果您未在此处指定值，GKE Identity Service 会使用“sub”，这是许多提供方使用的用户 ID 声明。您可以选择其他声明，例如“电子邮件”或“名称”，具体取决于 OpenID 提供方。“电子邮件”以外的声明会以颁发者网址作为前缀，以防止命名冲突。 字符串
userPrefix 否 如果您不想使用默认前缀，则该字段为您要附加到用户声明的前缀，以防止与现有名称冲突。 字符串
enableAccessToken 否 启用后，当用户从命令行登录时，GKE Identity Service 可以使用身份提供方的 userinfo 端点获取群组信息。如果您的提供方（例如 Okta）提供来自此端点的群组声明，您便可以使用安全群组进行授权。如果未设置，则视为 false。 布尔值
proxy 否 用于连接到身份提供方的代理服务器地址（如适用）。例如，如果您的集群位于专用网络中并且需要连接到公共身份提供方，则可能需要设置此字段。例如：http://user:password@10.10.10.10:8888。 字符串

完成 ClientConfig 后保存文件，以更新集群上的 ClientConfig。如果有任何语法错误，系统会提示您重新修改配置以修复错误。

特定于提供方的配置

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

Azure AD

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

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

...
spec:
  authentication:
  - name: oidc-azuread
    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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

替换以下内容：

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

Azure AD（高级）

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

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

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

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

...
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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

请替换以下内容：

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

Okta

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

...
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

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

群组访问限制

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

后续步骤

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