Auth0 Session Management API 教程：高效管理用户会话与刷新令牌

一. 为什么需要管理用户会话？

用户在通过 Auth0 登录时，通常会启动两种会话：

本地会话（应用程序会话）：存在于应用程序端，通过 cookie 或其他机制存储用户登录状态、偏好设置等信息，用于判断用户访问权限。
授权服务器会话（Auth0 会话）：由 Auth0 管理，存储于 auth0.com 或自定义域的 cookie 中，支持单点登录（SSO），决定用户在同一租户下是否需要再次认证。

通过 Auth0 SDK 可以创建应用会话，但 Auth0 会话则由 Auth0 管理。使用 Session Management API 可以：

列出用户的活动会话并远程注销。
管理所有用户会话，实现安全强制注销。
限制并发会话数量。

二. 配置 Session Management API 访问权限

1. 启用客户端应用程序

为客户端应用启用必要权限（Scopes）：

read:sessions：列出会话并获取详细信息。
delete:sessions：关闭会话（注销用户）。

在 Auth0 管理控制台的 Management API 部分搜索 session，勾选上述权限并点击 Update 保存。

2. 获取访问令牌

获取访问令牌方法：

测试场景：可从仪表板手动获取或使用 cURL。
生产场景：程序化请求访问令牌。

示例 cURL 请求访问令牌：

curl --request POST \
  --url https://YOUR_AUTH0_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://YOUR_AUTH0_DOMAIN/api/v2/","grant_type":"client_credentials"}'

成功返回示例：

{
  "access_token": "eyJhbGci...",
  "scope": "read:sessions delete:sessions",
  "expires_in": 86400,
  "token_type": "Bearer"
}

3. 调用 API

获取令牌后，可调用 API：

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/AUTH0_API_ENDPOINT' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json'

替换相应参数即可调用不同端点。

三. 管理用户会话

1. 列出用户活动会话

使用 /api/v2/users/{userId}/sessions 列出特定用户会话：

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/sessions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

返回的 JSON 包含每个会话的：

会话 ID（id）
用户 ID（user_id）
认证时间（authenticated_at）
认证方法（authentication）
活动设备（device）
客户端应用（clients）

2. 获取单个会话详情

通过 /api/v2/sessions/{id} 获取会话详细信息：

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

3. 强制终止会话

a. 终止特定会话

curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

b. 终止用户所有会话

curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/sessions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

注意：终止 Auth0 会话不会自动注销应用程序会话，需要在应用中处理注销逻辑。

四. 会话与刷新令牌

终止会话后，如果用户持有刷新令牌，可能仍然可以重新生成访问令牌。可以通过 API 管理刷新令牌：

列出刷新令牌：

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/refresh-tokens' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

删除特定刷新令牌：

curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/refresh-tokens/6srfsU4dh510' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

删除用户所有刷新令牌：

curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/refresh-tokens' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

五. 总结

通过本文，您已掌握使用 Auth0 Session Management API 管理用户会话的完整流程，包括：

启用客户端应用权限
获取访问令牌
列出用户会话
强制终止会话
管理刷新令牌

利用这些功能，开发者可以为应用提供 安全、高效的会话管理，增强用户体验和系统安全性。

原文链接: https://auth0.com/blog/introducing-session-management-api/