Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Implementar o Webhook de Rotação de Credenciais

Esta página aborda a rotação das credenciais de um usuário de banco de dados para um recurso provisionado por meio de sua integração. Não está relacionado à rotação do seu OAuth client_secret; para isso, consulte Armazenamento de tokens e segredos em Integre seu aplicativo com o Atlas aplicativo Connections.

Quando o Atlas rotaciona as credenciais de um usuário de banco de dados associado a um recurso provisionado por meio de sua integração, o Atlas envia as credenciais atualizadas para o seu ponto de extremidade de chamada de resposta HTTPS pré-registrado. O Atlas inicia a rotação de credenciais de forma independente, normalmente em resposta a um incidente de segurança. Implementar esse ponto de extremidade é opcional, mas recomendado, pois permite que os aplicativos do usuário final que dependem do usuário de banco de dados provisionado recebam credenciais atualizadas automaticamente. O ponto de extremidade não atualiza nem substitui a conexão OAuth entre sua integração e o Atlas.

Se você não implementar o ponto de extremidade, esses aplicativos de usuário final não receberão credenciais de usuários de banco de dados rotacionadas automaticamente. Você deve atualizar as credenciais por meio de outro mecanismo para que os aplicativos possam continuar se autenticando no banco de dados.

Exponha um ponto de extremidade usando a seguinte estrutura:

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

Você registra sua URL base com o Atlas durante a integração. Os parâmetros de caminho organizationId e projectId identificam a organização e o projeto do Atlas associados à integração. Você pode usar uma estrutura de URL diferente se concordar com o Atlas durante a integração, mas a URL base registrada e os identificadores necessários devem permanecer inequívocos.

O Atlas autentica cada solicitação com um Bearer token de escopo de instalação estabelecido durante o provisionamento:

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

Seu ponto de extremidade deve:

  • Valide o Bearer token em cada solicitação e rejeite tokens inválidos ou expirados com 401 Unauthorized.

  • Trate o token como confidencial e armazene-o usando controles de acesso apropriados.

  • Use HTTPS com um certificado TLS de uma autoridade certificadora confiável. O Atlas não chamar pontos de extremidade por HTTP simples, e certificados autoassinados não são suportados em produção.

O corpo da solicitação contém os pares de chave-valor das credenciais a atualizar:

{ "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}
Campo
Obrigatório
Descrição

secrets

Obrigatório

Um array de pares de chave-valor de credenciais para atualizar.

secrets[].name

Obrigatório

O nome canônico da credencial, acordado com o Atlas durante a integração. Trate cada nome acordado como um contrato estável e com versão.

secrets[].value

Obrigatório

O valor das credenciais atualizar. Os valores podem conter caracteres especiais.

partial

Opcional

Quando true, atualize apenas as credenciais fornecidas e deixe as outras inalteradas. Quando omitido ou false, substitua o conjunto completo de credenciais.

Status
Significado
Comportamento esperado

200 OK ou 204 No Content

As credenciais foram aceitas e armazenadas com êxito.

Nenhum corpo de resposta é necessário.

400 Bad Request

O corpo da solicitação estava malformado.

Retorne uma mensagem de erro que não exponha valores de credenciais.

401 Unauthorized

A validação do token falhou.

Rejeite a solicitação.

404 Not Found

O identificador da organização ou do projeto não foi reconhecido.

Rejeite a solicitação.

5xx

Ocorreu um erro transitório no lado do servidor.

Retorne o erro para que o Atlas possa tentar novamente a solicitação.

O Atlas tenta novamente solicitações com falha (respostas 5xx ou tempos limite de rede) com backoff exponencial e um número limitado de tentativas.

Seu ponto de extremidade deve ser idempotente. Você pode receber solicitações duplicadas para o mesmo evento de rotação, e aplicar os mesmos valores de credenciais mais de uma vez deve produzir o mesmo resultado sem erro.

Além dos requisitos de autenticação acima, seu ponto de extremidade deve:

  • Credenciais criptografadas em repouso.

  • Evite que valores de credenciais apareçam em logs de aplicativos, logs de solicitação, mensagens de erro, telemetria ou arquivo de configuração em texto simples.

  • Restrinja o acesso às credenciais armazenadas aos sistemas e ao pessoal que as exigem.

  • Responda dentro de 10 segundos. Se a persistência das novas credenciais exigir em processamento em segundo plano, reconheça a solicitação de forma síncrona e conclua o em processamento de forma assíncrona.

  • Siga o processo de suporte do Atlas acordado se você suspeitar que seu token de acesso à instalação foi comprometido.

Antes que o Atlas possa enviar credenciais rotacionadas para sua integração, você deve:

  • Registre sua URL base de chamada de resposta durante o onboarding.

  • Estabeleça e armazene com segurança o token de acesso de instalação em ambos os lados.

  • Concorde e documente os nomes das credenciais e a semântica de atualização.

  • Implante seu ponto de extremidade para que ele possa ser acessado via HTTPS.

  • Confirme se o seu ponto de extremidade retorna os códigos de status esperados.

  • Teste manualmente uma rotação de ponta a ponta em um ambiente de não produção com uma instalação de não produção.

  • Testar entrega duplicada e comportamento de nova tentativa.