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

5.2. 客户端发起的帐户链接

有些应用程序需要与实验室供应商（如 Ice）集成，但不想提供通过这些社交提供商登录的选项。红帽构建的 Keycloak 提供了一个基于浏览器的 API，应用程序可以使用它将现有用户帐户链接到特定的外部 IDP。这称为 client-initiated account link。链接的帐户只能由 OIDC 应用程序启动。

其工作方式在于，应用程序将用户的浏览器转发到红帽构建的 Keycloak 服务器上的 URL，要求它希望将用户帐户链接到特定的外部提供程序（例如，Facebook）。服务器使用外部提供程序启动登录。浏览器在外部提供程序登录，并重定向到服务器。服务器建立链接，并通过确认重新重定向到应用程序。

在启动此协议前，客户端应用程序必须满足一些先决条件：

  • 必须为 admin 控制台中的用户域配置和启用所需的身份提供程序。
  • 用户帐户必须已经通过 OIDC 协议以现有用户身份登录
  • 用户必须具有 account.manage-account 或 account.manage-account-links 角色映射。
  • 应用程序必须在其访问令牌内授予这些角色的范围
  • 应用必须有权访问其访问令牌，因为它需要其中的信息来生成重定向 URL。

要启动登录，应用程序必须光纤一个 URL，并将用户的浏览器重定向到此 URL。URL 类似如下： 

/{auth-server-root}/realms/{realm}/broker/{provider}/link?client_id={id}&redirect_uri={uri}&nonce={nonce}&hash={hash}

下面是每个路径和查询参数的描述：

provider
这是您在管理控制台的 Identity Provider 部分中定义的外部 IDP 的供应商别名。
client_id
这是应用程序的 OIDC 客户端 ID。当您在 admin 控制台中将应用程序注册为客户端时，您必须指定此客户端 ID。
redirect_uri
这是您在建立帐户链接后要重定向到的应用程序回调 URL。它必须是有效的客户端重定向 URI 模式。换句话说，它必须与您在管理控制台中注册客户端时定义的一个有效 URL 模式匹配。
nonce
这是应用程序必须生成的随机字符串
hash
这是一个 Base64 URL 编码哈希。此哈希值由 Base64 URL 编码的 一个非ce + token.getSessionState （） + token.getIssuedFor （） 的 SHA_256 哈希生成。令牌变量从 OIDC 访问令牌获取。基本上，您要对随机非ce、用户会话 ID、客户端 ID 和您要访问的身份提供程序别名进行哈希处理。

以下是生成 URL 的 Java Servlet 代码示例，以建立帐户链接。 

   KeycloakSecurityContext session = (KeycloakSecurityContext) httpServletRequest.getAttribute(KeycloakSecurityContext.class.getName());
   AccessToken token = session.getToken();
   String clientId = token.getIssuedFor();
   String nonce = UUID.randomUUID().toString();
   MessageDigest md = null;
   try {
      md = MessageDigest.getInstance("SHA-256");
   } catch (NoSuchAlgorithmException e) {
      throw new RuntimeException(e);
   }
   String input = nonce + token.getSessionState() + clientId + provider;
   byte[] check = md.digest(input.getBytes(StandardCharsets.UTF_8));
   String hash = Base64Url.encode(check);
   request.getSession().setAttribute("hash", hash);
   String redirectUri = ...;
   String accountLinkUrl = KeycloakUriBuilder.fromUri(authServerRootUrl)
                    .path("/realms/{realm}/broker/{provider}/link")
                    .queryParam("nonce", nonce)
                    .queryParam("hash", hash)
                    .queryParam("client_id", clientId)
                    .queryParam("redirect_uri", redirectUri).build(realm, provider).toString();

为什么包含这个哈希？我们这样做，以便身份验证服务器可以保证知道客户端应用程序启动请求，且没有其他恶意应用程序只是随机要求用户帐户链接到特定提供程序。身份验证服务器首先将检查用户是否登录，方法是检查登录时设置的 SSO cookie。然后，它将尝试基于当前登录重新生成哈希，并将它与应用发送的哈希值匹配。

链接帐户后，auth 服务器将重定向到 redirect_uri。如果提供链接请求的问题，auth 服务器可能会也可能不会重定向到 redirect_uri。浏览器可能只是在错误页面结束，而不是重定向到应用。如果出现错误条件，并且 auth 服务器认为能够安全地重定向到客户端应用，则将附加额外的 错误 查询参数到 redirect_uri。

警告

虽然此 API 保证应用程序启动请求，但它不会完全防止 CSRF 攻击。应用程序仍负责保护 CSRF 攻击目标。

5.2.1. 刷新外部令牌
复制链接

如果您使用登录到供应商生成的外部令牌（例如，Cyter 或 GitHub 令牌），您可以通过重新发起帐户链接 API 来刷新此令牌。

Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2026 Red Hat返回顶部