4.2. 客户端启动的帐户链接

有些应用程序希望与 Facebook 等社交供应商集成，但不想通过这些社交提供商登录。红帽构建的 Keycloak 提供了一个基于浏览器的 API，应用程序可以使用它将现有用户帐户链接到特定的外部 IDP。这称为客户端发起的帐户链接。帐户链接只能由 OIDC 应用程序启动。

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

客户端应用程序必须满足一些前提条件，然后才能启动此协议：

必须在管理控制台中为用户域配置和启用所需的身份提供程序。
用户帐户必须已经通过 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}

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

Copy to Clipboard

Toggle word wrap

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

provider: 这是您在管理控制台的 Identity Provider 部分中定义的外部 IDP 的供应商别名。
client_id: 这是应用程序的 OIDC 客户端 ID。当您在管理控制台中将应用程序注册为客户端时，必须指定此客户端 ID。
redirect_uri: 这是您要在帐户链接建立后重定向到的应用程序回调 URL。它必须是有效的客户端重定向 URI 模式。换句话说，它必须与您在管理控制台中注册客户端时定义的有效 URL 模式之一匹配。
nonce: 这是应用程序必须生成的随机字符串
hash: 这是以 Base64 URL 编码的哈希。此哈希由 Base64 URL 编码为 nonce + token.getSessionState （） + token.getIssuedFor （） + 供应商 生成。令牌变量从 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();

   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();

Copy to Clipboard

Toggle word wrap

为什么包含此哈希？这样做是为了保证 auth 服务器知道客户端应用程序启动请求，而其他恶意应用程序不会随机要求用户帐户链接到特定提供程序。auth 服务器首先通过检查登录时设置的 SSO cookie 来检查用户是否已登录。然后，它将尝试根据当前登录重新生成哈希，并将其与应用程序发送的哈希匹配。

在帐户被链接后，身份验证服务器将重新重定向到 redirect_uri。如果为链接请求提供服务，则身份验证服务器可能会或不重新重定向到 redirect_uri。浏览器可能只位于错误页面，而不是重新重定向到应用。如果存在错误条件，并且 auth 服务器足够安全地重定向到客户端应用程序，则会将额外的 错误 查询参数附加到 redirect_uri。

警告

虽然此 API 保证应用程序启动了请求，但它不会阻止 CSRF 对此操作进行攻击。应用程序仍然负责保护其自身对 CSRF 攻击目标。

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

如果您使用通过登录到提供程序（例如，Facebook 或 GitHub 令牌）生成的外部令牌，您可以通过重新初始化帐户链接 API 来刷新此令牌。

4.2. 客户端启动的帐户链接

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

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.2. 客户端启动的帐户链接

4.2.1. 刷新外部令牌复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

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