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

应用程序开发中的一个重要环节，它帮助开发者实现从控制会话并发到监控和终止会话等功能。本文将详细介绍如何使用 Auth0 的 Session Management API，在集成 Auth0 的应用程序中高效管理用户会话。

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

当用户通过 Auth0 登录您的应用程序时，通常会启动以下两种会话：

本地会话（应用程序会话）：此会话存在于您的应用程序端，通常通过 cookie 或类似机制存储用户的登录状态、偏好设置或其他与应用程序功能相关的数据。它的主要作用是向应用程序表明用户是否已登录并有权访问特定资源或功能。
授权服务器会话（Auth0 会话）：此会话由 Auth0 服务器管理，通常存储在 auth0.com 域名或与您的 Auth0 租户关联的自定义域名的 cookie 中。Auth0 会话主要用于支持单点登录（SSO）等功能，并决定用户在访问同一 Auth0 租户内的其他应用程序时是否需要重新认证。

虽然 Auth0 SDK 可以帮助创建会话，但应用程序会话完全由您掌控，而 Auth0 会话则由 Auth0 管理。通过新的 Session Management API，您可以从应用程序端管理 Auth0 会话，这种能力能够满足以下需求：

允许用户列出其活动会话并通过远程注销关闭它们。
允许管理员列出所有用户会话，并出于安全原因强制注销任何会话。
限制并发用户会话数量。

接下来，我们将探讨如何使用这个强大的 API。

配置 Session Management API 的访问权限

使用 Session Management API 的步骤与管理其他 API 类似，主要包括启用客户端应用程序、获取访问令牌以及调用 API 端点。

1. 启用客户端应用程序

首先，您需要为客户端应用程序启用使用 Session Management API 所需的权限范围（Scopes）：

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

在 Auth0 管理控制台中，展开 Management API 部分，使用 session 关键字筛选权限列表，勾选 read:sessions 和 delete:sessions 项。如下图所示：

完成后，记得点击 Update 按钮保存更改。

2. 获取访问令牌

接下来，您的应用程序需要请求访问令牌以调用 Management API。访问令牌的获取方式因场景而异，例如：

测试场景：可以从 Auth0 仪表板手动获取或使用 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"}'

将 YOUR_AUTH0_DOMAIN、YOUR_CLIENT_ID 和 YOUR_CLIENT_SECRET 替换为您的客户端配置中的相应值。成功请求后，您将收到如下响应：

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

您需要使用 access_token 的值来调用 API。

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'

将 YOUR_AUTH0_DOMAIN、YOUR_ACCESS_TOKEN 和 AUTH0_API_ENDPOINT 替换为相应的值。

管理用户会话

完成客户端配置和访问令牌获取后，您可以开始使用 Session Management API 管理用户会话。

列出用户的活动会话

使用 /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'

响应将返回一个包含 sessions 数组的 JSON 对象，每个会话都包含以下信息：

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

获取单个会话详情

如果您有会话 ID，可以通过 /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'

强制终止会话

如果您的应用程序启用了 delete:sessions 权限范围，可以通过以下方式终止会话：

终止特定会话：

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

终止用户的所有会话：

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

需要注意的是，终止会话不会自动将用户从应用程序中注销。您需要正确处理应用程序的注销逻辑。

会话与刷新令牌

终止会话后，用户将被强制注销。然而，如果应用程序在登录时请求了刷新令牌，刷新令牌可能仍然有效。根据应用程序的需求，您可以选择是否使刷新令牌失效。

列出用户的刷新令牌：

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/