5.2. 客户端启动帐户链接
有些应用程序希望与 Facebook 等社交提供商集成,但不想通过这些社交提供商登录。红帽 Keycloak 的构建提供了基于浏览器的 API,应用程序可以使用该 API 将现有用户帐户链接到特定的外部 IDP。这称为客户端发起的帐户链接。帐户链接只能由 OIDC 应用程序启动。
它的工作方式是,应用程序将用户的浏览器转发到红帽构建的 Keycloak 服务器的 URL,要求其要将用户的帐户链接到特定的外部提供程序(如bookbook)。服务器使用外部提供程序启动登录。浏览器从外部提供程序登录,并重定向到服务器。服务器建立链接,并通过确认重定向到应用程序。
在启动此协议前,客户端应用程序必须满足一些条件:
- 必须在管理控制台中为用户域配置并启用所需的身份提供程序。
- 用户帐户必须通过 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 ()+provider的 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 来检查用户是否已登录。然后,它将尝试根据当前登录来重新生成哈希,并将其与应用程序发送的哈希匹配。
链接帐户后,身份验证服务器将重定向到 redirect_uri。如果提供链接请求存在问题,则 auth 服务器可能会或可能无法重定向到 redirect_uri。浏览器可能只是在错误页面结束,而不是重新重定向到应用。如果存在错误条件,并且 auth 服务器会足够安全重定向到客户端应用,则额外的 错误 查询参数将附加到 redirect_uri 中。
虽然此 API 保证应用程序启动请求,但它不会完全防止 CSRF 攻击此操作。应用程序仍负责保护 CSRF 攻击目标。
5.2.1. 刷新外部令牌 复制链接链接已复制到粘贴板!
如果您使用通过登录到供应商(例如 Facebook 或 GitHub 令牌)生成的外部令牌,您可以通过重新发起帐户链接 API 来刷新此令牌。