使用 OIDC 和 Google 进行身份验证

注意：请务必提前规划您的安装。创建集群后，您的集群配置（在 GKE On-Prem 配置文件中声明）便无法再改变。创建集群后，您将无法更改其大部分内容，包括网络和身份验证。以下是可配置的例外情况：

• 调整用户集群的大小
• 创建额外的用户集群
• 升级集群
• 创建和管理节点池

了解如何在 GKE On-Prem 中配置 OpenID Connect (OIDC)，并将 Google 用作 OpenID 提供方。

如需大致了解 GKE On-Prem 身份验证流程，请参阅身份验证。请参阅以下主题，了解如何使用其他 OpenID 提供方配置 OIDC：

• Active Directory Federation Services
• 任何 OpenID 提供方

概览

GKE On-Prem 支持将 OIDC 用作与用户集群的 Kubernetes API 服务器进行交互的身份验证机制之一。借助 OIDC，您可以按照组织中创建、启用和停用用户帐号的标准程序来管理对 Kubernetes 集群的访问权限。

用户可以通过以下两种方式为其帐号授权：

• 使用 Google Cloud CLI 启动 OIDC 流程，并通过基于浏览器的同意页面获取用户授权。

• 使用 Google Cloud Console 启动 OIDC 身份验证流程。

准备工作

• 本主题假定您熟悉以下身份验证和 OpenID 概念：

  • OAuth 2.0
  • OpenID Connect
  • 范围
  • 声明。

• Google OpenID 提供方不支持群组。当您使用 Kubernetes 基于角色的访问权限控制 (RBAC) 来向经过身份验证的用户授予角色时，必须将角色授予每个用户，而非群组。

• 不支持无头系统。基于浏览器的身份验证流程用于提示您同意并授权您的用户帐号。

• 如需通过 Google Cloud Console 进行身份验证，您要配置进行 OIDC 身份验证的每个集群都必须向 Google Cloud 注册。

角色

本主题涉及三个角色：

• 组织管理员：此角色选择 OpenID 提供方，并向提供方注册客户端应用。

• 集群管理员：此角色创建一个或多个用户集群，并为使用这些集群的开发者创建身份验证配置文件。

• 开发者：此角色在一个或多个集群上运行工作负载，并使用 OIDC 进行身份验证。

创建重定向网址

本部分面向组织管理员。

您必须为 gcloud CLI 和 Google Cloud 控制台创建重定向网址，以便 OpenID 提供方可使用此类网址返回 ID 令牌。

gcloud CLI 重定向网址

Google Cloud CLI 安装在每个开发者的本地机器上，并包含 gcloud CLI。您可以指定大于 1024 的端口号，以用于重定向网址：

http://localhost:[PORT]/callback

其中，[PORT] 是您的端口号。

配置 Google OpenID 提供商时，请将 http://localhost:[PORT]/callback 指定为其中一个重定向网址。

Google Cloud 控制台重定向网址

Google Cloud 控制台的重定向网址为：

https://console.cloud.google.com/kubernetes/oidc

配置 Google OpenID 提供商时，请将 https://console.cloud.google.com/kubernetes/oidc 指定为其中一个重定向网址。

配置您的权限请求屏幕

在此部分中，您将配置 Google 的 OAuth 权限请求屏幕。当您组织中的开发者向用户集群启动身份验证时，系统会转到此权限请求屏幕。届时，他们会向 Google 证明自己的身份，并授权 Google 创建令牌，以向 OAuth 客户端提供识别信息。在本主题中，OAuth 客户端是 gcloud CLI 或 Google Cloud 控制台。

1. 转到 Google Cloud Console 中的 OAuth 权限请求屏幕页面。

   配置 OAuth 权限请求屏幕

2. 选择内部，然后点击创建。

3. 对于应用类型，选择内部。

4. 对于应用名称，输入您选择的名称。建议使用 GKE on-prem。

5. 在授权网域下，添加 google.com。

6. 根据需要填写其他字段。

7. 点击保存。

向 Google 注册客户端应用

在本部分中，您将向 Google 注册 GKE On-Prem，以便 Google 可以充当贵组织中开发者的 OpenID 提供方。作为注册的一部分，您必须提供您之前创建的两个重定向网址。

1. 转到 Google Cloud Console 中的凭据页面。

   转到“凭据”页面

2. 点击创建凭据并选择 OAuth 客户端 ID。

3. 对于应用类型，选择 Web 应用。

4. 对于名称，输入您选择的名称。

5. 在已获授权的重定向 URI 下，添加两个重定向网址。回想一下，您已为 gcloud CLI 创建了重定向网址并为 Google Cloud 控制台创建了重定向网址。

6. 点击创建。

7. 系统会为您提供客户端 ID 和客户端密钥。保存这些内容以备日后使用。

在 GKE On-Prem 配置文件中填充 oidc 规范

本部分面向集群管理员。

在创建用户集群之前，可使用 gkectl create-config 生成 GKE On-Prem 配置文件。配置包括以下 oidc 规范。您必须使用提供方特定的值填充 oidc：

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:

• issuerurl：将此项设置为 "https://accounts.google.com"。客户端应用（如 gcloud CLI 和 Google Cloud 控制台）会向此网址发送授权请求。Kubernetes API 服务器使用此网址来发现用于验证令牌的公钥。
• kubectlredirecturl:：必填。您之前配置的 gcloud CLI 重定向网址。
• clientid：向 OpenID 提供商发出身份验证请求的客户端应用的 ID。gcloud CLI 和 Google Cloud 控制台都使用此 ID。当您通过 Google 注册客户端应用时，系统会向您提供此 ID。
• clientsecret：客户端应用的密钥。gcloud CLI 和 Google Cloud 控制台都使用此密钥。当您通过 Google 注册客户端应用时，系统会向您提供此 ID。
• username：将此项设置为 "email"。
• usernameprefix：可选。附加到用户名声明前面的前缀，以防止与现有名称冲突。如果您未提供此字段，并且 username 是 email 以外的值，则前缀默认为 issuerurl#。您可以使用值 - 停用所有前缀。
• group：将此项留空。
• groupprefix：将此项留空。
• scopes：将此项设置为 "email"。
• extraparams：将此项设置为 "prompt=consent,access_type=offline"。
• usehttpproxy：将此项设置为 "false"。
• capath：将此项留空。

为您的用户集群创建 RBAC 政策

本部分面向集群管理员。

创建集群后，请使用 Kubernetes 基于角色的访问权限控制 (RBAC) 向经过身份验证的集群用户授予访问权限。要授予对特定命名空间中的资源的访问权限，请创建 Role 和 RoleBinding。要授予对整个集群的资源的访问权限，请创建 ClusterRole 和 ClusterRoleBinding。

使用 Google 作为 OpenID 提供方时，您必须向单个用户授予访问权限。授予群组访问权限无效。这是因为 Google OpenID 提供商返回的令牌不包含有关单个用户所属群组的任何信息。

例如，假设您希望 [e-mail] 可以查看集群中的所有 Secret 对象。

以下是名为 secret-viewer 的 ClusterRole 的清单。被授予此角色的人可以获取、查看和列出集群中的任何 Secret。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-viewer
rules:
- apiGroups: [""]
  # The resource type for which access is granted
  resources: ["secrets"]
  # The permissions granted by the ClusterRole
  verbs: ["get", "watch", "list"]

以下是名为 people-who-view-secrets 的 ClusterRoleBinding 的清单。绑定会将 secret-viewer 角色授予名为 [e-mail] 的用户。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: people-who-view-secrets
subjects:
- kind: User
  name: [e-mail]
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-viewer
  apiGroup: rbac.authorization.k8s.io

要创建 ClusterRole，请将清单保存到名为 secret-viewer-cluster-role.yaml 的文件中，然后输入以下命令：

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] apply -f secret-viewer-cluster-role.yaml

其中，[USER_CLUSTR_KUBECONFIG] 是用户集群的 kubeconfig 文件。

要创建 ClusterRoleBinding，请将清单保存到名为 secret-viewer-cluster-role-binding.yaml 的文件中，然后输入以下命令：

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] apply -f secret-viewer-cluster-role-binding.yaml

创建和分发身份验证配置文件

本部分面向集群管理员。

创建用户集群后，您可以为该集群创建身份验证配置文件。您可以在单个身份验证配置文件中配置多个集群。您必须向要对每个集群进行身份验证的用户提供每个身份验证配置文件。

创建身份验证配置文件

要在当前目录中创建身份验证配置文件，请运行以下 gkectl 命令：

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

其中，[USER_CLUSTER_KUBECONFIG] 是用户集群的 kubeconfig 文件的路径。在您运行 gkectl create cluster 创建用户集群时，系统已创建您的 kubeconfig 文件。

结果：在当前目录中创建名为 kubectl-anthos-config.yaml 的身份验证配置文件。

将多个集群添加到身份验证配置文件

您可以将多个集群的身份验证配置详细信息存储在单个身份验证配置文件中。

您可以使用以下命令将额外的用户集群身份验证详细信息合并到现有身份验证配置文件中。如果存在现有身份验证配置文件，您可以合并或组合额外的用户集群身份验证详细信息：

• 将额外的用户集群身份验证详细信息合并到现有身份验证配置文件中。
• 将额外的用户集群身份验证详细信息组合到一个新文件中。

例如，您可能需要同时管理 anthos-config-1cluster.yaml 和 anthos-config-3clusters.yaml 身份验证配置文件，以满足贵组织中多个用户群组的访问需求。

要向现有身份验证配置文件添加额外的用户集群，请执行以下操作：

1. 确保每个集群的名称唯一。如果您的集群具有相同的名称，则无法将它们组合到同一身份验证配置文件中。请注意，创建集群后，无法重命名该集群。

2. 运行以下 gkectl 命令以合并或组合配置详细信息：

   gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG] \
   --merge-from [IN_AUTH_CONFIG_FILE] --output [OUT_AUTH_CONFIG_FILE]

   其中

   • [USER_CLUSTER_KUBECONFIG] 指定要添加的用户集群的 kubeconfig 文件。

   • [IN_AUTH_CONFIG_FILE] 指定要与额外的集群信息合并的现有身份验证配置文件的路径。

   • [OUT_AUTH_CONFIG_FILE] 指定要存储合并的身份验证配置的文件的路径：

     • 指定与 [IN_AUTH_CONFIG_FILE] 相同的文件，以便将额外的集群信息合并到该现有文件中。
     • 指定新的路径和文件名，以将身份验证配置详细信息组合到新文件中。

分发身份验证配置文件

要让您的用户可针对您的用户集群进行身份验证，您必须向他们提供访问您创建的一个或多个身份验证配置文件的权限。请注意，以下步骤使用默认文件名和 gcloud CLI 所需的位置。如需了解如何使用备用文件名和位置，请参阅自定义配置。

考虑通过以下方式分发身份验证配置文件：

• 将文件托管在可访问的网址。如果您在 gcloud anthos auth login 命令中添加 --login-config 标志，则 gcloud CLI 会从该位置获取身份验证配置文件。

  考虑将文件托管在安全主机上。如需详细了解如何使用 PEM 证书进行安全 HTTPS 访问，请参阅 gcloud CLI 的 --login-config-cert 标志。

• 手动向每个用户提供文件。用户下载文件后，您必须告知他们如何将文件存储在默认位置以及使用 gcloud CLI 预期的默认文件名。

  例如，用户可以运行以下命令以使用默认 kubectl-anthos-config.yaml 文件名和默认位置存储身份验证配置文件：

  Linux

  mkdir -p  $HOME/.config/google/anthos/
  cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

  其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。例如 kubectl-anthos-config.yaml。

  macOS

  mkdir -p  $HOME/Library/Preferences/google/anthos/
  cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

  其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。例如 kubectl-anthos-config.yaml。

  Windows

  md "%APPDATA%\google\anthos"
  copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

  其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。例如 kubectl-anthos-config.yaml。

• 使用内部工具将身份验证配置文件推送到每个用户的机器上。例如，您可以使用工具将使用默认 kubectl-anthos-config.yaml 文件名的文件推送到每个用户机器上的默认位置：

  Linux

  $HOME/.config/google/anthos/kubectl-anthos-config.yaml

  macOS

  $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

  Windows

  %APPDATA%\google\anthos\kubectl-anthos-config.yaml

自定义配置

gcloud CLI 要求将身份验证配置文件存储在默认位置，并使用上一部分中提到的默认文件名 kubectl-anthos-config.yaml。但是，您可以选择在其他位置重命名或存储身份验证配置文件。如果文件的名称和位置与默认名称和位置不同，您必须将 --login-config 标志附加到对集群进行身份验证时运行的每条命令。额外的命令标志传入自定义路径和文件名。如需详细了解该命令标志，请参阅通过 gcloud CLI 进行身份验证。

安装 gcloud CLI

本部分面向集群管理员和开发者。

每位需要向集群进行身份验证的开发者或用户都必须在自己的机器上安装 Cloud SDK。Anthos 身份验证命令已作为 anthos-auth 组件 集成到 gcloud CLI 中。

• 如果您使用的是旧版“适用于 Kubectl 的 Anthos 插件”，则必须卸载该插件，然后才能安装 gcloud CLI 和 anthos-auth 组件。

• 如果您有现有版本的 gcloud CLI，请安装其最新版本和 anthos-auth 组件。

移除旧插件

您必须先卸载旧插件，然后才能使用 gcloud CLI 的 anthos-auth 组件。您可以通过运行以下命令来检查机器上是否存在某个旧式的基于 kubectl 的插件：

kubectl anthos version

• 如果该命令返回 Error: unknown command "anthos" for "kubectl"，则表明未找到任何插件，您可以跳至下一部分。

• 如果发现 1.0beta 版本的插件，则必须找到并删除该插件的二进制文件。运行以下命令列出位置，然后使用该位置从机器中移除二进制文件：

  kubectl plugin list

安装 gcloud CLI 和 gcloud CLI

如需安装 gcloud CLI，您必须先安装 gcloud CLI：

重要提示：如果您将 gcloud CLI 与 GKE On-Prem 搭配使用，则无需拥有 Google 帐号。如果您有帐号，可以选择登录，但无需运行 gcloud init 命令。

1. 安装 gcloud CLI，但跳过 gcloud init 命令。

2. 运行以下命令以安装 anthos-auth 组件：

   gcloud components update
   gcloud components install anthos-auth

3. 通过运行以下任一命令来验证 gcloud CLI 是否已成功安装：

   gcloud anthos auth
   gcloud anthos auth login

   结果：每条命令都应回复有关必需参数和可用选项的详细信息。

获取身份验证配置文件

本部分面向开发者。

您的管理员负责创建您的身份验证配置文件，然后将其提供给您。如需了解详情，请参阅分发身份验证配置文件。

默认情况下，gcloud CLI 会使用默认文件名和存储位置来存储您的身份验证配置文件。如果您获得的是手动提供的文件，并且需要将其保存到机器上，请使用默认值来简化 gcloud 身份验证命令。

使用以下命令将身份验证配置文件复制到默认位置：

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。例如 kubectl-anthos-config.yaml。

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。例如 kubectl-anthos-config.yaml。

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。例如 kubectl-anthos-config.yaml。

如果您选择使用不同的文件名或位置，则可以选择在每个身份验证请求中包括 --login-config 标志。如需详细了解如何使用 gcloud anthos auth login 命令，请参阅以下部分。

使用用户集群进行身份验证

本部分面向开发者。

现在您的机器上已安装了 gcloud CLI，并且管理员已为您提供了身份验证配置文件，接下来您可以使用 gcloud CLI 或 Google Cloud 控制台向集群进行身份验证。

通过 gcloud CLI 进行身份验证

运行 gcloud 命令以向您的集群进行身份验证：

1. 运行 gcloud anthos auth login 命令以启动身份验证流程：

   gcloud anthos auth login \
    --cluster [CLUSTER_NAME] \
    --user [USER_NAME] \
    --login-config [AUTH_CONFIG_FILE_PATH] \
    --login-config-cert [CA_CERT_PEM_FILE] \
    --kubeconfig [USER_CLUSTER_KUBECONFIG]

   其中：

   • [CLUSTER_NAME]（可选）指定用户集群的名称。如果省略此标志，则系统会提示您从身份验证配置文件中指定的用户集群中进行选择。

   • [USER_NAME]（可选）指定存储在 kubeconfig 文件中的凭据的用户名。默认值为 [CLUSTER_NAME]-anthos-default-user。

   • [AUTH_CONFIG_FILE_PATH]（可选）指定存储或托管身份验证配置文件的自定义路径或网址。如果文件位于默认位置，则可以省略此参数。示例：--login-config /path/to/custom/authentication-config.yaml

   • [CA_CERT_PEM_FILE]（可选）指定来自您的 CA 的 PEM 证书文件的路径。如果您的身份验证配置文件是安全托管的，您可以使用 HTTPS 连接访问该文件。示例：--login-config-cert my-cert.pem

   • [USER_CLUSTER_KUBECONFIG]（可选）指定用户集群的 kubeconfig 文件的自定义路径。您的 OpenID 提供方返回的 OIDC ID 令牌存储在 kubeconfig 文件中。

     如果您的 kubeconfig 文件未存储在默认位置，请使用此标志。如果省略此标志，则系统会在默认位置创建新的 kubeconfig 文件。示例：--kubeconfig /path/to/custom.kubeconfig

   示例：

   • 向特定集群进行身份验证：

     gcloud anthos auth login --cluster my-production-cluster
     

   • 使用提示选择要通过身份验证的集群：

     gcloud anthos auth login
     

     结果：

     Please use the --cluster flag to specify a cluster from the list below:
     Source: $HOME/.config/google/anthos/kubectl-anthos-config.yaml
     1. Cluster: test-cluster ServerIP: https://192.168.0.1:6443
     2. Cluster: test-cluster-2 ServerIP: https://192.168.0.2:6443
     3. Cluster: my-production-cluster ServerIP: https://192.168.0.3:6443
     

   • 使用托管的身份验证配置文件：

     gcloud anthos auth login \
      --cluster my-production-cluster \
      --login-config HTTPS://my-secure-server/kubectl-anthos-config.yaml \
      --login-config-cert my-cert.pem
     

2. 在打开的基于浏览器的权限请求屏幕中输入您的凭据。

3. 通过运行其中一个 kubectl 命令来检索有关集群的详细信息，验证身份验证是否成功。例如：

   kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

结果：您的 kubeconfig 文件现在包含一个 ID 令牌，您的 kubectl 命令将使用该令牌向用户集群上的 Kubernetes API 服务器进行身份验证。

使用 SSH 从远程机器进行身份验证

假设您要通过 SSH 连接到远程机器，并从远程机器向用户集群进行身份验证。为此，您的身份验证配置文件必须位于远程机器上，并且您必须能够从本地机器访问 OpenID 提供方。

在本地机器上，运行以下命令：

ssh [USER_NAME]@[REMOTE_MACHINE] -L [LOCAL_PORT]:localhost:[REMOTE_PORT]

其中：

• [USER_NAME] 和 [REMOTE_MACHINE] 是用于通过 SSH 登录的标准值。

• [LOCAL_PORT] 是您在本地机器上选择的用于访问远程机器的开放端口。

• [REMOTE_PORT] 是您为 OIDC 重定向网址配置的端口。您可以在身份验证配置文件的 kubectlRedirectURI 字段中找到此端口。

在 SSH Shell 中，运行以下命令以启动身份验证：

gcloud anthos auth login --login-config [AUTH_CONFIG_FILE]

其中，[AUTH_CONFIG_FILE] 是您的身份验证配置文件在远程机器上的路径。

在本地机器上的浏览器中，转到 http://localhost:[LOCAL_PORT]/login 并完成 OIDC 登录流程。

现在，您的远程机器上的 kubeconfig 文件包含您访问用户集群所需的令牌。

在 SSH Shell 中，验证您是否有权访问用户集群：

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] get nodes

通过 Google Cloud 控制台进行身份验证

从 Google Cloud 控制台中的 Kubernetes 集群页面启动身份验证流程：

1. 打开 Google Cloud 控制台：

   访问 Kubernetes 集群页面

2. 在列表中找到您的 GKE On-Prem 集群，然后点击登录。

3. 选择使用为集群配置的身份提供方服务执行身份验证，然后点击登录。

   系统会将您重定向到您的身份提供方，您可能需要登录或同意 Google Cloud 控制台访问您的帐号。然后，系统会将您重定向回 Google Cloud 控制台中的 Kubernetes 集群页面。

排查 OIDC 配置问题

请查看以下行为和错误，以帮助您解决 OIDC 问题：

配置无效

如果 Google Cloud 控制台无法从集群中读取 OIDC 配置，则登录按钮会被停用。

提供商配置无效

如果您的身份提供方配置无效，点击登录后，身份提供方将显示错误屏幕。按照特定于提供方的说明正确配置提供方或您的集群。

权限无效

如果您完成了身份验证流程，但仍看不到集群的详细信息，请确保您已向与 OIDC 搭配使用的帐号授予了正确的 RBAC 权限。请注意，此帐号可能与您用于访问 Google Cloud 控制台的帐号不同。

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

如果授权服务器提示是否同意，但您未提供所需的身份验证参数，则可能会遇到此错误。向 GKE On-Prem 配置文件的 oidc: extraparams 字段提供 prompt=consent 参数，并使用 --extra-params prompt=consent 标志重新生成客户端身份验证文件。

后续步骤

• 详细了解范围和声明。