使用 OIDC 和 AD FS 进行身份验证

本页面介绍如何将 OpenID Connect (OIDC) 与 Active Directory Federation Services (AD FS) 搭配使用,为 GKE On-Prem 用户集群配置身份验证。请注意,AD FS 仅在 2016 及更高版本中支持 OIDC。

如需简要了解身份验证流程,请参阅身份验证。如需了解如何使用 AD FS 以外的 OpenID 提供商,请参阅使用 OpenID Connect 进行身份验证

概览

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

员工可以通过两种方式使用 OIDC 身份验证流程:

  • 员工可以使用 kubectl 启动 OIDC 流程。为了实现此流程的自动化,GKE On-Prem 提供适用于 Kubectl 的 Anthos 插件,这是一个 kubectl 插件
  • 员工可以使用 Google Cloud Console 启动 OIDC 身份验证流程。

在本练习中,您将配置两个选项:kubectl 和 Cloud Console。您可以使用一组 AD FS 管理向导来配置 AD FS 服务器和 AD 员工数据库。

准备工作

本主题假定您熟悉 OAuth 2.0OpenID Connect。本主题假定您熟悉 OpenID 范围声明

本主题适用于具有以下基础架构的企业:

  • 企业为其员工数据库使用 Active Directory (AD)。
  • 企业运行 Active Directory Federation Services (AD FS) 服务器。
  • AD FS 服务器充当 OpenID 提供商。

角色

本主题涉及三个角色:

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

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

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

为适用于 Kubectl 的 Anthos 插件创建重定向网址

本部分面向组织管理员

作为与 AD FS 服务器建立关系的一部分,您必须指定一个重定向网址,以便 AD FS 服务器使用此网址将 ID 令牌返回到适用于 Kubectl 的 Anthos 插件。适用于 Kubectl 的 Anthos 插件在每个开发者的本地机器上运行,并侦听您选择的端口。选择适合此用途且大于 1024 的端口号。然后,重定向网址为:

http://localhost:[PORT]/callback

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

配置 AD FS 服务器时,请指定 http://localhost:[PORT]/callback 作为您的重定向网址之一。

为 Cloud Console 配置重定向网址

本部分面向组织管理员

除了拥有适用于 Kubectl 的 Anthos 插件的重定向网址之外,您还需要一个 Cloud Console 重定向网址。Cloud Console 的重定向网址为:

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

配置 AD FS 服务器时,请指定 https://console.cloud.google.com/kubernetes/oidc 作为您的重定向网址之一。

配置 AD FS

以下部分介绍如何为 GKE On-Prem 配置 AD FS。

设置重定向网址

本部分面向组织管理员

  1. 打开 AD FS 管理窗格。

  2. 选择 Application Groups > Actions > Add an Application Group

  3. 选择 Server Application。输入您选择的名称和说明。点击 Next

  4. 输入您的两个重定向网址。您将获得一个客户端 ID。这是 AD FS 服务器标识适用于 Kubectl 的 Anthos 插件和 Cloud Console 的方式。保存客户端 ID 以供日后使用。

  5. 选择 Generate a shared secret。适用于 Kubectl 的 Anthos 插件和 Cloud Console 使用此 Secret 向 AD FS 服务器进行身份验证。保存此 Secret 以供日后使用。

配置安全群组(可选)

本部分面向组织管理员

  1. 在 AD FS 管理中,选择 Relying party trusts > Add a new relying party trust

  2. 选择 Claims aware,然后点击 Start

  3. 选择 Enter data about relying party manually

  4. 输入显示名。

  5. 跳过接下来的两个步骤。

  6. 输入信赖方信任标识符。建议:token-groups-claim

  7. 对于 Access control policy,请选择 Permit everyone。这意味着所有员工都会与适用于 Kubectl 的 Anthos 插件和 Cloud Console 共享其安全群组信息。

  8. 点击完成

将 LDAP 特性映射到声明名称

本部分面向组织管理员

  1. 在 AD FS 管理中,选择 Relying party trusts > Edit claim issuance policy

  2. 选择 Send LDAP Attributes as Claims,然后点击 Next

  3. 对于 Claim rule name,请输入 groups

  4. 对于 Attribute store,请选择 Active Directory

  5. 在表格中,对于 LDAP Attribute,请选择:

    • AD FS 5.0 及更高版本:Token-Groups Qualified by Domain name
    • AD FS 5.0 之前的版本:Token Groups - Qualified Names
  6. 对于 Outgoing Claim Type,请选择:

    • AD FS 5.0 及更高版本:Group
    • AD FS 5.0 之前的版本:groups
  7. 点击 Finish,然后点击 Apply

向 AD FS 注册适用于 Kubectl 的 Anthos 插件和 Cloud Console

本部分面向组织管理员

在管理员模式下打开 PowerShell 窗口,然后输入以下命令:

Grant-AD FSApplicationPermission `
    -ClientRoleIdentifier "[CLIENT_ID]" `
    -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] `
    -ScopeName "allatclaims", "openid"

其中:

  • [CLIENT_ID] 是您之前获得的客户端 ID。

  • [SERVER_ROLE_IDENTIFIER] 是您之前输入的声明标识符。回想一下,建议的标识符为 token-groups-claim

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

  • extraparams:可选。以英文逗号分隔列表的形式发送到 OpenID 提供商的额外键值对参数。
    • 如需查看身份验证参数的列表,请参阅身份验证 URI 参数
    • 如果您要向群组授权,请传入 resource=token-groups-claim
    • 如果您的授权服务器提示是否同意,请传入 prompt=consent。这是使用 Microsoft Azure 进行身份验证所必需的。
  • usehttpproxy:可选。指定是否在集群中部署反向代理,以允许 Google Cloud Console 访问本地 OIDC 提供方来验证用户身份。值必须是字符串:"true""false"。如果无法通过公共互联网访问您的身份提供商,并且您希望使用 Google Cloud Console 进行身份验证,则必须将此字段设置为 "true"
  • 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 create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

其中,[USER_CLUSTER_KUBECONFIG] 是用户集群的 kubeconfig 文件的路径。创建用户集群后,gkectl create cluster 会为集群生成一个 kubeconfig 文件。

上述命令会在当前目录中创建一个名为 kubectl-anthos-config.yaml 的文件。

将其他集群添加到您的身份验证配置文件中

本部分面向集群管理员

您可以将多个集群的身份验证配置存储在一个文件中。然后,您可以将该文件分发给应该有权访问所有集群的开发者。

从现有身份验证配置文件开始。然后,使用以下命令将该文件与其他集群的配置合并:

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] 相同。

分发身份验证配置文件

本部分面向集群管理员

您分发给开发者的身份验证配置文件必须命名为 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

放置身份验证配置文件

本部分面向开发者

身份验证配置文件包含您可以进行身份验证的所有集群的详细信息。请勿修改此文件的内容。

如果您的集群管理员为您提供了身份验证配置文件,请将该文件放在正确的目录中。如果您的集群管理员已将配置放到您的机器上,您可以跳过此部分。

将您的身份验证配置文件复制到其默认位置:

Linux

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

其中,[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。

macOS

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

其中,[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。

Windows

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

其中,[AUTH_CONFIG_FILE] 是您的身份验证配置文件的名称。

获取适用于 Kubectl 的 Anthos 插件

本部分面向集群管理员

适用于 Kubectl 的 Anthos 插件位于管理员工作站中的以下位置:

Linux

/usr/bin/kubectl_anthos/v1.0beta/linux_amd64/kubectl-anthos

macOS

/usr/bin/kubectl_anthos/v1.0beta/darwin_amd64/kubectl-anthos

Windows

/usr/bin/kubectl_anthos/v1.0beta/windows_amd64/kubectl-anthos

您可以将插件分发给开发者,也可以让他们直接下载插件。

下载适用于 Kubectl 的 Anthos 插件

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

每个开发者都需要在自己的机器上安装适用于 Kubectl 的 Anthos 插件。开发者可以自行下载插件,也可以由集群管理员下载插件,然后将其分发给开发者。

开发者注意事项:请询问您的集群管理员,您应该使用哪个版本的插件。

下载适用于 Kubectl 的 Anthos 插件:

Linux

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/linux_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

macOS

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/darwin_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

Windows

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/windows_amd64/kubectl-anthos ./
rename kubectl-anthos kubectl-anthos.exe.

安装适用于 Kubectl 的 Anthos 插件

本部分面向开发者

您的集群管理员可能会向您提供适用于 Kubectl 的 Anthos 插件。您的集群管理员也可能会告诉您自行下载插件

要安装适用于 Kubectl 的 Anthos 插件,请将可执行文件移到路径上的任意位置。可执行文件必须命名为 kubectl-anthos。如需了解详情,请参阅安装 kubectl 插件

验证是否安装了适用于 Kubectl 的 Anthos 插件:

kubectl plugin list
kubectl anthos version

列出可用的集群

本部分面向开发者

如果您的身份验证配置文件位于默认路径中,请输入以下命令来列出您可以进行身份验证的集群:

kubectl anthos listclusters

如果您的身份验证配置文件没有位于默认路径中,请输入以下命令来列出集群:

kubectl anthos listclusters --loginconfig [AUTH_CONFIG_FILE]

其中,[AUTH_CONFIG_FILE] 是您的身份验证配置文件的路径。

使用适用于 Kubectl 的 Anthos 插件进行身份验证

本部分面向开发者

登录到用户集群:

kubectl anthos login --cluster [CLUSTER_NAME] --user [USER_NAME] \
    --loginconfig [AUTH_CONFIG_FILE] --kubeconfig [USER_CLUSTER_KUBECONFIG]

其中:

  • [CLUSTER_NAME] 是您的用户集群的名称。您必须从 kubectl anthos listclusters 命令提供的列表中选择此名称。

  • [USER_NAME] 是一个可选参数,用于指定存储在 kubeconfig 文件中的凭据的用户名。默认值为 [CLUSTER_NAME]-anthos-default-user

  • [AUTH_CONFIG_FILE] 是您的身份验证配置文件的路径。如果您的身份验证配置文件位于默认位置,则可以省略此参数。

  • [USER_CLUSTER_KUBECONFIG] 是用户集群的 kubeconfig 文件的路径。如果 kubeconfig 文件不存在,该命令会从身份验证配置文件生成新的 kubeconfig 文件,并将集群详细信息和令牌添加到 kubeconfig 文件。

kubectl anthos login 会启动浏览器,您可以在其中输入凭据。

现在提供的 kubeconfig 文件包含一个 ID 令牌,kubectl 可使用该令牌向用户集群上的 Kubernetes API 服务器进行身份验证。

kubectl anthos login 命令有一个可选的 --dry-run 标志。如果您添加了 --dry-run 标志,则该命令会输出 kubectl 命令,后者会将令牌添加到 kubeconfig 文件中,但不会真正将该令牌保存到 kubeconfig 文件中。

通过输入 kubectl 命令验证身份验证是否成功。例如:

kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

将 OIDC 与 Google Cloud Console 搭配使用

本部分面向开发者

  1. 验证您的集群是否已针对 OIDC 进行了配置

  2. 验证您的集群是否已向 Google Cloud 注册(无论是在创建集群时自动注册还是手动注册)。

  3. 访问 Cloud Console 中的 Kubernetes 集群页面。

    访问 Kubernetes 集群页面

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

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

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

总结

您的企业运行充当 OpenID 提供商的 AD FS 服务器。您的 OpenID 提供商知晓您的两个客户端应用:适用于 Kubectl 的 Anthos 插件和 Cloud Console。您的 OpenID 提供商知晓您的客户端应用可以请求 openidallatclaims 范围。

在 AD FS 5.0 之前的版本中,AD 数据库中的 Token-Groups Qualified Names LDAP 特性被映射到 OpenID 提供商中的 groups 声明。在 5.0 和更高版本中,该特性为 Token-Groups Qualified by Domain name。提供商会返回包含员工 ID、颁发者 ID、openid 声明和 groups 声明的令牌。groups(在 5.0 中为 Group)声明会列出员工所属的安全群组。

自定义配置

默认情况下,适用于 Kubectl 的 Anthos 插件要求身份验证配置文件位于特定位置。如果您不想将身份验证配置文件置于默认位置,可以使用 --login-config 标志手动将身份验证配置文件的路径传递给插件命令。如需查看示例,请参阅使用适用于 Kubectl 的 Anthos 插件进行身份验证

排查 GKE On-Prem 中的 OIDC 问题

配置无效

如果 Cloud Console 无法从集群中读取 OIDC 配置,则登录按钮将被停用。

提供商配置无效

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

权限无效

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

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

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

后续步骤