了解如何配置 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 和 Cloud Console 创建重定向网址,以便 OpenID 提供方可使用此类网址返回 ID 令牌。
gcloud CLI 重定向网址
Google Cloud CLI 安装在每个开发者的本地机器上。您可以指定大于 1024 的端口号,以用于重定向网址:
http://localhost:PORT/callback
将 PORT
替换为您的端口号。
配置 OpenID 提供程序时,请将 http://localhost:PORT/callback
指定为其中一个重定向网址。具体操作方式取决于您的提供方。
Cloud Console 重定向网址
Cloud Console 的重定向网址为:
https://console.cloud.google.com/kubernetes/oidc
配置 OIDC 提供方时,请将 https://console.cloud.google.com/kubernetes/oidc
指定为其中一个重定向网址。具体操作方式取决于您的提供方。
向 OpenID 提供商注册您的客户端应用
本部分面向组织管理员。
您需要先向 OpenID 提供方注册这两个客户端,您的开发者才可以通过 OpenID 提供方使用 gcloud CLI 或 Cloud Console。注册包括以下步骤:
了解提供方的颁发者 URI。这是 gcloud CLI 或 Cloud Console 将身份验证请求发送到的位置。
为提供方提供 gcloud CLI 的重定向网址。
为提供方提供 Cloud Console 的重定向网址。网址为 https://console.cloud.google.com/kubernetes/oidc。
确定单个客户端 ID。这是提供方用于标识 gcloud CLI 和 Cloud Console 的 ID。
确定单个客户端密钥。gcloud CLI 和 Cloud Console 均使用此密钥向 OpenID 提供方进行身份验证。
建立自定义范围,以便 gcloud CLI 或 Cloud Console 能够用于请求用户的安全组。
建立自定义声明名称,供提供方用来返回用户的安全组。
如何执行这些步骤取决于您的 OpenID 提供商。
在集群上配置 oidc
本部分面向集群管理员。
如需配置 OIDC 身份验证,您需要使用集群的身份验证详细信息配置集群的 ClientConfig CRD。为此,请在 kube-public
命名空间中修改 clientconfig
类型的 KRM 默认对象。 您可以将不同的配置应用到管理员集群和用户集群,也可以对它们使用相同的配置,具体取决于贵组织的需求。
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-public edit clientconfig default
ClientConfig CRD 中的详细信息用于为 Cloud Console 和适用于 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 enableAccessToken: ENABLE_ACCESS_TOKEN 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 提供方的 示例: |
字符串 |
clientID | 是 | 向 OpenID 提供商发出身份验证请求的客户端应用的 ID。 | 字符串 |
clientSecret | 否 | OIDC 客户端应用和 OIDC 提供方之间的共享密钥令牌。 | 字符串 |
deployCloudConsoleProxy | 否 | 指定是否部署一个代理,该代理允许 Cloud Console 连接到无法通过互联网公开访问的本地身份提供方。默认情况下,该值设置为 false 。 |
布尔值 |
enableAccessToken | 否 | 启用后,当用户从命令行登录时,Identity Service 可以使用身份提供方的 userinfo 端点获取群组信息。如果您的提供方(例如 Okta)提供来自此端点的群组声明,您便可以使用安全群组进行授权。如果未设置,则视为 false 。 |
布尔值 |
extraParams | 否 |
要发送到 OpenID 提供方的其他键值对参数。如果您要向群组授权,请传入 如果您的授权服务器提示是否同意使用 Microsoft Azure 和 Okta 进行身份验证,请将 |
英文逗号分隔列表 |
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-' groupClaim: '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.yaml
和 anthos-config-3clusters.yaml
身份验证配置文件,以满足贵组织中多个用户群组的访问需求。
要向现有身份验证配置文件添加额外的用户集群,请执行以下操作:
确保每个集群的名称唯一。如果您的集群具有相同的名称,则无法将它们组合到同一身份验证配置文件中。请注意,创建集群后,无法重命名该集群。
运行以下
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,但跳过
gcloud init
命令。运行以下命令以安装
anthos-auth
组件:gcloud components update gcloud components install anthos-auth
通过运行以下任一命令来验证 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 或 Cloud Console 向集群进行身份验证。
通过 gcloud CLI 进行身份验证
运行 gcloud
命令以向您的集群进行身份验证:
运行
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-userAUTH_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
在打开的基于浏览器的同意屏幕中输入您的凭据。
通过运行其中一个
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 Console 进行身份验证
从 Cloud Console 中的 Kubernetes 集群页面启动身份验证流程:
-
打开 Cloud Console:
-
在列表中找到 Anthos Clusters on VMware 集群,然后点击登录。
-
选择使用为集群配置的身份提供方服务执行身份验证,然后点击登录。
系统会将您重定向到您的身份提供方,您可能需要登录或同意 Cloud Console 访问您的帐号。然后,系统会将您重定向回 Cloud Console 中的 Kubernetes 集群页面。
排查 OIDC 配置问题
请查看以下行为和错误,以帮助您解决 OIDC 问题:
- 配置无效
- 如果 Cloud Console 无法从集群中读取 OIDC 配置,则登录按钮会被停用。
- 提供方配置无效
- 如果您的身份提供商配置无效,点击登录后,身份提供商将显示错误屏幕。按照特定于提供商的说明正确配置提供商或您的集群。
- 权限无效
- 如果您完成了身份验证流程,但仍看不到集群的详细信息,请确保您已向与 OIDC 搭配使用的帐号授予了正确的 RBAC 权限。请注意,此帐号可能与您用于访问 Cloud Console 的帐号不同。
Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct
- 如果授权服务器提示是否同意,但您未提供所需的身份验证参数,则可能会遇到此错误。向 Anthos Clusters on VMware 配置文件的
oidc: extraparams
字段提供prompt=consent
参数,并使用--extra-params prompt=consent
标志重新生成客户端身份验证文件。
后续步骤
- 详细了解范围和声明。