将您的应用与Atlas App Connections 集成

关键概念

委托访问权限

您的应用程序代表Atlas 用户而不是自身运行。用户自己的组织角色和项目权限决定了哪些操作会成功。如果用户无法执行某项动作，则您的应用程序也无法代表他们执行该操作。

组织委托设置

每个Atlas组织可以控制是否允许第三方应用连接。即使用户授权您的应用程序，仅当特定组织启用了第三方应用连接时，针对该组织的操作才会成功。默认下，现有组织禁用委派。由于一个用户可能属于多个组织，因此一次授权可能会对用户的某些组织成功，而对其他组织失败，具体取决于每个组织的委派设置。

代码交换证明密钥 (PKCE)

OAuth 2.1 授权代码流的安全扩展，可防止授权代码拦截攻击。 PKCE 要求客户端生成随机 code_verifier，从中派生出 code_challenge，然后将挑战与授权请求一起发送。然后，客户端在将授权代码交换为令牌时，通过发送原始 code_verifier 来证明它发起了请求。

流程概述

点击放大

该流程分三个步骤进行：

1. 您的应用程序会生成 PKCE 代码验证程序和挑战，将用户重定向到Atlas授权端点，然后用户在同意屏幕上批准访问权限。

2. 您的应用程序将授权代码交换为访问权限令牌和刷新令牌。

3. 您的应用程序使用访问权限令牌调用Atlas Administration API ，并使用刷新令牌在新的访问权限令牌过期之前获取它们。

步骤 1：授权请求

使用以下参数将用户定向到Atlas授权端点 (https://cloud.mongodb.com/oauth/authorize)。您可以控制应用程序显示此端点的方式：现有窗口内的重定向、新的浏览器窗口或弹出窗口。

仅发送上表中的参数。授权端点不需要 resource 参数，因此即使 OAuth 2.1 规范定义了参数，也请从授权请求中省略该参数。

为了便于阅读，以下示例将URL换行。以单行形式发送：

https://cloud.mongodb.com/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &state=<RANDOM_STATE_VALUE>

步骤 2：令牌交换

通过向Atlas令牌端点发出 POST请求，将授权代码交换为令牌：

POST https://authorize.mongodb.com/tokens

请求示例：

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'code=<AUTHORIZATION_CODE>' \
  --data 'code_verifier=<CODE_VERIFIER>' \
  --data 'redirect_uri=https://yourapp.example.com/callback' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

响应包括：

步骤 3：刷新访问令牌

访问令牌的有效期很短（目前为 10 分钟）。在过期后进行Atlas Administration API调用之前，请将刷新令牌交换为新的访问权限令牌：

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=<YOUR_REFRESH_TOKEN>' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

响应始终返回一个新的 access_token 和一个新的 refresh_token。先前的刷新令牌会立即失效。始终替换这两个存储的值。

权限和组织委派设置

仅当以下两个条件为 true 时，针对特定Atlas组织的操作才会成功：

• 组织已启用第三方应用连接。组织所有者在 Organization Settings > 中配置此设置。 App Connections。要学习；了解有关这些设置的更多信息，请参阅Atlas App Connections 概述。

• 授权用户具有该组织或项目中操作所需的角色。

如果在用户授权您的应用程序后为组织禁用委派，则针对该组织的API调用将返回 403 Forbidden 响应。

已完成的授权并不能保证Atlas Administration API调用成功。 Atlas在每次请求（而不是在授权时）评估组织的委托设置和用户角色，因此 OAuth 流程和同意屏幕可以干净利落地完成，同时请求仍返回 403 Forbidden。

检查组织访问权限

授权后调用 GET /api/atlas/v2/orgs 以确定应用程序可以操作的组织。 Atlas仅返回允许第三方应用连接的组织，因此空列表意味着用户所属的组织均未启用第三方应用程序连接。

空列表是设置步骤，而不是失败。提示用户要求组织所有者为组织启用应用连接，并点他们查看Atlas App Connections Overview（Atlas 应用程序连接概述）。避免将空列表显示为授权或身份验证错误，因为用户的凭证和同意是有效的。

由于委派访问权限包含授权用户自己的权限，因此写入操作也取决于该用户的角色。常见的预配操作需要以下角色：

• 要创建项目，用户需要 Organization Owner 或 Organization Project Creator角色。

• 要创建集群，用户需要目标项目的 Project Owner 或 Project Cluster Creator角色。

仅持有 Organization Member角色的用户可以读取他们有权访问权限的资源，但写入操作会返回 403 Forbidden。命名错误处理中所需的角色，以便用户可以请求正确的角色。要学习；了解所有可用角色，请参阅Atlas用户角色。

当应用程序代表用户创建组织时，新组织尚不允许第三方应用连接。启用它们是一个手动步骤：联系MongoDB以将组织列入允许名单。在此之前，即使用户授权了您的应用程序应用程序，您的应用程序也无法对组织执行操作。

阻止和过滤的端点

委托访问权限可到达大多数Atlas Administration API端点，但无论授权用户的权限如何， Atlas都会以不同方式对待某些端点。

即使授权用户拥有通常允许该操作的角色，被阻止的端点也会返回 403 Forbidden 响应。 Atlas会阻止联合设置端点，这些端点读取和修改联合和单点登录 (SSO) 配置。身份提供商配置在联合中的每个组织之间共享，因此对其的委托访问权限可能会暴露或扰乱从未授权过您的应用程序的组织。

筛选的端点接受调用，但根据选择加入第三方应用连接的组织，限制其可以看到或更改的内容。您的应用程序只能访问这些组织， Atlas会阻止访问权限未选择加入的组织的资源。

跨组织的端点（例如列出用户可以访问权限的每个组织、项目或集群的端点）仅返回允许第三方应用连接的组织。对于创建资源的请求， Atlas会验证目标组织，并在该组织未选择加入时拒绝调用。

组织所有者选择加入 Organization Settings > App Connections。要学习；了解更多信息，请参阅权限和组织委派设置。

随着时间的推移， Atlas可能会区块或过滤其他端点以进行委托访问权限。

控制平面与数据平面

Atlas Administration API提供控制平面访问权限：您可以创建、配置和管理Atlas资源，例如组织、项目、集群和用户。它不提供直接的数据平面访问权限（在数据库中读取或写入文档）。

要访问权限Atlas集群中的数据，请通过Atlas Administration API检索集群连接字符串，并使用数据库用户和MongoDB驾驶员或Shell进行连接。连接字符串和数据库凭证与 OAuth 不记名令牌是分开的。

撤销对控制平面和数据平面访问权限的影响不同。请参阅数据平面影响。

创建数据库用户

使用授权用户的不记名令牌，通过Atlas Administration API端点 POST /api/atlas/v2/groups/{groupId}/databaseUsers 创建数据库用户。用户必须拥有允许数据库用户管理的项目角色。

推荐实践

• 保持在数据库用户限制之内。 Atlas对每个项目强制执行 100数据库用户的默认限制。尽可能重复使用现有数据库用户，而不是为每个操作创建新用户，并取消预配不再需要的用户以避免达到限制。

• 使用有作用域的角色。创建具有使用案例所需的最低数据库角色的数据库用户，而不是 atlasAdmin。

• 取消预配不再需要的用户。当用户撤销对应用程序的访问权限时，删除应用程序代表他们创建的任何数据库用户。撤销访问权限时， Atlas不会自动删除数据库用户。

• 按定义的安排轮换凭证。如果您的应用程序存储数据库用户密码，请使用 PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username} 端点定期轮换密码。

如果Atlas轮换应用程序预配资源（例如数据库用户的密码）的凭证，它可以通过可选的 Webhook 通知您的应用程序，而不是要求您自行更新凭证。这与轮换 OAuth client_secret 无关；有关详细信息，请参阅令牌和密钥存储。要实现Webhook，请参阅实施档案轮换 Webhook。

静态加密凭证

您的应用程序处理几类必须静态加密的敏感信息：

• 连接字符串。 Atlas连接字符串包含嵌入式凭证或参考数据库用户。使用高级加密标准 (AES)-256 或等效加密对任何存储的连接字符串进行加密。请勿将连接字符串以明文形式存储在配置文件、环境变量存储或数据库中。

• OAuth 令牌。刷新令牌是长期凭证。将它们存储在加密的密钥管理器中（示例，HashiCorp Vault、 Amazon Web Services (AWS) Secrets 经理或Azure Key Vault ）。不要在未加密的情况下将刷新令牌存储在应用程序数据库中。

• 客户端密钥。您的 client_secret 相当于密码。将其存储在密钥管理器中，如果怀疑其已被暴露，则进行轮换。

连接字符串处理

当您的应用程序代表用户从Atlas Administration API检索连接字符串时：

• 在需要时检索连接字符串，而不是尽可能长期存储它们。

• 如果您的应用程序必须保留连接字符串，请仅将所需的内容（示例主机名和端口）与凭证分开存储。

• 不要日志连接字符串，也不要将其包含在错误消息或堆栈跟踪中。

令牌和密钥存储

• 请勿将令牌或密钥提交给源代码管理。

• 不日志访问权限令牌、刷新令牌或客户端密钥。如果您的应用程序记录了用于调试的Atlas Administration API请求，请编辑 Authorization 标头。

• 将对密钥管理器中密钥的访问权限限定为仅需要这些密钥的服务。

• 定期轮换您的 client_secret，如果出现疑似遭到泄露的情况，请立即立即轮换。请联系MongoDB以轮换与您的 OAuth应用程序关联的密钥。

撤销触发器

可以通过以下任一操作进行撤销：

• 用户从Atlas用户界面撤销访问权限(User Settings > Connected Apps)。

• 组织所有者限制整个组织与 Organization Settings 的第三方应用连接。

• 刷新令牌过期的原因是已达到组织的最大刷新令牌生命周期或令牌的空闲时间超过空闲生命周期限制。

• 当您的应用程序不再需要访问权限时，它会撤销自己的令牌。

从应用程序撤销令牌

当用户断开应用程序与您自己的接口的连接时，或者您的集成不再需要访问权限时，请撤销令牌而不是让令牌过期。向撤销端点发送 POST请求：

curl --request POST \
  --url https://authorize.mongodb.com/tokens/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>' \
  --data 'token=<REFRESH_OR_ACCESS_TOKEN>' \
  --data 'token_type_hint=refresh_token'

撤销刷新令牌还会使其颁发的每个访问权限令牌失效。无论令牌是否有效，端点都会返回 200 OK，因此将成功响应视为令牌不再可用的确认，而不是令牌存在的证明。

控制平面效果

撤销生效的速度取决于撤销访问权限的人：

• 组织所有者限制第三方应用连接： Atlas Administration API会在每次调用时检查组织的委托设置，因此针对该组织的请求会立即开始返回 403 Forbidden。

• 用户撤销应用程序的访问权限：刷新令牌立即失效，但已颁发的任何访问权限令牌在过期之前仍然有效。由于访问权限令牌的有效期很短，因此您的应用程序可能会在最多 10 分钟内继续进行成功的调用。之后，调用将返回 401 Unauthorized。

• MongoDB删除您的 OAuth客户端：在您的应用程序连接到的每个组织中级联撤销，这最多需要 15 分钟才能完成。

将应用程序设计为主动处理401 和 403 响应，而不是依赖立即传播。

数据平面影响

撤销Atlas Administration API访问权限不会立即终止现有数据平面连接。您的应用程序通过其创建的数据库用户到达数据平面，使用独立于 OAuth 令牌的凭证进行身份验证。撤销令牌并不会使这些凭证失效。打开MongoDB驾驶员会话和连接池连接将保持活动状态，直到被正常的连接生命周期事件关闭，例如超时、空闲关闭或应用程序显式关闭。

由于撤销不会删除应用程序创建的数据库用户，因此应在断开连接流程中将其清理。要学习；了解更多信息，请参阅数据库用户生命周期。

Error Scenarios

OAuth 错误响应

来自授权和令牌端点的错误遵循标准 OAuth 结构：

{
  "error": "error_code",
  "error_description": "Human-readable explanation"
}

下表列出了常见的 error 值：

如果多次提供相同的授权代码，服务器将使与该授权关联的所有令牌失效，作为防止代码拦截的安全措施。发生这种情况时，用户必须从头开始重新授权。

已禁用的客户端

MongoDB可以禁用已注册的客户端，示例在事件响应或合作退出期间。当客户端被禁用时，服务器拒绝启动新的授权流程或颁发新令牌：

• 授权端点将用户重定向到 error=access_denied 的 redirect_uri，error_description 为 client is disabled。

• 令牌端点返回带有 invalid_client 和相同描述的 401。这适用于每种授权类型，包括 refresh_token，因此应用程序在禁用时无法交换现有的刷新令牌。

在禁用客户端之前颁发的访问令牌在过期之前仍然有效。禁用客户端会阻止新令牌，而不是使现有令牌失效。

禁用的客户端无法自行恢复。将 client is disabled 视为终止条件：停止重试，显示故障，并联系MongoDB合作团队以重新启用客户端。