管理用户会话

在此页面上

Overview

获取用户会话访问令牌
通过 HTTPS 获取用户访问令牌
从 Realm SDK 中获取用户访问令牌
刷新用户会话访问令牌
通过 HTTPS 刷新用户访问令牌
从 Realm SDK 中刷新用户访问令牌
配置刷新令牌到期时间
在管理用户界面中设置刷新令牌到期时间
通过 HTTPS 设置刷新令牌到期时间
验证和解码用户访问令牌
结束用户会话
撤销用户会话

Atlas Device Sync 、 Atlas Edge Server 、 Data API和HTTPS endpoints均已弃用。有关详细信息，请参阅弃用页面。

Overview

App Services 使用访问令牌和刷新令牌管理用户会话。访问令牌允许拥有该令牌的任何人使用与其关联的会话最多 30 分钟。即使先前的令牌已经过期，刷新令牌也可以让您为会话生成新的访问令牌。

在用户连接到 App Services 时，Realm SDK 自动管理用户访问和刷新令牌。如果您要连接到 Data API 等 API 服务，您可能需要自行管理会话。

获取用户会话访问令牌

您可以直接通过 HTTPS 或由 Realm SDK 管理的会话对用户进行身份验证，并收到用户访问令牌。

通过 HTTPS 获取用户访问令牌

您可以通过 HTTPS 直接向 App Services 发送身份验证请求以获取访问令牌。身份验证端点接受具有 JSON 正文的 HTTPS POST 请求，其中包含用户的登录凭证。如果凭证有效，则响应包含用户访问令牌。

查找应用的客户端 Client API 基础 URL

应用的身份验证端点 URL 取决于应用的部署模式。

选择应用的部署模式以确定如何构建基本 URL。

https://services.cloud.mongodb.com/api/client/v2.0/app/<App ID>

将 <App ID>替换为您的客户端应用程序ID。示例， myapp-abcde 。

https://<Region>.<Cloud>.services.cloud.mongodb.com/api/client/v2.0/app/<App ID>

将<Region>替换为您的应用的托管区域。例如， us-east-1 。
将<Cloud>替换为托管应用程序的云。例如， aws 、 azure或gcp 。
将 <App ID> 替换为您的客户端应用程序 ID。例如：myapp-abcde。

您可以使用应用位置端点以编程方式找到基本 URL。响应主体包含基本 URL，即 hostname 字段。

curl 'https://services.cloud.mongodb.com/api/client/v2.0/app/<App ID>/location'

{
  "deployment_model": "LOCAL",
  "location": "US-VA",
  "hostname": "https://us-east-1.aws.services.cloud.mongodb.com",
  "ws_hostname": "wss://ws.us-east-1.aws.services.cloud.mongodb.com"
}

验证用户身份

要对用户进行身份验证，请调用登录端点并指定身份验证提供程序。登录端点为 <Base URL>/auth/providers/<ProviderType>/login，其中 <ProviderType> 是以下类型之一：

anon-user
local-userpass
api-key
custom-token
custom-function

将登录端点附加到基本 URL 中，并发送具有 JSON 正文的 HTTPS POST 请求，其中包含所选的提供程序类型的用户登录凭证：

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/myapp-abcde/auth/providers/anon-user/login'

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/myapp-abcde/auth/providers/local-userpass/login' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "username": "test@example.com",
    "password": "Pa55w0rd"
  }'

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/myapp-abcde/auth/providers/api-key/login' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "key": "hScMWZyOKnjQMbfDPMJ1qHgtdGT2raQXdVDDvlC2SzKEBKlHKV8FK9SPCSTnODPg"
  }'

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/myapp-abcde/auth/providers/custom-token/login' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0ZXN0ZGV2LWJwcWVsIiwiZXhwIjoxNTE2MjM5MDIyLCJzdWIiOiIyNDYwMSIsInVzZXJfZGF0YSI6eyJuYW1lIjoiSmVhbiBWYWxqZWFuIiwiYWxpYXNlcyI6WyJNb25zaWV1ciBNYWRlbGVpbmUiLCJVbHRpbWUgRmF1Y2hlbGV2ZW50IiwiVXJiYWluIEZhYnJlIl19fQ.mVWr4yFf8nD1EhuhrJbgKfY7BEpMab38RflXzUxuaEI"
  }'

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/app/myapp-abcde/auth/providers/custom-function/login' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "someCustomFunctionArg": "<Login Info>"
  }'

如果身份验证请求成功，响应正文将包含用户的 access_token 和 refresh_token 值。access_token 是一个 JSON Web 令牌 (JWT)，可用于对请求进行身份验证。

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYWFzX2RldmljZV9pZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsImJhYXNfZG9tYWluX2lkIjoiNWVlYTg2NjdiY2I0YzgxMGI2NTFmYjU5IiwiZXhwIjoxNjY3OTQwNjE4LCJpYXQiOjE2Njc5Mzg4MTgsImlzcyI6IjYzNmFiYTAyMTcyOGI2YzFjMDNkYjgzZSIsInN0aXRjaF9kZXZJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInN0aXRjaF9kb21haW5JZCI6IjVlZWE4NjY3YmNiNGM4MTBiNjUxZmI1OSIsInN1YiI6IjYzNmFiYTAyMTcyOGI2YzFjMDNkYjdmOSIsInR5cCI6ImFjY2VzcyJ9.pyq3nfzFUT-6r-umqGrEVIP8XHOw0WGnTZ3-EbvgbF0",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYWFzX2RhdGEiOm51bGwsImJhYXNfZGV2aWNlX2lkIjoiMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwiYmFhc19kb21haW5faWQiOiI1ZWVhODY2N2JjYjRjODEwYjY1MWZiNTkiLCJiYWFzX2lkIjoiNjM2YWJhMDIxNzI4YjZjMWMwM2RiODNlIiwiYmFhc19pZGVudGl0eSI6eyJpZCI6IjYzNmFiYTAyMTcyOGI2YzFjMDNkYjdmOC1ud2hzd2F6ZHljbXZycGVuZHdkZHRjZHQiLCJwcm92aWRlcl90eXBlIjoiYW5vbi11c2VyIiwicHJvdmlkZXJfaWQiOiI2MjRkZTdiYjhlYzZjOTM5NjI2ZjU0MjUifSwiZXhwIjozMjQ0NzM4ODE4LCJpYXQiOjE2Njc5Mzg4MTgsInN0aXRjaF9kYXRhIjpudWxsLCJzdGl0Y2hfZGV2SWQiOiIwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAiLCJzdGl0Y2hfZG9tYWluSWQiOiI1ZWVhODY2N2JjYjRjODEwYjY1MWZiNTkiLCJzdGl0Y2hfaWQiOiI2MzZhYmEwMjE3MjhiNmMxYzAzZGI4M2UiLCJzdGl0Y2hfaWRlbnQiOnsiaWQiOiI2MzZhYmEwMjE3MjhiNmMxYzAzZGI3Zjgtbndoc3dhemR5Y212cnBlbmR3ZGR0Y2R0IiwicHJvdmlkZXJfdHlwZSI6ImFub24tdXNlciIsInByb3ZpZGVyX2lkIjoiNjI0ZGU3YmI4ZWM2YzkzOTYyNmY1NDI1In0sInN1YiI6IjYzNmFiYTAyMTcyOGI2YzFjMDNkYjdmOSIsInR5cCI6InJlZnJlc2gifQ.h9YskmSpSLK8DMwBpPGuk7g1s4OWZDifZ1fmOJgSygw",
  "user_id": "636aba021728b6c1c03db7f9"
}

从 Realm SDK 中获取用户访问令牌

在 Realm SDK 中，您可以从登录用户的 User 对象中访问该用户的访问令牌。SDK 自动刷新 SDK 操作的过期访问令牌，您可以调用方法以手动刷新这些令牌。

要了解更多信息，请参阅 Realm SDK 文档：

刷新用户会话访问令牌

访问令牌在授予后的 30 分钟过期。在访问令牌过期时，您必须获取新的访问令牌才能继续发送请求。

您可以让用户重新登录以获取新的访问令牌，但这要求用户重新输入其凭证。相反，您可以使用与用户会话关联的刷新令牌，以获取有效期为 30 分钟的新访问令牌。

在成功登录后，您将在与访问令牌相同的响应中获取刷新令牌。

通过 HTTPS 刷新用户访问令牌

会话刷新端点接受 POST 请求，其中在 Authorization 标头中包含刷新令牌。端点 URL 取决于应用的部署模式。

curl -X POST 'https://services.cloud.mongodb.com/api/client/v2.0/auth/session' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <RefreshToken>'

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYWFzX2RldmljZV9pZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsImJhYXNfZG9tYWluX2lkIjoiNWVlYTg2NjdiY2I0YzgxMGI2NTFmYjU5IiwiZXhwIjoxNjY3OTQzOTc5LCJpYXQiOjE2Njc5NDIxNzksImlzcyI6IjYzNmFjNzAyMDE5ZDJkYmY0NzUxMDRjMiIsInN0aXRjaF9kZXZJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInN0aXRjaF9kb21haW5JZCI6IjVlZWE4NjY3YmNiNGM4MTBiNjUxZmI1OSIsInN1YiI6IjYzNmFjNzAyMDE5ZDJkYmY0NzUxMDQ5MyIsInR5cCI6ImFjY2VzcyJ9.pF3DR-096Ujt9-0KOWJTU25ZuryvwMfeCI7TiHJERNg"
}

将<Region>替换为您的应用的托管区域。例如， us-east-1 。
将<Cloud>替换为托管应用程序的云。例如， aws 、 azure或gcp 。

curl -X POST 'https://<Region>.<Cloud>.services.cloud.mongodb.com/api/client/v2.0/auth/session' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <RefreshToken>'

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYWFzX2RldmljZV9pZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsImJhYXNfZG9tYWluX2lkIjoiNWVlYTg2NjdiY2I0YzgxMGI2NTFmYjU5IiwiZXhwIjoxNjY3OTQzOTc5LCJpYXQiOjE2Njc5NDIxNzksImlzcyI6IjYzNmFjNzAyMDE5ZDJkYmY0NzUxMDRjMiIsInN0aXRjaF9kZXZJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInN0aXRjaF9kb21haW5JZCI6IjVlZWE4NjY3YmNiNGM4MTBiNjUxZmI1OSIsInN1YiI6IjYzNmFjNzAyMDE5ZDJkYmY0NzUxMDQ5MyIsInR5cCI6ImFjY2VzcyJ9.pF3DR-096Ujt9-0KOWJTU25ZuryvwMfeCI7TiHJERNg"
}

从 Realm SDK 中刷新用户访问令牌

如果登录用户的访问令牌在请求时过期，Realm SDK 将自动刷新该令牌。

SDK 还允许您对 User 对象调用方法以手动刷新用户的访问令牌。

要了解更多信息，请参阅 Realm SDK 文档：

配置刷新令牌到期时间

默认情况下，刷新令牌在颁发后的 60 天过期。您可以将应用的刷新令牌到期时间间隔配置为 30 分钟到 5 年之间（含这两个值）。

匿名用户刷新令牌的到期时间很长，实际上并不会过期。相反，匿名用户帐户在创建后的 90 天自动删除。

您可以从管理用户界面或管理 API 中为应用中的所有会话配置刷新令牌到期时间。

在管理用户界面中设置刷新令牌到期时间

要从管理用户界面中为应用中的所有会话设置刷新令牌到期时间，请执行以下操作：

单击左侧导航菜单中的 App Users（应用用户）。
选择 User Settings 标签页。
找到 Refresh Token Expiration（刷新令牌到期时间）选项，然后单击 Edit（编辑）按钮。
在文本输入框中输入一个时间值，然后从下拉菜单中选择相应的时间单位（例如“分钟”或“天”）。
单击 Save（连接）。

通过 HTTPS 设置刷新令牌到期时间

要通过管理 API 为应用中的所有会话设置刷新令牌到期时间，请调用应用的设置用户刷新令牌到期时间端点，并将请求正文的 expiration_time_seconds 字段设置为所需的到期时间。

curl -X PUT \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/security/refresh_token_expiration \
  --data-raw '{
    "expiration_time_seconds": 864000
  }'

如果您成功更新刷新令牌到期时间，该端点将返回 204 响应。

验证和解码用户访问令牌

您可以对访问令牌进行解码，以验证该令牌是否具有正确的格式和有效的签名。解码的响应包括其他信息，例如访问令牌何时过期。

使用请求正文的 token 字段中的令牌，调用应用的验证并解码访问令牌管理 API 端点。

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/users/verify_token \
  --data-raw '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYWFzX2RldmljZV9pZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsImJhYXNfZG9tYWluX2lkIjoiNWNkYjEyNDA4ZTIzMmFjNGY5NTg3ZmU4IiwiZXhwIjoxNjc2NTExMjgyLCJpYXQiOjE2NzY1MDk0ODIsImlzcyI6IjYzZWQ4MTJhNDNiZTcyYzE3NmFhNWQyMyIsInN0aXRjaF9kZXZJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInN0aXRjaF9kb21haW5JZCI6IjVjZGIxMjQwOGUyMzJhYzRmOTU4N2ZlOCIsInN1YiI6IjYzZWQ4MTJhNDNiZTcyYzE3NmFhNWQyMSIsInR5cCI6ImFjY2VzcyJ9.7kHO9wjWvIaD3VewDyPhLyb-oRc7wTYZdD9-hroF-H4"
  }'

{
  "sub": "63ed812a43be72c176aa5d21",
  "exp": 1676511282,
  "iat": 1676509482,
  "iss": "63ed812a43be72c176aa5d23",
  "domain_id": "5cdb12408e232ac4f9587fe8",
  "device_id": "000000000000000000000000"
}

如果令牌有效，您将收到 200 响应。

如果令牌有效但已过期，则响应指示令牌已过期而不是包含已解码的 JWT。

"token expired"

如果令牌无效，您将收到包含错误消息的 401 响应。

{
  "error": "signature is invalid"
}

结束用户会话

建立会话后，您无法单独结束该会话，但您可以撤销用户的所有活动会话。

您可以删除访问令牌和刷新令牌的所有副本以实际结束用户会话。这会禁止进一步访问该会话，并要求用户进行身份验证和启动新的会话以继续。

每个 Realm SDK 具有一个 User.logOut() 方法，用于删除访问令牌和刷新令牌的本地副本并使刷新令牌失效，以使其无法用于获取新的访问令牌。

如果管理员或用户删除了用户帐户，则会自动撤销该用户的所有会话。

重要

保护令牌安全

即使删除了您拥有的令牌的所有副本并使之失效，也不会结束服务器上的活动会话。如果在删除访问令牌之前恶意用户复制了该令牌，他们可能会在长达 30 分钟的时间内使用该令牌发出请求，直到该令牌过期。这些请求似乎来自“注销”的用户。

撤销用户会话

您可以撤销用户的所有当前会话。这会使会话访问令牌和刷新令牌失效，并禁止用户在任何设备上发出任何请求，直到他们再次登录。

如果管理员或用户删除了用户帐户，则会自动撤销该用户的所有会话。

从左侧导航菜单中选择 App Users。
在 Users 标签页下，从列表中找到用户并单击省略号（...）。
单击 Revoke all sessions（连接）。

要撤销用户的所有会话，请调用appservices users revoke 。 CLI将提示您输入应用程序ID ，并列出该应用中的用户以供选择。

appservices users revoke

您还可以在运行以下命令时指定参数：

appservices users revoke \
  --app=<Your App ID> \
  --user=<User ID>

提示

通过将多个用户的id值指定为逗号分隔的列表，可以使用单个命令撤销多个用户的会话。

appservices users revoke --user=6099694d5debcbcc873ff413,60996996b78eca4a8d615d3a

调用撤销用户会话端点。

确保替换端点 URL 中的以下值：

{groupId} 与您的Atlas项目ID。
{appId} 与应用程序的内部ObjectId 。
{userId} 与用户的帐户 ID。

curl -X PUT \
  -H 'Authorization: Bearer {access_token}' \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/users/{userId}/logout

后退

管理用户帐户

来年

对提供商进行身份验证