实施档案轮换 Webhook

本页介绍了通过集成配置的资源的数据库用户凭证的轮换。这与轮换 OAuth client_secret 无关；为此，请参阅将您的应用程序与Atlas App 连接集成中的令牌和密钥存储。

当Atlas轮换与通过集成预配的资源关联的数据库用户的凭证时， Atlas会将更新的凭证发送到预先注册的 HTTPS回调端点。 Atlas独立启动档案轮换，通常是为了响应安全事件。实施此端点是可选的，但建议实施，因为它允许依赖于预配数据库用户的最终用户应用程序自动接收更新的凭证。端点不会更新或替换集成与Atlas之间的 OAuth 连接。

如果您未实现端点，这些最终用户应用程序将不会自动接收轮换的数据库用户凭证。必须通过另一种机制更新凭证，应用程序才能继续对数据库进行身份验证。

端点要求

使用以下结构公开端点：

PUT https://<your-registered-base-url>/v1/organizations/{organizationId}/projects/{projectId}/secrets

您可以在载入期间向Atlas注册您的基本URL 。 organizationId 和 projectId 路径参数标识与集成相关的Atlas组织和项目。如果您在新员工培训期间与Atlas达成一致，则可以使用不同的URL结构，但注册的基本URL和所需的标识符必须保持明确。

Atlas使用在预配建立的安装范围的不记名令牌对每个请求进行身份验证：

Authorization: Bearer <installation-access-token>
Content-Type: application/json

您的端点必须：

在每个请求中验证不记名令牌，并使用 401 Unauthorized 拒绝无效或过期的令牌。
将令牌视为机密，并使用适当的访问权限控制存储。
将 HTTPS 与来自受信任证书颁发机构的 TLS 证书结合使用。 Atlas不会通过普通HTTP调用端点，并且生产环境中不支持自签名证书。

请求正文

请求正文包含要更新的凭证键值对：

{
  "secrets": [
    {
      "name": "ATLAS_CONNECTION_STRING",
      "value": "mongodb+srv://user:pass@cluster.mongodb.net/"
    },
    {
      "name": "ATLAS_DB_USERNAME",
      "value": "app_user"
    },
    {
      "name": "ATLAS_DB_PASSWORD",
      "value": "rotated_password"
    }
  ],
  "partial": true
}

字段	必需	说明
`secrets`	必需	要更新的凭证键值对大量。
`secrets[].name`	必需	在载入过程中与Atlas达成一致的规范凭证名称。将每个商定的名称视为稳定的版本化合同。
`secrets[].value`	必需	更新后的凭证值。值可以包含特殊字符。
`partial`	Optional	当为 `true` 时，仅更新提供的凭证，其他档案保持不变。如果省略或为 `false`，则替换完整的凭证设立。

响应

状态	含义	预期行为
`200 OK` or `204 No Content`	档案已成功接受并存储。	无需响应正文。
`400 Bad Request`	请求正文格式不正确。	返回不公开凭证值的错误消息。
`401 Unauthorized`	令牌验证失败。	拒绝请求。
`404 Not Found`	无法识别组织或项目标识符。	拒绝请求。
`5xx`	发生暂时性服务器端错误。	返回错误，以便Atlas可以重试请求。

重试和幂等性

Atlas使用指数退避和有限重试次数重试失败的请求（5xx 响应或网络超时）。

您的端点必须是幂等的。您可能会收到针对同一轮换事件的重复请求，并且多次应用相同的凭证值必须产生相同的结果，而不会出错。

安全要求

除了上述身份验证要求外，您的端点还必须：

静态加密凭证。
防止凭证值出现在应用程序日志、请求日志、错误消息、遥测或明文配置文件中。
将对存储凭证的访问权限限制为有需要的系统和人员。
在 10 秒内响应。如果保存新凭证需要背景处理，请同步确认请求并异步完成处理。
如果您怀疑您的安装访问权限令牌已被泄露，请遵循商定的Atlas支持进程。

入门检查清单

在Atlas可以将轮换凭证发送到集成之前，您必须：

在新手入门期间注册回调基本URL 。
在双方建立并安全存储安装访问权限令牌。
就凭证名称和更新语义达成一致并文档下来。
部署端点，使其可通过 HTTPS 访问。
确认您的端点返回预期的状态代码。
在非生产环境中使用非生产安装手动测试端到端轮换。
测试重复传递和重试行为。

其他资源

后退

将您的应用与Atlas App Connections 集成

来年

管理应用访问