/realms/{realm-name}/.well-known/openid-configuration
作为完全兼容 OpenID Connect 提供程序的实现,Keycloak 公开了一组端点,应用程序和服务可以使用这些端点来验证和授权其用户。
本节介绍应用程序和服务在与 Keycloak 交互时应使用的一些关键端点。
要理解的最重要的端点是 well-known
配置端点。它列出了与 Keycloak 中 OpenID Connect 实现相关的端点和其他配置选项。该端点是
/realms/{realm-name}/.well-known/openid-configuration
要获得完整 URL,请添加 Keycloak 的基本 URL,并将 {realm-name}
替换为您的 realm 名称。例如
https://127.0.0.1:8080/realms/master/.well-known/openid-configuration
一些 RP 库从此端点检索所有必需的端点,但对于其他库,您可能需要单独列出端点。
/realms/{realm-name}/protocol/openid-connect/auth
授权端点执行最终用户的身份验证。此身份验证通过将用户代理重定向到此端点来完成。
有关更多详细信息,请参阅 OpenID Connect 规范中的 授权端点 部分。
/realms/{realm-name}/protocol/openid-connect/token
令牌端点用于获取令牌。令牌可以通过交换授权码或直接提供凭据来获取,具体取决于使用的流程。令牌端点也用于在访问令牌过期时获取新的访问令牌。
有关更多详细信息,请参阅 OpenID Connect 规范中的 令牌端点 部分。
/realms/{realm-name}/protocol/openid-connect/userinfo
用户信息端点返回有关已验证用户的标准声明;此端点受 bearer 令牌保护。
有关更多详细信息,请参阅 OpenID Connect 规范中的 用户信息端点 部分。
/realms/{realm-name}/protocol/openid-connect/logout
注销端点注销已验证的用户。
用户代理可以重定向到该端点,这将导致活动用户会话被注销。然后,用户代理被重定向回应用程序。
应用程序也可以直接调用该端点。要直接调用此端点,需要包含刷新令牌以及验证客户端所需的凭据。
/realms/{realm-name}/protocol/openid-connect/certs
证书端点返回 realm 启用的公钥,编码为 JSON Web Key (JWK)。根据 realm 设置,可以启用一个或多个密钥来验证令牌。有关更多信息,请参阅 服务器管理指南 和 JSON Web Key 规范。
/realms/{realm-name}/protocol/openid-connect/token/introspect
内省端点用于检索令牌的活动状态。换句话说,您可以使用它来验证访问令牌或刷新令牌。此端点只能由保密客户端调用。
有关如何调用此端点的更多详细信息,请参阅 OAuth 2.0 令牌内省规范。
您可以使用 HTTP 标头 Accept: application/jwt
而不是 Accept: application/json
来调用内省端点。在 application/jwt
的情况下,响应可能包含附加声明 jwt
以及完整的 JWT 访问令牌,这在要内省的令牌是 轻量级访问令牌 时尤其有用。这要求您在客户端高级设置中启用 Support JWT claim in Introspection Response
,这将触发令牌内省。
/realms/{realm-name}/clients-registrations/openid-connect
动态客户端注册端点用于动态注册客户端。
有关更多详细信息,请参阅 <@links.securingapps id="client-registration" /> 指南和 OpenID Connect 动态客户端注册规范。
/realms/{realm-name}/protocol/openid-connect/revoke
令牌撤销端点用于撤销令牌。此端点支持刷新令牌和访问令牌。当撤销刷新令牌时,也会撤销对相应客户端的用户授权。
有关如何调用此端点的更多详细信息,请参阅 OAuth 2.0 令牌撤销规范。
/realms/{realm-name}/protocol/openid-connect/auth/device
设备授权端点用于获取设备代码和用户代码。它可以由保密客户端或公共客户端调用。
有关如何调用此端点的更多详细信息,请参阅 OAuth 2.0 设备授权 Grant 规范。
/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth
Backchannel 身份验证端点用于获取 auth_req_id,该 auth_req_id 标识客户端发出的身份验证请求。它只能由保密客户端调用。
有关如何调用此端点的更多详细信息,请参阅 OpenID Connect 客户端发起的 Backchannel 身份验证流程规范。
另请参阅 Keycloak 文档的其他位置,例如本指南的 客户端发起的 Backchannel 身份验证 Grant 部分 和服务器管理指南的 客户端发起的 Backchannel 身份验证 Grant 部分。
本节介绍中继方可用的不同 grant 类型。
授权码流程将用户代理重定向到 Keycloak。一旦用户成功通过 Keycloak 身份验证,就会创建一个授权码,并且用户代理被重定向回应用程序。然后,应用程序使用授权码及其凭据从 Keycloak 获取访问令牌、刷新令牌和 ID 令牌。
该流程的目标是 Web 应用程序,但也建议用于本机应用程序,包括移动应用程序,在这些应用程序中可以嵌入用户代理。
有关更多详细信息,请参阅 OpenID Connect 规范中的 授权码流程。
隐式流程的工作方式与授权码流程类似,但它返回的是访问令牌和 ID 令牌,而不是授权码。这种方法减少了交换授权码以获取访问令牌的额外调用需求。但是,它不包含刷新令牌。这导致需要允许具有长过期时间的访问令牌;但是,这种方法是不切实际的,因为很难使这些令牌失效。或者,您可以要求新的重定向以在初始访问令牌过期后获取新的访问令牌。如果应用程序只想验证用户身份并自行处理注销,则隐式流程非常有用。
您可以改为使用混合流程,其中同时返回访问令牌和授权码。
需要注意的一点是,隐式流程和混合流程都存在潜在的安全风险,因为访问令牌可能会通过 Web 服务器日志和浏览器历史记录泄露。您可以通过对访问令牌使用短过期时间来在某种程度上缓解此问题。
有关更多详细信息,请参阅 OpenID Connect 规范中的 隐式流程。
根据当前的 OAuth 2.0 安全最佳实践,不应使用此流程。此流程已从未来的 OAuth 2.1 规范 中删除。
资源所有者密码凭据(在 Keycloak 中称为直接 Grant)允许交换用户凭据以获取令牌。根据当前的 OAuth 2.0 安全最佳实践,不应使用此流程,而应首选替代方法,例如 设备授权 Grant 或 授权码。
使用此流程的限制包括
用户凭据暴露给应用程序
应用程序需要登录页面
应用程序需要了解身份验证方案
身份验证流程的更改需要更改应用程序
不支持身份代理或社交登录
不支持流程(用户自助注册、所需操作等)
此流程的安全问题包括
让 Keycloak 以外的更多实体参与凭据处理
凭据泄露可能发生的脆弱表面积增加
创建一个生态系统,用户信任另一个应用程序输入其凭据,而不是 Keycloak
为了允许客户端使用资源所有者密码凭据 Grant,客户端必须启用 Direct Access Grants Enabled
选项。
此流程未包含在 OpenID Connect 中,但它是 OAuth 2.0 规范的一部分。它已从未来的 OAuth 2.1 规范 中删除。
有关更多详细信息,请参阅 OAuth 2.0 规范中的 资源所有者密码凭据 Grant 章节。
以下示例展示了如何使用 confidential client myclient
获取 realm master
中用户名为 user
和密码为 password
的用户的访问令牌
curl \
-d "client_id=myclient" \
-d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \
-d "username=user" \
-d "password=password" \
-d "grant_type=password" \
"https://127.0.0.1:8080/realms/master/protocol/openid-connect/token"
当客户端(应用程序和服务)想要代表自身而不是代表用户获取访问权限时,使用客户端凭据。例如,这些凭据对于在系统中应用更改的后台服务(而不是特定用户)非常有用。
Keycloak 提供对客户端使用密钥或公钥/私钥进行身份验证的支持。
此流程未包含在 OpenID Connect 中,但它是 OAuth 2.0 规范的一部分。
有关更多详细信息,请参阅 OAuth 2.0 规范中的 客户端凭据 Grant 章节。
设备授权 Grant 由在具有有限输入功能或缺少合适浏览器的联网设备上运行的客户端使用。
应用程序请求 Keycloak 提供设备代码和用户代码。
Keycloak 创建设备代码和用户代码。
Keycloak 返回包含设备代码和用户代码的响应给应用程序。
应用程序向用户提供用户代码和验证 URI。用户访问验证 URI 以使用另一个浏览器进行身份验证。
应用程序重复轮询 Keycloak,直到 Keycloak 完成用户授权。
如果用户身份验证完成,则应用程序获取设备代码。
应用程序使用设备代码及其凭据从 Keycloak 获取访问令牌、刷新令牌和 ID 令牌。
有关更多详细信息,请参阅 OAuth 2.0 设备授权 Grant 规范。
客户端发起的 Backchannel 身份验证 Grant 由想要通过直接与 OpenID 提供程序通信来启动身份验证流程的客户端使用,而无需像 OAuth 2.0 的授权码 Grant 那样通过用户的浏览器重定向。
客户端从 Keycloak 请求一个 auth_req_id,该 auth_req_id 标识客户端发出的身份验证请求。Keycloak 创建 auth_req_id。
收到此 auth_req_id 后,此客户端需要重复轮询 Keycloak 以获取访问令牌、刷新令牌和 ID 令牌,以换取 auth_req_id,直到用户通过身份验证。
如果客户端使用 ping
模式,则无需重复轮询令牌端点,但它可以等待 Keycloak 发送到指定的客户端通知端点的通知。客户端通知端点可以在 Keycloak 管理控制台中配置。客户端通知端点的合同详细信息在 CIBA 规范中描述。
有关更多详细信息,请参阅 OpenID Connect 客户端发起的 Backchannel 身份验证流程规范。
另请参阅 Keycloak 文档的其他位置,例如本指南的 Backchannel 身份验证端点 和服务器管理指南的 客户端发起的 Backchannel 身份验证 Grant 部分。有关 FAPI CIBA 合规性的详细信息,请参阅本指南的 FAPI 部分。
Keycloak 服务器可以在 OIDC 身份验证响应中向客户端应用程序发送错误,参数为 error=temporarily_unavailable
和 error_description=authentication_expired
。当用户通过身份验证并具有 SSO 会话时,Keycloak 会发送此错误,但身份验证会话在当前浏览器选项卡中过期,因此 Keycloak 服务器无法自动执行用户的 SSO 重新身份验证并使用成功响应重定向回客户端。当客户端应用程序收到此类错误时,最好立即重试身份验证并向 Keycloak 服务器发送新的 OIDC 身份验证请求,由于 SSO 会话,这通常应始终验证用户身份并重定向返回。有关更多详细信息,请参阅 服务器管理指南。
Keycloak 使管理员更容易确保其客户端符合以下规范
此合规性意味着 Keycloak 服务器将验证规范中提到的授权服务器的要求。Keycloak 适配器对 FAPI 没有任何特定的支持,因此客户端(应用程序)端所需的验证可能仍需要手动完成或通过其他第三方解决方案完成。
为了确保您的客户端符合 FAPI,您可以在 realm 中配置客户端策略,如 服务器管理指南 中所述,并将它们链接到 FAPI 支持的全局客户端配置文件,这些配置文件在每个 realm 中自动可用。您可以根据您需要客户端符合的 FAPI 配置文件,使用 fapi-1-baseline
或 fapi-1-advanced
配置文件。您还可以使用配置文件 fapi-2-security-profile
或 fapi-2-message-signing
以符合 FAPI 2 草案规范。
如果您想使用 推送授权请求 (PAR),建议您的客户端对 PAR 请求同时使用 fapi-1-baseline
配置文件和 fapi-1-advanced
配置文件。具体而言,fapi-1-baseline
配置文件包含 pkce-enforcer
执行器,该执行器确保客户端将 PKCE 与安全的 S256 算法一起使用。除非 FAPI 高级客户端使用 PAR 请求,否则这不是必需的。
如果您想以 FAPI 合规的方式使用 CIBA,请确保您的客户端同时使用 fapi-1-advanced
和 fapi-ciba
客户端配置文件。需要使用 fapi-1-advanced
配置文件或其他包含请求的执行器的客户端配置文件,因为 fapi-ciba
配置文件仅包含 CIBA 特定的执行器。当强制执行 FAPI CIBA 规范的要求时,还需要更多要求,例如强制执行保密客户端或证书绑定的访问令牌。
Keycloak 符合 巴西开放金融金融级 API 安全配置文件 1.0 实现者草案 3。这个规范在某些要求上比 FAPI 1 高级 规范更严格,因此可能需要以更严格的方式配置 客户端策略 以强制执行某些要求。特别是
如果您的客户端不使用 PAR,请确保它使用加密的 OIDC 请求对象。这可以通过使用配置了 Encryption Required
启用的 secure-request-object
执行器的客户端配置文件来实现。
确保对于 JWS,客户端使用 PS256
算法。对于 JWE,客户端应使用 RSA-OAEP
和 A256GCM
。这可能需要在所有适用这些算法的 客户端设置 中设置。
Keycloak 符合 澳大利亚消费者数据权利安全配置文件。
如果您想应用澳大利亚 CDR 安全配置文件,则需要使用 fapi-1-advanced
配置文件,因为澳大利亚 CDR 安全配置文件基于 FAPI 1.0 高级安全配置文件。如果您的客户端也应用 PAR,请确保客户端应用 RFC 7637 Proof Key for Code Exchange (PKCE),因为澳大利亚 CDR 安全配置文件要求您在应用 PAR 时应用 PKCE。这可以通过使用带有 pkce-enforcer
执行器的客户端配置文件来实现。
由于正在交换机密信息,因此所有交互都应使用 TLS (HTTPS) 加密。此外,FAPI 规范对使用的密码套件和 TLS 协议版本有一些要求。为了满足这些要求,您可以考虑配置允许的密码。可以通过设置 https-protocols
和 https-cipher-suites
选项来完成此配置。Keycloak 默认使用 TLSv1.3
,因此可能不需要更改默认设置。但是,如果您需要出于某种原因回退到较低的 TLS 版本,则可能需要调整密码。有关更多详细信息,请参阅 配置 TLS 指南。
Keycloak 使管理员更容易确保其客户端符合以下规范
此合规性意味着 Keycloak 服务器将验证规范中提到的授权服务器的要求。Keycloak 适配器对 OAuth 2.1 没有任何特定的支持,因此客户端(应用程序)端所需的验证可能仍需要手动完成或通过其他第三方解决方案完成。
为了确保您的客户端符合 OAuth 2.1,您可以在 realm 中配置客户端策略,如 服务器管理指南 中所述,并将它们链接到 OAuth 2.1 支持的全局客户端配置文件,这些配置文件在每个 realm 中自动可用。您可以为保密客户端使用 oauth-2-1-for-confidential-client
配置文件,为公共客户端使用 oauth-2-1-for-public-client
配置文件。
OAuth 2.1 规范仍为草案,将来可能会更改。因此,Keycloak 内置的 OAuth 2.1 客户端配置文件也可能会更改。 |
当为公共客户端使用 OAuth 2.1 配置文件时,建议使用 DPoP 预览功能,如 服务器管理指南 中所述,因为 DPoP 将访问令牌和刷新令牌与客户端密钥对的公共部分绑定在一起。此绑定可防止攻击者使用被盗令牌。 |
本节介绍使用 Keycloak 保护应用程序时的一些建议。
如果您需要手动验证 Keycloak 颁发的访问令牌,可以调用 内省端点。此方法的缺点是您必须对 Keycloak 服务器进行网络调用。如果同时进行太多验证请求,这可能会很慢并可能使服务器过载。Keycloak 颁发的访问令牌是 JSON Web 令牌 (JWT),使用 JSON Web 签名 (JWS) 进行数字签名和编码。由于它们以这种方式编码,因此您可以使用颁发 realm 的公钥在本地验证访问令牌。您可以将 realm 的公钥硬编码到您的验证代码中,或者使用 证书端点 和 JWS 中嵌入的密钥 ID (KID) 查找和缓存公钥。根据您使用的编码语言,存在许多第三方库,它们可以帮助您进行 JWS 验证。
当使用基于重定向的流程时,请务必为您的客户端使用有效的重定向 uri。重定向 uri 应尽可能具体。这尤其适用于客户端(公共客户端)应用程序。否则可能会导致
开放重定向 - 这可能允许攻击者创建看起来像是来自您域的欺骗链接
未经授权的进入 - 当用户已通过 Keycloak 身份验证时,攻击者可以使用未正确配置重定向 uri 的公共客户端,通过在用户不知情的情况下重定向用户来获得访问权限
在生产环境中,对于 Web 应用程序,始终对所有重定向 URI 使用 https
。不允许重定向到 http。
还存在一些特殊的重定向 URI
http://127.0.0.1
此重定向 URI 对于本机应用程序非常有用,并允许本机应用程序在随机端口上创建一个 Web 服务器,该服务器可用于获取授权码。此重定向 uri 允许任何端口。请注意,根据 OAuth 2.0 for Native Apps,不 建议使用 localhost
,而应使用 IP 字面量 127.0.0.1
。
urn:ietf:wg:oauth:2.0:oob
如果无法在客户端启动 Web 服务器(或浏览器不可用),则可以使用特殊的 urn:ietf:wg:oauth:2.0:oob
重定向 uri。当使用此重定向 uri 时,Keycloak 会显示一个页面,其中代码在标题中和页面上的一个框中。应用程序可以检测到浏览器标题已更改,或者用户可以手动复制代码并粘贴到应用程序中。使用此重定向 uri,用户可以使用不同的设备来获取代码以粘贴回应用程序。