Auth0 会话管理 API 简介

用户会话管理允许开发人员实现从控制会话并发到监控和终止会话等各种功能。会话管理 API，它允许您在与 Auth0 集成的应用程序中管理用户会话。

一，管理用户会话的介绍

当用户使用 Auth0 登录您的应用程序时，至少会启动两个会话：

1.本地会话（应用程序会话）

此会话存在于应用程序端。它通常使用 Cookie 或类似机制来存储信息，例如用户的登录状态、偏好或与应用程序功能相关的任何其他数据。其主要作用是向您的应用程序指示用户当前是否已登录并有权访问特定资源或功能。

2.授权服务器会话（Auth0会话）

此会话由 Auth0 的服务器管理。它通常存储在auth0.com域或与您的 Auth0 租户关联的自定义域内的 cookie 中。它主要由 Auth0 用来促进单点登录 (SSO) 等功能，并确定用户在访问同一 Auth0 租户内的其他应用程序时是否需要重新进行身份验证。

3.第三方IdP 会话

如果用户使用第三方身份提供商（例如 Google、Facebook、GitHub 或其他提供商）进行身份验证，则您将拥有第三个会话，即第三方IdP 会话，用于跟踪用户与该身份提供商之间的交互。有关更多信息，请参阅此文档。

尽管 Auth0 SDK 可以帮助您创建会话，但应用程序的会话完全由您掌控。Auth0 的会话管理由 Auth0 控制。但是，借助新的会话管理 API，您现在也可以从应用程序管理 Auth0 会话。在 Auth0 中管理经过身份验证的用户会话的能力可以满足一些需求，例如：

您可以允许用户列出他们的活动会话并通过远程注销来关闭它们。

您可以允许管理员列出所有用户会话，并可能出于安全原因强制其中任何用户注销。

您可以限制并发用户会话的数量。

二，如何使用这个新的 API

1.设置会话管理 API 的访问权限

要使用会话管理 API，您需要企业计划。如果您没有此计划但想要测试 API，您可以创建一个新租户并获得免费试用期。

您可以像使用所有管理API 一样使用会话管理API ：基本上，您需要启用客户端应用程序、获取访问令牌并调用 API 端点。

2.启用您的客户端

首先，您需要启用客户端应用程序以使用所需的范围来使用会话管理 API。特别是：

该范围使您的客户端能够列出会话并获取有关它们的详细信息。read:sessions

该范围允许您的客户端关闭会话，即注销用户。delete:sessions

要将客户端启用到这些范围，请转到Auth0 仪表板并选择要启用的应用程序。确保这是一个机器对机器应用程序。选择应用程序页面上的 API 选项卡，然后切换与 Auth0 管理 API 相对应的授权开关按钮，如下图所示：

然后，展开 Auth0 Management API 部分并使用关键字过滤权限列表session。您应该获得和项目。检查它们，如下图所示：

不要忘记单击“更新”按钮来保存您的更改。

3.获取访问令牌

现在，您的应用程序必须请求访问令牌才能调用管理 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://Y

将占位符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。

4.调用 API

现在您有了访问令牌，您可以通过在标Authorization头中传递它来调用 API 端点，如以下 cURL 请求所示：

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为相应的值。

5.管理用户会话

一旦我们启用了客户端并获取了访问令牌，让我们看看如何实际使用会话管理 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'

在此示例中，您通过指定 Auth0 域、用户 ID 和访问令牌向端点发送 GET 请求。作为响应，您将获得如下所示的 JSON 对象：

{
"sessions": [{

"id": "2Lw8dT76wJpOl924",

"user_id": "auth0|8374f7459j7493u84335",

"created_at": "2024-05-10T12:04:22:3452",

"updated_at": "2024-05-10T12:04:22:3452",

"authenticated_at": "2024-05-21T11:29:12:4251",

"authentication": { "methods":[

{

"name": "pwd",

"timestamp": "2024-05-21T11:29:12:4251"

}

]},

"idle_expires_at": "2024-05-21T12:29:12:4251",

"expires_at": "2024-05-21T18:29:12:4251",,

"device": {

"initial_ip": "142.250.184.206",

"last_ip": "142.250.184.206",

"user_agent": "Mozilla/5.0...",

"initial_asn": "8612",

"last_asn": "8612"

},

"clients":[ {"client_id": "Hwo482a51heU632d34"} ]

}

]}

这是一个包含sessions列出用户活动会话的数组的对象。每个会话都由一个包含以下属性的对象表示：会话 ID ( id)、用户 ID ( user_id)、身份验证的时间戳 ( authenticated_at)、身份验证方法 ( authentication)、会话处于活动状态的设备 ( device)、用户使用的应用程序客户端 ( clients) 等。
在上面的示例中，仅为该用户返回一个会话。
如果您有会话 ID，则可以使用端点访问有关该会话的数据。您可以从ID 或注销令牌的声明中获取会话 ID 。以下示例显示如何根据其 ID 获取会话详细信息：/api/v2/sessions/{id}sid

curl --request GET \
--url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \

--header 'Accept: application/json' \

--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

您将收到一个代表该单个会话的 JSON 对象，如下所示：

{
"id": "2Lw8dT76wJpOl924",

"user_id": "auth0|8374f7459j7493u84335",

"created_at": "2024-05-10T12:04:22:3452",

"updated_at": "2024-05-10T12:04:22:3452",

"authenticated_at": "2024-05-21T11:29:12:4251",

"authentication": { "methods":[

{

"name": "pwd",

"timestamp": "2024-05-21T11:29:12:4251"

}

]},

"idle_expires_at": "2024-05-21T12:29:12:4251",

"expires_at": "2024-05-21T18:29:12:4251",

"device": {

"initial_ip": "142.250.184.206",

"last_ip": "142.250.184.206",

"user_agent": "Mozilla/5.0...",

"initial_asn": "8612",

"last_asn": "8612"

},

"clients":[ {"client_id": "Hwo482a51heU632d34"} ]}

6.强制终止会话

除了获取有关用户会话的信息之外，如果您的应用程序启用了范围，您还可以终止它们。您可以调用两个端点并使用该方法。例如，以下 cURL 命令可终止特定的用户会话：delete:sessions/api/v2/users/{userId}/sessions/api/v2/sessions/{id}DELETE

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'

会话终止不会自动将用户从应用程序中注销。如前所述，应用程序中涉及多个会话，因此必须正确处理注销。

具体来说，会话终止事件与OpenID Connect 反向通道注销机制相关。因此，要通过会话管理 API 触发应用程序注销，必须将应用程序配置为使用启动器。阅读本文档以了解如何配置应用程序以使用启动器。

7.会话和刷新令牌

会话终止会强制用户注销。但是，如果应用程序在登录时请求刷新令牌，则即使用户会话终止后，应用程序仍可以使用此刷新令牌。

这可能是有意或无意的情况，具体取决于应用程序的特定要求。例如，假设有一个应用程序需要定期调用 API。即使用户没有活动会话，它也需要刷新令牌来确保访问令牌。另一方面，您的应用程序只能使用刷新令牌来续订具有有限生命周期的访问令牌，但您不希望刷新令牌在用户会话结束后仍然存在。

在第一种情况下，终止用户会话将按目前所示的方式进行。您无需采取额外步骤来撤销刷新令牌。

在第二种情况下，会话终止是不够的。您还需要一种方法来使当前刷新令牌无效。为此，您可以使用一些端点来帮助您管理刷新令牌。

为了使您的客户端应用程序能够管理刷新令牌，您必须将和范围添加到 Auth0 仪表板中的管理 API 配置中。read:refresh_tokensdelete:refresh_tokens

以下命令显示如何列出与给定用户相关的所有刷新令牌：

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'

您将获得一个 JSON 对象，其中包含具有所有详细信息的刷新令牌列表，如下例所示：

{
"refresh_tokens": [{

 "id": "6srfsU4dh510",

 "user_id": "auth0|8374f7459j7493u84335",

 "client_id": "Hwo482a51heU632d34",

 "created_at": "2024-05-10T12:04:22:3452",

 "updated_at": "2024-05-10T12:04:22:3452",

 "idle_expires_at": "2024-05-21T12:29:12:4251",

 "expires_at": "2024-06-21T18:29:12:4251",

 "session_id": "2Lw8dT76wJpOl924",

 "rotating": true,

 "resource_servers": [{ audience: "http://myapi.com", scopes:"read:users"}]

}]}

要删除此特定的刷新令牌，您可以按以下示例调用端点：/api/v2/refresh-tokens/{tokenId}

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

--header 'Accept: application/json' \

--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

注意如何指定要删除的刷新令牌的 ID。

如果要删除与用户关联的所有刷新令牌，可以使用以下命令：

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

--header 'Accept: application/json' \

--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

考虑到通过DELETE上述端点上的命令撤销刷新令牌是异步运行的。这意味着命令运行完毕后，刷新令牌不会立即撤销。