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

了解如何配置 Anthos clusters on VMware (GKE on-prem),以使用 OpenID Connect (OIDC) 对用户集群进行身份验证。本页面总体上介绍了该过程,以帮助您了解如何配置 OpenID 提供方。

如需大致了解 Anthos clusters on VMware 身份验证流程,请参阅身份验证。如需了解如何针对其他 OpenID 提供方配置 OIDC,请参阅以下资源:

Anthos clusters on VMware 支持使用 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 安装在每个开发者的本地机器上。您可以指定大于 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 提供商注册 gcloud CLI 和 Google Cloud 控制台,您的开发者才能将这两个客户端用于您的 OpenID 提供商。注册包括以下步骤:

  • 了解提供商的颁发者 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 提供方。

在 Anthos clusters on VMware 集群中配置 oidc

本部分面向集群管理员

如需配置 OIDC 身份验证,您需要使用集群的身份验证详细信息来配置用户集群的 ClientConfig CRD。为此,请在 kube-public 命名空间中修改 clientconfig 类型的 KRM 默认对象。

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-public edit clientconfig default

ClientConfig CRD 中的详细信息用于为 Google Cloud 控制台和适用于 Anthos 的身份验证插件配置 OIDC。配置包括以下 OIDC 信息。

authentication:
  - name: NAME_STRING
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: "http://console.cloud.google.com/kubernetes/oidc"
      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
    proxy: PROXY_URL

下表介绍了 ClientConfig CRD oidc 对象的字段。

字段 必填 说明 格式
name 要创建的 OIDC 配置的名称。 字符串
certificateAuthorityData

OIDC 提供方的 base64 编码的 PEM 编码证书。如需创建字符串,请将证书(包括标头)进行 base64 编码。将生成的字符串作为单独的一行添加到 certificateAuthorityData 中。

示例:
certificateAuthorityData: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tC...k1JSUN2RENDQWFT==

字符串
clientID 向 OpenID 提供方发出身份验证请求的客户端应用的 ID。 字符串
clientSecret OIDC 客户端应用和 OIDC 提供方之间的共享密钥令牌。 字符串
extraParams

要发送到 OpenID 提供方的其他键值对参数。如果您要向群组授权,请传入 resource=token-groups-claim

如果您的授权服务器提示是否同意使用 Microsoft Azure 和 Okta 进行身份验证,请将 extraParams 设置为 prompt=consent。对于 Cloud Identity,请将 extraParams 设置为 prompt=consent,access_type=offline

英文逗号分隔列表
groupsClaim 提供方用于返回安全组的 JWT 声明。 字符串
groupPrefix 附加到群组声明前面的前缀,以防止与现有名称冲突。例如,如果您有两个名为 foobar 的群组,请添加前缀 gid-。生成的群组为 gid-foobar 字符串
issuerURI 用于向 OpenID 发送授权请求的网址,例如 https://example.com/adfs。Kubernetes API 服务器使用此网址来发现用于验证令牌的公钥。URI 必须使用 HTTPS。 网址字符串
kubectlRedirectURI kubectl 用于授权的重定向网址。 网址字符串
scopes 要发送到 OpenID 提供方的其他范围。Microsoft Azure 和 Okta 需要 offline_access 范围。 英文逗号分隔列表
userClaim 用作用户名的 JWT 声明。您可以选择其他声明,例如电子邮件或名称,具体取决于 OpenID 提供方。不过,电子邮件以外的声明会以颁发者网址作为前缀,以防止命名冲突。 字符串
userPrefix 附加到用户名声明前面的前缀,以防止与现有名称冲突。 字符串
proxy 用于 auth 方法的代理服务器(如果适用)。例如 http://user:password@10.10.10.10:8888. 字符串

示例:向用户和群组授权

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

  • 用户 ID 可能会导致政策难以阅读和审核。

  • 电子邮件可能会产生可用性风险(如果用户更改其主电子邮件),也可能产生安全风险(如果可以重新分配电子邮件)。

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

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

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

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

issuerURL: 'https://server.example.com'
userClaim: 'sub'
usernamePrefix: 'uid-'
groupsClaim: '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_NAMEREMOTE_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. 在列表中找到 Anthos Clusters on VMware 集群,然后点击登录

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

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

排查 OIDC 配置问题

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

配置无效
如果 Google Cloud 控制台无法从集群中读取 OIDC 配置,则登录按钮会被停用。
提供商配置无效
如果您的身份提供方配置无效,点击登录后,身份提供方将显示错误屏幕。按照特定于提供方的说明正确配置提供方或您的集群。
权限无效
如果您完成了身份验证流程,但仍看不到集群的详细信息,请确保您已向与 OIDC 搭配使用的帐号授予了正确的 RBAC 权限。请注意,此帐号可能与您用于访问 Google Cloud 控制台的帐号不同。
Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct
如果授权服务器提示是否同意,但您未提供所需的身份验证参数,则可能会遇到此错误。向 Anthos Clusters on VMware 配置文件的 oidc: extraparams 字段提供 prompt=consent 参数,并使用 --extra-params prompt=consent 标志重新生成客户端身份验证文件。

后续步骤