Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 13 章 管理 OpenID Connect 和 SAML 客户端

客户端是可以请求用户身份验证的实体。客户端以两种形式提供。第一个类型的客户端是希望参与单点登录的应用程序。这些客户端只希望红帽构建的 Keycloak 为其提供安全性。其他类型的客户端是请求访问令牌之一，以便它能够代表经过身份验证的用户调用其他服务。本节讨论了有关配置客户端以及进行各种方法的各方面。

13.1. 管理 OpenID Connect 客户端
复制链接

OpenID Connect 是推荐的协议来保护应用程序。它设计为网络友好型设计，最适合 HTML5/JavaScript 应用程序。

13.1.1. 创建 OpenID Connect 客户端
复制链接

要保护使用 OpenID 连接协议的应用程序，请创建一个客户端。

流程

  1. 点菜单中的 Clients。

  2. 单击 Create client。

    创建客户端

    Create Client

  3. 将 Client type 设置为 OpenID Connect。

  4. 输入 客户端 ID。

    这个 ID 是一个字母数字字符串，用于 OIDC 请求以及红帽构建的 Keycloak 数据库来识别客户端。

  5. 为客户端提供 Name。

    如果您计划本地化此名称，请设置替换字符串值。例如，字符串值，如 ${myapp}。如需更多信息 ，请参阅服务器开发人员指南。

  6. 点击 Save。

此操作将创建客户端，并带您进入 Settings 选项卡，您可以在其中 执行基本配置。

13.1.2. 基本配置
复制链接

Settings 选项卡包含用于配置此客户端的许多选项。

设置标签页

Settings tab

13.1.2.1. 常规设置
复制链接

客户端 ID
OIDC 请求中使用的字母数字 ID 字符串，以及红帽构建的 Keycloak 数据库来识别客户端。
Name
红帽构建的 Keycloak UI 屏幕中的客户端名称。要本地化名称，请设置替换字符串值。例如，字符串值，如 ${myapp}。如需更多信息 ，请参阅服务器开发人员指南。
描述
客户端的描述。此设置也可以本地化。
始终在控制台中显示
即使此用户没有活动的会话，也始终在帐户控制台中列出此客户端。

13.1.2.2. 访问设置
复制链接

根 URL
如果红帽构建的 Keycloak 使用任何配置的相对 URL，则该值会添加到其中。
主页 URL
提供默认 URL，当 auth 服务器需要重定向或链接到客户端时。
有效的 Redirect URI

必填字段。输入 URL 模式，然后单击 + 以删除现有 URL，然后单击 Save。完全（区分大小写）字符串匹配用于比较有效的重定向 URI。

您可以在 URL 模式末尾使用通配符。例如 http://host.com/path/*。为避免安全问题，如果传递的重定向 URI 包含 userinfo 部分，或者 其路径 管理对父目录(/../)的访问，则不会执行通配符比较，但标准和安全完全匹配。

完整通配符 * 有效重定向 URI 也可以配置为允许任何 http 或 https 重定向 URI。请不要在生产环境中使用它。

专用重定向 URI 模式通常更为安全。如需更多信息 ，请参阅非特定 Redirect URI。

Web Origins

输入 URL 模式并点击 + 以删除现有 URL。点 Save。

此选项处理 Cross-Origin Resource Sharing (CORS)。如果浏览器 JavaScript 尝试 AJAX HTTP 请求到域与 JavaScript 代码来自的服务器不同，则请求必须使用 CORS。服务器必须处理 CORS 请求，否则浏览器将不会显示或允许处理请求。此协议可防止 XSS、CSRF 和其他基于 JavaScript 的攻击。

此处列出的域 URL 嵌入到发送到客户端应用程序的访问令牌中。客户端应用使用此信息来决定是否允许在其上调用 CORS 请求。只有 Red Hat build of Keycloak 客户端适配器支持此功能。如需更多信息，请参阅 保护应用程序和服务指南。

管理 URL
客户端的回调端点。服务器使用此 URL 进行回调，如推送撤销策略、执行反向通道注销和其他管理操作。对于红帽构建的 Keycloak servlet 适配器，此 URL 可以是 servlet 应用程序的 root URL。如需更多信息，请参阅 保护应用程序和服务指南。

13.1.2.3. 功能配置
复制链接

客户端身份验证

OIDC 客户端的类型。

  • ON

    对于执行浏览器登录的服务器端客户端，并在进行访问令牌请求时要求客户端 secret。此设置应该用于服务器端应用程序。

  • OFF

    用于执行浏览器登录的客户端。由于无法确保 secret 可以与客户端安全保存，因此务必要通过配置正确的重定向 URI 来限制访问。

授权
启用或禁用此客户端的细粒度授权支持。
标准流
如果启用，此客户端可以使用 OIDC 授权代码流。
直接访问授予
如果启用，此客户端可以使用 OIDC Direct Access Grants。
隐式流
如果启用，此客户端可以使用 OIDC Implicit 流。
服务帐户角色
如果启用，此客户端可以向红帽构建 Keycloak 进行身份验证，并检索专用于此客户端的访问令牌。在 OAuth2 规范中，这 支持此客户端的客户端 凭证授予。
Auth 2.0 设备授权
如果启用，此客户端可以使用 OIDC 设备授权。
OIDC CIBA Grant
如果启用，此客户端可以使用 OIDC Client Initiated Backchannel Authentication Grant。

13.1.2.4. 登录设置
复制链接

登录主题
用于 login、OTP、授予注册和忘记密码页面的主题。
需要同意

如果启用，用户必须同意客户端访问。

用于执行浏览器登录的客户端。由于无法确保 secret 可以与客户端安全保存，因此务必要通过配置正确的重定向 URI 来限制访问。

在屏幕上显示客户端

如果 Consent Required 为 Off，则应用此开关。

  • 关

    同意屏幕将仅包含与配置的客户端范围对应的同意。

  • On

    此客户端本身的同意屏幕上也会有一个项。

客户端同意屏幕文本
如果启用了 屏幕上的 Consent required 和 Display client。包含有关此客户端权限的同意屏幕上的文本。

13.1.2.5. 退出设置
复制链接

前端频道退出
如果启用了 Front Channel Logout，应用程序应该可以根据 OpenID Connect Front-Channel Logout 规格通过前端频道注销用户。如果启用，您还应提供 Front-Channel Logout URL。
front-channel logout URL
红帽构建的 Keycloak 用于通过前端向客户端发送注销请求的 URL。
Backchannel logout URL
当注销请求发送到此域（通过 end_session_endpoint）时，会导致客户端自行注销。如果省略，则不会向客户端发送注销请求。
需要 Backchannel logout 会话
指定在使用 Backchannel Logout URL 时，Logout Token 中是否包含会话 ID 声明。
Backchannel logout revoke offline sessions
指定在使用 Backchannel Logout URL 时，Logout Token 中是否包含 revoke_offline_access 事件。红帽构建的 Keycloak 将在使用这个事件接收 Logout Token 时撤销离线会话。

13.1.3. 高级配置
复制链接

在 Settings 选项卡中完成字段后，您可以使用其他标签页执行高级配置。

13.1.3.1. 高级标签页
复制链接

当您点 Advanced 选项卡时，会显示其他字段。有关特定字段的详情，请点击该字段的问号图标。但是，本节将详细介绍某些字段。

13.1.3.2. 精细的 OpenID Connect 配置
复制链接

徽标 URL

引用客户端应用程序的徽标的 URL。

策略 URL

Relying Party Client 为 End-User 提供的 URL，用于读取配置集数据的使用方式。

服务 URL 术语

Relying Party Client 提供给最终用户以阅读有关 Relying Party 服务条款的 URL。

签名和加密的 ID 令牌支持

红帽构建的 Keycloak 可以根据 Json Web 加密(JWE)规范加密 ID 令牌。管理员决定是否为每个客户端加密 ID 令牌。

用于加密 ID 令牌的密钥是内容加密密钥(CEK)。红帽构建的 Keycloak 和客户端必须协商使用哪个 CEK 以及它是如何提供的。确定 CEK 的方法是密钥管理模式。红帽构建的 Keycloak 支持的密钥管理模式是密钥加密。

在密钥加密中：

  1. 客户端生成非对称加密密钥对。
  2. 公钥用于加密 CEK。
  3. Red Hat build of Keycloak 为每个 ID 令牌生成 CEK
  4. 红帽构建的 Keycloak 使用这个生成的 CEK 加密 ID 令牌
  5. 红帽构建的 Keycloak 使用客户端的公钥加密 CEK。
  6. 客户端使用其私钥解密这个加密的 CEK
  7. 客户端使用解密的 CEK 解密 ID 令牌。

客户端以外的方都可以解密 ID 令牌。

客户端必须将其公钥传递给红帽构建的 Keycloak。Red Hat build of Keycloak 支持从客户端提供的 URL 下载公钥。客户端必须根据 Json Web Keys (JWK) 规范提供公钥。

该流程是：

  1. 打开客户端的 Keys 选项卡。
  2. 将 JWKS URL 切换到 ON。
  3. 在 JWKS URL 文本框中输入客户端的公钥 URL。

密钥加密算法在 Json Web Algorithm (JWA) 规范中定义。Red Hat build of Keycloak 支持：

  • RSAES-PKCS1-v1_5(RSA1_5)
  • RSAES OAEP 使用默认参数(RSA-OAEP)
  • RSAES OAEP 256 使用 SHA-256 和 MFG1 (RSA-OAEP-256)

选择算法的步骤为：

  1. 打开客户端 的高级 选项卡。
  2. 打开 Fine Grain OpenID Connect Configuration。
  3. 从 ID Token Encryption Content Algorithm 下拉菜单中选择算法。

13.1.3.3. OpenID Connect 兼容性模式
复制链接

本节存在以便向后兼容。点每个字段的详情的问号图标。

启用 OAuth 2.0 通用 TLS 证书绑定访问令牌

双向 TLS 将访问令牌和刷新令牌与客户端证书绑定，该证书在 TLS 握手期间交换。这个绑定可防止攻击者使用 stolen 令牌。

这种类型的令牌是拥有者(key-of-key)令牌。与 bearer 令牌不同，令牌令牌的接收者可以验证令牌的发件人是否合法。

如果此设置为 on，工作流为：

  1. 令牌请求在授权代码流或混合流中发送到令牌端点。
  2. 红帽构建的 Keycloak 请求客户端证书。
  3. 红帽构建的 Keycloak 接收客户端证书。
  4. 红帽构建的 Keycloak 成功验证客户端证书。

如果验证失败，红帽构建的 Keycloak 会拒绝令牌。

在以下情况下，红帽构建的 Keycloak 将验证发送访问令牌或刷新令牌的客户端：

  • 令牌刷新请求发送到具有拥有者密钥刷新令牌端点。
  • UserInfo 请求发送到 UserInfo 端点，其具有持有者的访问令牌。
  • 注销请求发送到带有拥有者密钥刷新令牌的 Keycloak 专有 Logout 端点的非OIDC 兼容红帽构建。

如需了解更多详细信息，请参阅 OAuth 2.0 通用 TLS 客户端身份验证和证书绑定 访问令牌 中的 通用 TLS 客户端证书 Bound 访问令牌。

注意

Red Hat build of Keycloak 客户端适配器不支持 holder-of-key 令牌验证。Red Hat build of Keycloak 适配器将访问和刷新令牌视为 bearer 令牌。

应用层(DPoP)上的 OAuth 2.0 演示概念验证-Possession

DPoP 将访问令牌和客户端密钥对的公钥部分绑定在一起。这个绑定可防止攻击者使用 stolen 令牌。

这种类型的令牌是拥有者(key-of-key)令牌。与 bearer 令牌不同，令牌令牌的接收者可以验证令牌的发件人是否合法。

如果客户端切换 OAuth 2.0 DPoP Bound Access Tokens 为 on，则工作流为：

  1. 令牌请求在授权代码流或混合流中发送到令牌端点。
  2. 红帽构建的 Keycloak 请求了 DPoP 证明。
  3. 红帽构建的 Keycloak 接收 DPoP 证明。
  4. 红帽构建的 Keycloak 成功验证 DPoP 证明。

如果验证失败，红帽构建的 Keycloak 会拒绝令牌。

如果启用 OAuth 2.0 DPoP Bound Access Tokens 为 off，客户端仍然可以在令牌请求中发送 DPoP 证据。在这种情况下，红帽构建的 Keycloak 将验证 DPoP 证明，并将添加 thumbprint 到令牌。但是，如果交换机关闭，红帽为此客户端构建 Keycloak 服务器不会强制使用 DPoP 绑定。如果要确保特定的客户端始终使用 DPoP 绑定，则建议在 上进行这个切换。

在以下情况下，红帽构建的 Keycloak 将验证发送访问令牌或刷新令牌的客户端：

  • 令牌刷新请求发送到具有拥有者密钥刷新令牌端点。此验证仅对公共客户端完成，如 DPoP 规范中所述。对于机密客户端，不会通过适当的客户端凭据进行验证，以确保请求来自合法客户端。对于公共客户端，访问令牌和刷新令牌均受 DPoP 绑定。对于机密客户端，只有访问令牌绑定为 DPoP。
  • UserInfo 请求发送到 UserInfo 端点，其具有持有者的访问令牌。
  • 注销请求发送到带有持有者密钥刷新令牌的 Keycloak 专有退出端点 Logout 端点的 non-OIDC 红帽构建。此验证只针对公共客户端完成，如上所述。

如需了解更多详细信息，请参阅 OAuth 2.0 演示方式 Possession (DPoP)。

注意

红帽构建的 Keycloak 客户端适配器不支持 DPoP 持有者令牌验证。Red Hat build of Keycloak 适配器将访问和刷新令牌视为 bearer 令牌。

注意

DPoP 是 技术预览，且不受支持。此功能默认为禁用。

使用-- features=preview or-- features=dpop启动服务器

OIDC 的高级设置

OpenID Connect 的高级设置允许您在客户端级别上为 会话和令牌超时 配置覆盖。

Advanced Settings

Expand
Configuration描述

访问令牌生命周期

该值会覆盖具有相同名称的 realm 选项。

客户端会话空闲

该值会覆盖具有相同名称的 realm 选项。该值应短于全局 SSO 会话空闲。

客户端会话最大

该值会覆盖具有相同名称的 realm 选项。该值应短于全局 SSO 会话 Max。

客户端离线会话空闲

此设置允许您为客户端配置较短的离线会话闲置超时。在红帽构建的 Keycloak 撤销其离线令牌前，超时是会话保持闲置的时间。如果没有设置，则使用 realm Offline Session Idle。

客户端离线会话 Max

此设置允许您为客户端配置较短的离线会话 max 生命周期。生命周期span 是红帽构建的 Keycloak 撤销对应的离线令牌前的最长时间。这个选项需要在域中全局启用 离线会话 Max Limited，默认为 Offline Session Max。

代码交换代码挑战方法的证明密钥

如果攻击者窃取合法客户端的授权代码，则代码交换(PKCE)的证明密钥会阻止攻击者获得适用于代码的令牌。

管理员可以选择以下选项之一：

(blank)
红帽构建的 Keycloak 不会应用 PKCE，除非客户端将适当的 PKCE 参数发送到红帽构建的 Keycloaks 授权端点。
S256
Red Hat build of Keycloak 适用于客户端 PKCE，其代码质询方法是 S256。
plain
Red Hat build of Keycloak 适用于客户端 PKCE，其代码质询方法是 plain。

如需了解更多详细信息，请参阅 OAuth 公共客户端的代码交换的 RFC 7636 概念验证。

ACR 到级别身份验证(LoA)映射

在客户端的高级设置中，您可以定义哪个 身份验证方法类参考(ACR) 值映射到哪个 级别身份验证(LoA)。此映射也可以在域中指定，如 ACR 到 LoA Mapping 中所述。最佳实践是在域级别上配置此映射，它允许在多个客户端间共享相同的设置。

Default ACR 值 可用于在没有 acr _values 参数的情况下将登录请求发送到红帽构建的 Keycloak 时指定默认值，且没有附加了 acr_values 参数的 claims 参数。请参阅 官方 OIDC 动态客户端注册规格。

警告

请注意，默认的 ACR 值用作默认级别，但无法可靠使用它来强制使用特定级别的登录。例如，假设您将 Default ACR 值 配置为 2 级。默认情况下，用户需要使用级别 2 进行身份验证。但是，当用户将参数明确附加到登录请求时，如 acr_values=1，则会使用级别 1。因此，如果客户端真正需要 2 级，则建议客户端检查 ID 令牌中是否存在 acr 声明，并仔细检查它包含请求的级别 2。

ACR to LoA mapping

详情请查看 步骤身份验证和 官方 OIDC 规格。

13.1.4. 机密客户端凭证
复制链接

如果客户端的客户端身份验证设置为 ON，必须在 Credentials 选项卡中配置客户端的凭证。???

credentials 标签页

Credentials Tab

Client Authenticator 下拉列表指定用于您的客户端的凭证类型。

客户端 ID 和 Secret

这个选择是默认设置。secret 自动生成。如果需要，点 Regenerate 以重新创建 secret。

签名的 JWT

Signed JWT

签名的 JWT 为 "Signed JSON Web Token"。

在此验证器中，您可以强制 客户端使用的 签名算法（任何算法默认有效）和 JWT 令牌允许的 Max expiration （在此周期后收到的令牌将被接受，因为它们太旧，请注意，在身份验证前需要发布令牌，默认为 60 秒）。

在选择此凭证类型时，还必须在密钥键中为客户端生成私钥和证书。私钥将用于为 JWT 签名，而证书供服务器用来验证签名。

keys 标签页

Keys tab

点 Generate new keys 按钮来启动此过程。

生成密钥

generate client keys

  1. 选择要使用的存档格式。
  2. 输入 密钥密码。
  3. 输入 存储密码。
  4. 点 Generate。

当您生成密钥时，红帽构建的 Keycloak 将存储证书，并为客户端下载私钥和证书。

您还可以使用外部工具生成密钥，然后通过单击 Import Certificate 来导入客户端的证书。

导入证书

Import Certificate

  1. 选择证书的存档格式。
  2. 输入存储密码。
  3. 单击 Import File，以选择证书文件。
  4. 点 Import。

如果您单击 Use JWKS URL，则不需要导入证书。在这种情况下，您可以提供以 JWK 格式发布公钥的 URL。使用这个选项时，如果更改了密钥，Red Hat build of Keycloak 会重新导入密钥。

如果您使用由红帽构建的 Keycloak 适配器保护的客户端，您可以使用这个格式配置 JWKS URL，假设 https://myhost.com/myapp 是客户端应用程序的根 URL： 

https://myhost.com/myapp/k_jwks
Copy to Clipboard Toggle word wrap

如需了解更多详细信息，请参阅 服务器开发人员指南。

使用客户端 Secret 签名 JWT

如果选择这个选项，您可以使用由客户端 secret 签名的 JWT，而不是私钥。

客户端机密将用于由客户端签署 JWT。

与 Signed JWT 验证器中所述，您可以为 JWT 令牌配置 签名算法 和 Max expiration。

X509 证书

红帽构建的 Keycloak 将验证客户端是否在 TLS Handshake 过程中使用正确的 X509 证书。

X509 证书

x509 client auth

验证器还使用配置的 regexp 验证表达式检查证书的 Subject DN 字段。在某些情况下，接受所有证书就足够了。在这种情况下，您可以使用 (React?) (?:$) 表达式。

红帽构建的 Keycloak 有两种方法从请求获取客户端 ID：

13.1.5. 客户端 Secret 轮转
复制链接

重要

请注意，客户端 Secret 轮转支持正在开发中。实验性使用此功能。

对于具有 机密 客户端身份验证的客户端，红帽构建的 Keycloak 支持通过客户端 策略 轮转客户端 secret 的功能。

客户端 secret 轮转策略提供更高的安全性，以缓解所有问题，如 secret 泄漏。启用后，红帽构建的 Keycloak 支持每个客户端最多两个活跃的 secret。策略根据以下设置管理轮转：

  • Secret expiration: [seconds] - 当 secret 被轮转时，这是新 secret 的时间。添加到 secret 创建日期 中的数量（以秒为单位）。在策略执行时计算。
  • 轮转 secret 过期： [秒] - 当 secret 被轮转时，这个值是旧 secret 的剩余过期时间。这个值应该总是小于 Secret 过期。当值为 0 时，旧 secret 将在客户端轮转过程中立即删除。添加到 secret 轮转日期 中的数量（以秒为单位）。在策略执行时计算。
  • 其余的过期时间在更新期间进行轮转： [秒] - 当更新到动态客户端应该执行客户端 secret 轮转时的时间段。在策略执行时计算。

当发生客户端 secret 轮转时，会生成一个新的主 secret，旧客户端主 secret 将成为带有新过期日期的二级 secret。

13.1.5.1. 客户端 secret 轮转的规则
复制链接

轮转不会自动或后台进程发生。要执行轮转，需要在客户端的凭证选项卡中或 Admin REST API 中通过红帽构建 Keycloak 管理控制台的 Red Hat build of Keycloak 管理控制台进行更新操作。在调用客户端更新操作时，会根据规则进行 secret 轮转：

  • 当 Secret 过期的 值小于当前日期时。
  • 在动态客户端注册客户端更新请求过程中，如果 Remaining expiration time 的值与当前日期和 Secret 过期之间的周期匹配，客户端 secret 将自动轮转。

此外，还可以通过 Admin REST API 强制客户端 secret 轮转。

注意

在创建新客户端期间，如果客户端 secret 轮转策略处于活动状态，则行为将自动应用。

警告

要将 secret 轮转行为应用到现有客户端，请在定义策略后更新该客户端，以便应用行为。

13.1.6. 创建 OIDC 客户端 Secret 轮转策略
复制链接

以下是定义 secret 轮转策略的示例：

流程

  1. 单击菜单中的 Realm Settings。
  2. 点 Client Policies 选项卡。

  3. 在 Profiles 页面上，单击 Create client profile。

    创建配置集

    Create Client Profile

  4. 为 Name 输入任何名称。
  5. 输入描述，帮助您识别配置集的用途 描述。

  6. 点 Save。

    此操作会创建配置集，并可让您配置 executor。

  7. 单击 Add executor 以为这个配置集配置 executor。

    创建配置集执行器

    Client Profile Executor

  8. 为 Executor Type 选择 secret-rotation。
  9. 为 Secret Expiration 输入每个 secret 的最大持续时间时间（以秒为单位）。

  10. 为 Rotated Secret Expiration 输入每个轮转 secret 的最大持续时间时间（以秒为单位）。

    警告

    请记住，Rotated Secret Expiration 值必须始终小于 Secret Expiration。

  11. 输入时间（以秒为单位），之后任何更新操作都会更新 Remain Expiration Time 的客户端。

  12. 点击 Add。

    在上例中：

    • 每个 secret 在一周内都有效。
    • 轮转的 secret 会在两天后过期。
    • 更新动态客户端的窗口将在 secret 过期前一天启动。
  13. 返回到 Client Policies 选项卡。
  14. 单击 Policies。

  15. 点 Create client policy。

    创建 Client Secret 轮转策略

    Client Rotation Policy

  16. 为 Name 输入任何名称。
  17. 输入描述，帮助您识别 描述 的策略的用途。

  18. 点 Save。

    此操作会创建策略，并允许您将策略与配置集关联。它还允许您配置策略执行条件。

  19. 在 Conditions 下，单击 Add condition。

    创建 Client Secret Rotation Policy Condition

    Client Rotation Policy Condition

  20. 要将行为应用到所有机密客户端，请在 Condition Type 字段中选择 client-access-type

    注意

    要应用到特定的客户端组，另一个方法是在 Condition Type 字段中选择 client-roles 类型。这样，您可以创建特定的角色，并为各个角色分配自定义轮转配置。

  21. 将机密 添加到 字段 Client Access Type。
  22. 点击 Add。

  23. 返回到策略设置，在 Client Profiles 下，单击 Add client profile，然后从列表中选择 Weekly Client Secret Rotation Profile，然后单击 Add。

    客户端 Secret 轮转策略

    Client Rotation Policy

注意

要将 secret 轮转行为应用到现有客户端，请按照以下步骤执行：

使用管理控制台

  1. 点菜单中的 Clients。
  2. 点客户端。
  3. 点 Credentials 选项卡。
  4. 点客户端 secret 的 Re-generate。

使用客户端 REST 服务，可通过两种方式执行：

  • 在客户端上通过更新操作
  • 通过重新生成客户端 secret 端点

13.1.7. 使用服务帐户
复制链接

每个 OIDC 客户端都有一个内置 服务帐户。使用 此服务帐户 获取访问令牌。

流程

  1. 点菜单中的 Clients。
  2. 选择您的客户端。
  3. 点 Settings 选项卡。
  4. 将 客户端身份验证 切换为 On。
  5. 选择 服务帐户角色。
  6. 点击 Save。
  7. 配置客户端凭据。
  8. 点 Scope 选项卡。
  9. 验证您是否具有角色，或将 Full Scope Allowed 切换到 ON。
  10. 点 Service Account Roles 选项卡
  11. 配置此服务帐户可供您的客户端使用的角色。

来自访问令牌的角色是以下部分：

  • 客户端的角色范围映射，以及从链接的客户端范围继承的角色范围映射。
  • 服务帐户角色。

要调用的 REST URL 是 /realms/{realm-name}/protocol/openid-connect/token。此 URL 必须作为 POST 请求调用，并且要求您使用请求发布客户端凭据。

默认情况下，客户端凭证由 Authorization: Basic 标头中的客户端的 clientId 和 clientSecret 表示，但您也可以使用签名 JWT 断言或任何其他用于客户端身份验证机制来验证客户端。

您还需要根据 OAuth2 规格将 grant_type 参数设置为 "client_credentials"。

例如，用于检索服务帐户的 POST 调用类似如下： 

    POST /realms/demo/protocol/openid-connect/token
    Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials
Copy to Clipboard Toggle word wrap

响应与 OAuth 2.0 规格中的访问令牌 响应 类似。 

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":60
}
Copy to Clipboard Toggle word wrap

默认仅返回访问令牌。不会返回刷新令牌，默认情况下，在 Red Hat build of Keycloak 侧不会创建用户会话。由于缺少刷新令牌，访问令牌过期时需要重新进行身份验证。但是，这种情况并不表示红帽构建的 Keycloak 服务器的额外开销，因为默认情况下不会创建会话。

在这种情况下，不需要注销。但是，可以通过向 OAuth2 撤销端点发送请求来撤销发布的访问令牌，如 OpenID Connect Endpoints 部分所述。

13.1.8. 受众支持
复制链接

通常，部署红帽构建的 Keycloak 环境由一组使用红帽构建的 Keycloak 进行身份验证 的机密 或 公共 客户端应用程序组成。

也提供 服务 ( OAuth 2 规范中的资源服务器 )服务，服务于来自客户端应用程序的请求并为这些应用提供资源。这些服务要求 向它们 发送访问令牌(Bearer 令牌)以验证请求。这个令牌由 frontend 应用程序在登录到红帽构建的 Keycloak 时获得。

在服务间信任的环境中，您可能会遇到这种情况：

  1. 前端客户端应用程序需要针对红帽构建的 Keycloak 进行身份验证。
  2. 红帽构建的 Keycloak 验证用户身份。
  3. 红帽构建的 Keycloak 向应用程序发布令牌。
  4. 应用使用令牌来调用不受信任的服务。
  5. 不受信任的服务将响应返回给应用。但是，它会保留应用程序令牌。
  6. 然后，不受信任的服务使用应用令牌调用可信服务。这会导致安全性问题，因为不受信任的服务错误地使用令牌代表客户端应用程序访问其他服务。

这种情境不太可能在服务间具有高度信任的环境，而不是在信任较低的环境中实现。在某些环境中，此工作流可能正确，因为不受信任的服务可能需要从可信服务检索数据，才能将数据返回到原始客户端应用程序。

当服务之间存在高级别信任时，没有限制的受众很有用。否则，受众应受限制。您可以限制受众，同时允许不受信任的服务从可信服务检索数据。在这种情况下，请确保将不受信任的服务和可信服务添加为令牌的使用者。

为防止访问令牌滥用，请限制令牌的使用者并配置您的服务以验证令牌的使用者。流程将更改如下：

  1. 前端应用程序针对红帽构建的 Keycloak 进行身份验证。
  2. 红帽构建的 Keycloak 验证用户身份。

  3. 红帽构建的 Keycloak 向应用程序发布令牌。应用程序知道需要调用不受信任的服务，以便在发送到红帽构建的 Keycloak 的 身份验证请求中放置 scope=<untrusted service > （请参阅 Client Scopes 部分 以了解更多有关 scope 参数的详细信息）。

    向应用程序发布的令牌包含对 audience 中不受信任的服务的引用("audience": [ "<untrusted service>" ])，声明客户端使用此访问令牌来调用不受信任的服务。

  4. 不受信任的服务使用令牌调用可信服务。调用不成功，因为可信服务检查令牌的使用者，并发现其受众只针对不受信任的服务。这个行为是正常的，安全性不会出现问题。

如果客户端稍后希望调用可信服务，则必须通过使用 scope =<trusted service> 重新颁发 SSO 登录来获取另一个令牌。然后，返回的令牌将包含可信服务作为受众： 

"audience": [ "<trusted service>" ]
Copy to Clipboard Toggle word wrap

使用此值调用 < trusted service>。

13.1.8.1. 设置
复制链接

在设置 audience 检查时：

  • 确保将服务配置为检查发送给它们的访问令牌的受众。这可以以特定于您的客户端 OIDC 适配器的方式完成，用于保护 OIDC 客户端应用程序。
  • 确保由红帽构建的 Keycloak 发布的访问令牌包含所有必要的受众。可使用客户端角色添加受众，如 下一小节 或硬编码中所述。请参阅 硬编码受众。

13.1.8.2. 自动添加受众
复制链接

Audience Resolve 协议映射器在默认客户端 范围角色 中定义。映射器检查至少有一个客户端角色用于当前令牌的客户端。然后，每个客户端的客户端 ID 添加为受众，如果您的服务客户端依赖客户端角色，这非常有用。服务客户端通常是在没有启用任何流的情况下的客户端，这些客户端可能没有直接向自身发出的任何令牌。它代表 OAuth 2 资源服务器。

例如，对于服务客户端和机密客户端，您可以使用为机密客户端发布的访问令牌来调用服务客户端 REST 服务。如果满足以下条件，该服务客户端将自动作为 audience 添加到为机密客户端发布的访问令牌：

  • 服务客户端具有自己定义的任何客户端角色。
  • 目标用户至少分配有其中一个客户端角色。
  • 机密客户端具有所分配角色的角色范围映射。
注意

如果要确保没有自动添加 audience，请不要直接在机密客户端上配置角色范围映射。相反，您可以创建一个专用的客户端范围，其中包含专用客户端范围的客户端角色的角色范围映射。

假设客户端范围已添加为机密客户端的可选客户端范围，如果 scope=< trusted service > 参数明确请求，则客户端角色和 audience 将添加到令牌中。

注意

前端客户端本身不会自动添加到访问令牌 audience 中，因此允许在访问令牌和 ID 令牌之间轻松区分，因为访问令牌不包含作为 audience 发布令牌的客户端。

如果您需要客户端本身作为受众，请参阅 硬编码的 audience 选项。但是，不建议使用与 frontend 和 REST 服务相同的客户端。

13.1.8.3. 硬编码受众
复制链接

当服务依赖于 realm 角色或根本不依赖于令牌中的角色时，使用硬编码的受众会很有用。硬编码受众是一个协议映射程序，它会将指定服务客户端的客户端 ID 添加为令牌的使用者。如果要使用与客户端 ID 不同的使用者，您可以使用任何自定义值，如 URL。

您可以将协议映射器直接添加到 frontend 客户端。如果直接添加了协议映射程序，则也会添加受众。

若要对协议映射器进行更多控制，您可以在专用客户端范围上创建协议映射程序，例如 good-service。

受众协议映射器

audience mapper

  • 在 good-service 客户端的 Client details 选项卡中，您可以生成适配器配置，并确认 verify-token-audience 已设为 true。如果您使用此配置，此操作会强制适配器验证 audience。

  • 您需要确保机密客户端能够请求 好服务 作为其令牌中的受众。

    在机密客户端中：

    1. 点 Client Scopes 选项卡。

    2. 将 good-service 分配为可选（或默认）客户端范围。

      如需了解更多详细信息 ，请参阅客户端范围链接部分。

  • 您可以选择 评估客户端范围 并生成示例访问令牌。如果将 good-service 添加为可选客户端范围时，将 good-service 添加到生成的访问令牌的 audience 中。

  • 在机密客户端应用中，确保使用 scope 参数。当您要发出令牌以访问 good-service 时，必须包含值 good-service。

    请参阅：

    • 如果您的应用程序使用 javascript 适配器，则 安全 应用程序部分中的 Keycloak JavaScript 适配器。
注意

默认情况下，Audience 和 Audience Resolve 协议映射器都会将 audiences 添加到访问令牌中。ID 令牌通常仅包含单个 audience （签发令牌的客户端 ID），这是 OpenID Connect 规格的要求。但是，访问令牌不一定具有发出的客户端 ID，这是发布的令牌，除非读者映射了它。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat