当前位置：首页 > news >正文

使用 Postman 访问 Keycloak 端点

news 2026/2/9 10:36:59

1. 引言

在本教程中，我们将首先快速回顾 OAuth 2.0、OpenID 和 Keycloak。然后，我们将了解 Keycloak REST API 以及如何在 Postman 中调用它们。

2. OAuth 2.0

OAuth 2.0 是一个授权框架，它允许经过身份验证的用户通过令牌向第三方授予访问权限。令牌通常仅限于某些生命周期有限的范围。因此，它是用户凭证的安全替代方案。

OAuth 2.0 带有四个主要组件：

Resource Owner(资源所有者) – 拥有受保护资源或数据的最终用户或系统
Resource Server(资源服务器) – 该服务通常通过基于 HTTP 的 API 公开受保护的资源
Client(客户端) – 代表资源所有者调用受保护的资源
Authorization Server(授权服务器) – 颁发 OAuth 2.0 令牌，并在对资源所有者进行身份验证后将其交付给客户端

OAuth 2.0 是一种具有一些标准流的协议，我们在此重点设计一下授权服务器组件。

3. OpenID 连接

OpenID Connect 1.0 （OIDC）构建在 OAuth 2.0 之上，用于向协议添加身份管理层。因此，它允许客户端通过标准 OAuth 2.0 流程验证最终用户的身份并访问基本配置文件信息。OIDC 向 OAuth 2.0 引入了一些标准范围，例如 openid、profile 和 email。

4. Keycloak 作为授权服务器

**JBoss 开发了 Keycloak 作为基于 Java 的开源身份和访问管理解决方案。 **除了支持 OAuth 2.0 和 OIDC 之外，它还提供身份代理、用户联合和 SSO 等功能。

我们可以将 Keycloak 用作带有管理控制台的独立服务器，或将其嵌入到 Spring 应用程序中。一旦我们以这两种方式中的任何一种运行了 Keycloak，我们就可以尝试访问其端点。

5. Keycloak 端点

Keycloak 为 OAuth 2.0 流程提供了各种 REST 端点。要在 Postman 中使用这些端点，我们首先要创建一个名为 “Keycloak” 的环境。然后，添加一些键值对，用于设置 Keycloak 授权服务器的 URL、领域、OAuth 2.0 客户端 ID 和客户端密码：
在这里插入图片描述

5.1. OpenID 配置端点

配置终端节点类似于根目录。它返回所有其他可用终端节点、支持的范围和声明以及签名算法。

让我们在 Postman 中创建一个请求：{{server}}/realms/{{realm}}/.well-known/openid-configuration。Postman 在运行时从所选环境中设置 {{server}} 和 {{realm}} 的值：

然后我们将执行请求，如果一切顺利，我们将得到一个响应：
在这里插入图片描述
如前所述，我们可以在响应中看到所有可用的终端节点，例如 “authorization_endpoint”、“token_endpoint” 等。

此外，响应中还有其他有用的属性。例如，我们可以从 “grant_types_supported” 中找出所有支持的授权类型，或者从 “scopes_supported” 中找出所有支持的作用域。

5.2. 授权端点

让我们继续了解负责 OAuth 2.0 授权代码流程的授权端点。它在 OpenID 配置响应中以 *“authorization_endpoint” *的形式提供。

授权端点：{{server}}/realms/{{realm}}/protocol/openid-connect/auth?response_type=code&client_id={{clientId}}

此外，此端点接受 scope 和 redirect_uri 作为可选参数。

我们不会在 Postman 中使用此端点，通常通过浏览器发起授权码流程。如果没有有效的登录 cookie，Keycloak 会将用户重定向到登录页面。最后，授权码会被发送到重定向 URL。接下来，我们将了解如何获取访问令牌。

5.3. 令牌端点

令牌终端节点允许我们检索访问令牌、刷新令牌或 id 令牌。OAuth 2.0 支持不同的授权类型，例如 authorization_code、refresh_token 或 password。

令牌端点：{{server}}/realms/{{realm}}/protocol/openid-connect/token

但是，每种授权类型都需要一些专用的表单参数。

5.3.1. 授权码流程

我们将首先测试令牌端点，以获取code(授权码)对应的访问令牌。请求正文中传递这些表单参数：client_id、client_secret、grant_type、code 和 redirect_uri。令牌终端节点还接受 scope 作为可选参数：

模拟获得code

浏览器访问：

http://192.168.1.212:8080/realms/cemx/protocol/openid-connect/auth?response_type=code&client_id=cemc-client&redirect_uri=http://192.168.1.128:8081/login/oauth2/code/keycloak
在登录界面里面输入用户名和密码
查看浏览器网络访问

通过code获得Token

在这里插入图片描述

5.3.2. 用户名密码流程

如果我们想绕过授权码流程，可以选择 password 授权类型。这里我们需要用户凭证，因此当我们的网站或应用程序中有内置登录页面时，可以使用此流程。让我们创建一个 Postman 请求，并在正文中传递表单参数 client_id、client_secret、grant_type、username 和 password：
在这里插入图片描述

在执行此请求之前，我们必须将 username 和 password 变量添加到 Postman 的环境键/值对中。

另一种有用的授权类型是* refresh_token*。当我们拥有来自上一次对 token 终端节点的有效刷新令牌时，我们可以使用它。刷新令牌流需要参数 client_id、client_secret、grant_type 和 refresh_token。

我们需要响应access_token来测试其他终端节点。为了加快使用 Postman 的测试速度，我们可以在令牌终端节点请求的 Scripts 部分编写一个脚本：
在这里插入图片描述

如果出现错误”keycloak Client not allowed for direct access grants“，说明这里需要Direct access grants的开启

在这里插入图片描述

5.4. 用户信息端点

当我们拥有有效的访问令牌时，我们可以从用户信息终端节点检索用户配置文件数据。

用户信息端点：{{server}}/realms/{{realm}}/protocol/openid-connect/userinfo

现在，我们将为其创建一个 Postman 请求，并在 Authorization 标头中传递访问令牌：

这里的access_token就是上一步获得写入环境中的Access Token，考虑到需要获得用户信息，采用scope 为openid，所以，上一步我红色标准的参数别忘记了。
不然，该请求的响应头中有报错信息，如 error=“insufficient_scope”, error_description=“Missing openid scope”
原因：当前使用的 access_token 丢失了 openid 这个作用范围。说明这个 access_token 不支持 openid 的方式请求 userinfo。解决这个问题，需要在请求 token 时，显式的增加 scope=openid 的参数。

5.5. Token Introspect 端点

如果资源服务器需要验证访问令牌是否有效，或者想要获取更多关于它的元数据（特别是对于 opaque access tokens[不透明的访问令牌]），那么令牌内省端点就能满足需求。在这种情况下，资源服务器将 introspect 过程与安全配置集成在一起。

introspect 端点：{{server}}/realms/{{realm}}/protocol/openid-connect/token/introspect

然后，我们将在 Postman 中创建一个 introspect 请求，并将 client_id、client_secret 和 token 作为表单参数传递：

如果 access_token 有效，我们将得到如下响应：
在这里插入图片描述

但是，如果我们使用无效的访问令牌，则响应将是：
在这里插入图片描述

6. 总结

在本文中，使用正在运行的 Keycloak Server，我们为授权、令牌、用户信息和内省端点创建了 Postman 请求。

7. 关于

关于使用postman的具体操作，请参考《使用 Spring Boot 和 Keycloak 的 OAuth2 快速指南》，该下载区有源码。