Implemente o webhook de rotação de credenciais

Esta página aborda a rotação das credenciais de um utilizador de banco de dados para um recurso provisionado por meio da sua integração. Não está relacionado à rotação de seu OAuth client_secret; para isso, consulte Token e Armazenamento Secretoem Integrar seu aplicativo com Atlas App Connections.

Quando o Atlas gira 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 seu endpoint 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. A implementação desse endpoint é opcional, mas recomendada, pois permite que os aplicativos de usuário final que dependem do usuário de banco de dados provisionado recebam credenciais atualizadas automaticamente. O endpoint não atualiza nem substitui a conexão OAuth entre sua integração e o Atlas.

Se você não implementar o endpoint, esses aplicativos de usuário final não receberão credenciais de usuário 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.

Requisitos de endpoint

Exponha um endpoint usando a seguinte estrutura:

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

Você registra sua URL base no Atlas durante a integração. Os parâmetros de caminho organizationId e projectId identificam a organização Atlas e o projeto associados à integração. Você pode usar uma estrutura de URL diferente se concordar com ela 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 token de portador com escopo de instalação estabelecido durante o provisionamento:

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

Seu endpoint deve:

Valide o token do portador 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 de certificação confiável. O Atlas não chama endpoints por HTTP simples e certificados autoassinados não são suportados em produção.

Corpo da solicitação

O corpo da solicitação contém os pares de valores-chave da credencial a serem atualizados:

{
  "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	Uma array de pares de valores-chave de credenciais para atualizar.
`secrets[].name`	Obrigatório	O nome da credencial canônica, acordada com Atlas durante a integração. Trate cada nome aceito como um contrato estável e versionado.
`secrets[].value`	Obrigatório	O valor da credencial atualizado. 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.

Respostas

Status	Significado	Comportamento esperado
`200 OK` ou `204 No Content`	As credenciais foram aceitas e armazenadas com sucesso.	Nenhum corpo de resposta é necessário.
`400 Bad Request`	O corpo da solicitação estava malformado.	Retornar uma mensagem de erro que não expõe valores de credenciais.
`401 Unauthorized`	Falha na validação do token.	Rejeite a solicitação.
`404 Not Found`	O identificador da organização ou do projeto não é reconhecido.	Rejeite a solicitação.
`5xx`	Ocorreu um erro transitório do lado do servidor.	Devolva o erro para que o Atlas possa tentar novamente a solicitação.

Retry e Idempotência

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

Seu endpoint deve ser idempotente. Você pode receber solicitações duplicadas para o mesmo evento de rotação , e a aplicação dos mesmos valores de credenciais mais de uma vez deve produzir o mesmo resultado sem erros.

Requisitos de segurança

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

Criptografe credenciais em repouso.
Impeça que os valores de credenciais apareçam em registros de aplicação , registros de solicitações, mensagens de erro, telemetria ou arquivos de configuração de texto simples.
Restrinja o acesso às credenciais armazenadas aos sistemas e ao pessoal que o exijam.
Responda dentro de 10 segundos. Se a persistência das novas credenciais exigir processamento em segundo plano, confirme a solicitação de forma síncrona e conclua o processamento de forma assíncrona.
Siga o processo de suporte do Atlas combinado se suspeitar que seu token de acesso à instalação tenha sido comprometido.

Lista de verificação de integração

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

Registre seu URL base de chamada de resposta durante a integração.
Estabeleça e armazene com segurança o token de acesso da instalação em ambos os lados.
Acordar e documento os nomes das credenciais e atualizar a semântica.
Implemente seu endpoint para que ele seja acessível por HTTPS.
Confirme se o endpoint retorna os códigos de status esperados.
Teste manualmente uma rotação de ponta a ponta em um ambiente que não seja de produção com uma instalação que não seja de produção.
Teste o comportamento de entrega duplicada e novas tentativas.

Recursos adicionais

Voltar

Integre seu aplicativo com o Atlas App Connections

Gerencie o acesso ao aplicativo