Implementar el webhook de rotación de credenciales

Esta página trata sobre la rotación de las credenciales de un usuario de base de datos para un recurso aprovisionado a través de su integración. No guarda relación con la rotación de su token OAuth client_secret; para ello, consulte Almacenamiento de tokens y secretos en Integrar su aplicación con Atlas App Connections.

Cuando Atlas actualiza las credenciales de un usuario de base de datos asociado a un recurso aprovisionado mediante su integración, envía las credenciales actualizadas a su punto final de devolución de llamada HTTPS preregistrado. Atlas inicia la actualización de credenciales de forma independiente, generalmente en respuesta a un incidente de seguridad. La implementación de este punto final es opcional, pero recomendable, ya que permite que las aplicaciones de usuario final que dependen del usuario de base de datos aprovisionado reciban automáticamente las credenciales actualizadas. Este punto final no actualiza ni reemplaza la conexión OAuth entre su integración y Atlas.

Si no implementa el punto final, las aplicaciones de usuario final no recibirán automáticamente las credenciales de usuario de la base de datos actualizadas. Deberá actualizar las credenciales mediante otro mecanismo para que las aplicaciones puedan seguir autenticándose en la base de datos.

Requisitos del punto final

Expón un punto final utilizando la siguiente estructura:

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

Durante el proceso de incorporación, usted registra su URL base en Atlas. Los parámetros de ruta organizationId y projectId identifican la organización y el proyecto de Atlas asociados con la integración. Puede usar una estructura de URL diferente si así lo acuerda con Atlas durante la incorporación, pero la URL base registrada y los identificadores requeridos deben ser inequívocos.

Atlas autentica cada solicitud con un token de portador con ámbito de instalación establecido durante el aprovisionamiento:

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

Su punto final debe:

Valida el token de portador en cada solicitud y rechaza los tokens no válidos o caducados con 401 Unauthorized.
Trate el token como confidencial y almacénelo utilizando los controles de acceso adecuados.
Utilice HTTPS con un certificado TLS de una autoridad de certificación de confianza. Atlas no realiza llamadas a puntos finales mediante HTTP simple, y los certificados autofirmados no son compatibles en producción.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene los pares clave-valor de las credenciales que se deben actualizar:

{
  "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	Requerido	Descripción
`secrets`	Requerido	Una serie de pares clave-valor de credenciales para actualizar.
`secrets[].name`	Requerido	El nombre de credencial canónico, acordado con Atlas durante el proceso de incorporación. Considere cada nombre acordado como un contrato estable y versionado.
`secrets[].value`	Requerido	El valor de la credencial actualizado. Los valores pueden contener caracteres especiales.
`partial`	Opcional	Cuando se especifica `true`, solo se actualizan las credenciales proporcionadas y las demás permanecen sin cambios. Cuando se omite o se especifica `false`, se reemplaza el conjunto completo de credenciales.

Respuestas

Estado	Significado	Comportamiento esperado
`200 OK` or `204 No Content`	Las credenciales fueron aceptadas y almacenadas correctamente.	No se requiere cuerpo de respuesta.
`400 Bad Request`	El cuerpo de la solicitud estaba mal formado.	Devuelve un mensaje de error que no expone los valores de las credenciales.
`401 Unauthorized`	Falló la validación del token.	Rechazar la solicitud.
`404 Not Found`	El identificador de la organización o del proyecto no se reconoce.	Rechazar la solicitud.
`5xx`	Se produjo un error transitorio en el servidor.	Devuelve el error para que Atlas pueda volver a intentar la solicitud.

Reintento e Idempotencia

Atlas reintenta las solicitudes fallidas (respuestas 5xx o tiempos de espera de red) con retroceso exponencial y un número limitado de reintentos.

Su punto final debe ser idempotente. Puede recibir solicitudes duplicadas para el mismo evento de rotación, y aplicar los mismos valores de credenciales más de una vez debe producir el mismo resultado sin errores.

Requisitos de seguridad

Además de los requisitos de autenticación mencionados anteriormente, su punto final debe:

Cifra las credenciales en reposo.
Evita que los valores de las credenciales aparezcan en los registros de la aplicación, los registros de solicitudes, los mensajes de error, la telemetría o los archivos de configuración en texto plano.
Restrinja el acceso a las credenciales almacenadas a los sistemas y al personal que lo necesiten.
Responda en 10 segundos. Si el almacenamiento de las nuevas credenciales requiere procesamiento en segundo plano, confirme la solicitud de forma síncrona y complete el procesamiento de forma asíncrona.
Siga el proceso de soporte de Atlas acordado si sospecha que su token de acceso a la instalación se ha visto comprometido.

Lista de verificación de incorporación

Antes de que Atlas pueda enviar credenciales rotadas a su integración, debe:

Registre su URL base de devolución de llamada durante el proceso de incorporación.
Establezca y almacene de forma segura el token de acceso a la instalación en ambos lados.
Acordar y documentar los nombres de las credenciales y actualizar la semántica.
Implementa tu punto final de forma que sea accesible a través de HTTPS.
Confirme que su punto final devuelve los códigos de estado esperados.
Pruebe manualmente una rotación completa en un entorno que no sea de producción con una instalación que no sea de producción.
Prueba de entrega duplicada y comportamiento de reintento.

Recursos adicionales

Volver

Integra tu aplicación con Atlas App Connections.

Administrar el acceso a las aplicaciones