使用 OpenID Connect (OIDC) 进行身份验证

了解如何配置 GKE On-Prem,以使用 OpenID Connect (OIDC) 向用户集群进行身份验证。本主题总体上介绍了该过程,以帮助您了解如何配置 OpenID 提供方。

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

概览

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

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

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

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

准备工作

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

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

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

角色

本主题涉及三个角色:

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

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

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

选择 OpenID 提供方

本部分面向组织管理员

您可以选择使用任何 OpenID 提供方。如需查看经过认证的提供方列表,请参阅 OpenID 认证

对于以下 OpenID 提供方,请参阅以下主题中的特定配置步骤:

创建重定向网址

本部分面向组织管理员

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

gcloud CLI 重定向网址

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

http://localhost:[PORT]/callback

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

配置 OpenID 提供方时,请将 http://localhost:[PORT]/callback 指定为其中一个重定向网址。具体操作方式取决于您的提供方。

Google Cloud 控制台重定向网址

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

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

配置 OIDC 提供方时,请将 https://console.cloud.google.com/kubernetes/oidc 指定为其中一个重定向网址。具体操作方式取决于您的提供方。

向 OpenID 提供方注册您的客户端应用

本部分面向组织管理员

您需要先向 OpenID 提供方注册这两个客户端,您的开发者才可以通过 OpenID 提供方使用 gcloud CLI 或 Google Cloud 控制台。注册包括以下步骤:

  • 了解提供方的颁发者 URI。这是 gcloud CLI 或 Google Cloud 控制台发送身份验证请求的位置。

  • 为提供方提供 gcloud CLI 的重定向网址。

  • 为提供方提供 Google Cloud 控制台的重定向网址。网址为 https://console.cloud.google.com/kubernetes/oidc。

  • 确定单个客户端 ID。这是提供方用于标识 gcloud CLI 和 Google Cloud 控制台的 ID。

  • 确定单个客户端密钥。gcloud CLI 和 Google Cloud 控制台都使用此密钥向 OpenID 提供方进行身份验证。

  • 建立自定义范围,供 gcloud CLI 或 Google Cloud 控制台用来请求用户的安全群组。

  • 建立自定义声明名称,供提供商用来返回用户的安全组。

如何执行这些步骤取决于您的 OpenID 提供方。

在 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:必填。您的 OpenID 提供方的网址,例如 "https://example.com/adfs"。客户端应用(如 gcloud CLI 和 Google Cloud 控制台)会向此网址发送授权请求。Kubernetes API 服务器使用此网址来发现用于验证令牌的公钥。必须使用 HTTPS。
  • kubectlredirecturl::必填。您之前配置的 gcloud CLI 重定向网址。
  • clientid:必填。向 OpenID 提供方发出身份验证请求的客户端应用的 ID。gcloud CLI 和 Google Cloud 控制台都使用此 ID。
  • clientsecret:可选。客户端应用的密钥。gcloud CLI 和 Google Cloud 控制台都使用此密钥。
  • username:可选。用作用户名的 JWT 声明。默认值为 sub,该值应为最终用户的唯一标识符。您可以选择其他声明,例如 emailname,具体取决于 OpenID 提供方。不过,email 以外的声明会以颁发者网址作为前缀,以防止命名与其他插件冲突。
  • usernameprefix:可选。附加到用户名声明前面的前缀,以防止与现有名称冲突。如果您未提供此字段,并且 usernameemail 以外的值,则前缀默认为 issuerurl#。您可以使用值 - 停用所有前缀。
  • group:可选。提供方将用于返回安全群组的 JWT 声明。
  • groupprefix:可选。附加到群组声明前面的前缀,以防止与现有名称冲突。例如,给定一个群组 foobar 和一个前缀 gid-,则格式为 gid-foobar。默认情况下,此值为空,且无前缀。
  • scopes:可选。以英文逗号分隔列表的形式发送给 OpenID 提供方的额外范围。
    • 对于 Microsoft Azure 或 Okta 的身份验证,请传入 offline_access

  • extraparams:可选。以英文逗号分隔列表的形式发送到 OpenID 提供方的额外键值对参数。
  • usehttpproxy:可选。指定是否在集群中部署反向代理,以允许 Google Cloud Console 访问本地 OIDC 提供方来验证用户身份。值必须是字符串:"true""false"。如果无法通过公共互联网访问您的身份提供方,并且您希望使用 Google Cloud Console 进行身份验证,则必须将此字段设置为 "true"。如果留空,则此字段默认为 "false"
  • capath:可选。证书授权机构 (CA)(负责颁发身份提供方 Web 证书)颁发的证书路径。此值可能不是必需的。例如,如果您的身份提供方证书是由知名公共 CA 颁发的,那么您无需在此提供值。但是,如果 usehttpproxy 为“true”,则必须提供此值,即使证书是由知名公共 CA 颁发的,也是如此。

示例:向用户和群组授权

许多提供方在令牌中对用户标识属性(例如电子邮件和用户 ID)进行编码。但是,对于身份验证政策来说,这些属性具有潜在的风险:

  • 用户 ID 可能会导致政策难以阅读和审核。
  • 电子邮件可能会产生可用性风险(如果用户更改其主电子邮件),也可能产生安全风险(如果可以重新分配电子邮件)。

因此,最佳做法是使用群组政策,因为群组 ID 是永久性 ID 且更易于审核。

假设您的提供方创建了包含以下字段的身份令牌:

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

根据此令牌格式,您可以按如下方式填充配置文件的 oidc 规范:

issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

创建用户集群后,您可以使用 Kubernetes 基于角色的访问权限控制 (RBAC) 向经过身份验证的用户授予具有特权的访问权限。例如,您可以创建一个 ClusterRole,向其用户授予对集群 Secret 的只读权限,并创建一个 ClusterRoleBinding 资源,以将角色绑定到经过身份验证的群组:

ClusterRole

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

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

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

本部分面向集群管理员

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

创建身份验证配置文件

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

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

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

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

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

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

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

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

例如,您可能需要同时管理 anthos-config-1cluster.yamlanthos-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 中。

移除旧插件

您必须先卸载旧插件,然后才能使用 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:

  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 标志重新生成客户端身份验证文件。

后续步骤