Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Implementar el Webhook de rotación de credenciales

Esta página cubre 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 está relacionado con la rotación de su OAuth client_secret; para ello, consulte Almacenamiento de tokens y secretos en Integrar su aplicación con Atlas App Connections.

Cuando Atlas rota las credenciales de un usuario de base de datos asociado con un recurso aprovisionado a través de su integración, Atlas envía las credenciales actualizadas a su función de retorno HTTPS pre-registrado. Atlas inicia la rotación de credenciales de forma independiente, normalmente en respuesta a un incidente de seguridad. Implementar este punto final es opcional pero recomendado, porque permite que las aplicaciones de usuario final que dependen del usuario de base de datos aprovisionado reciban credenciales actualizadas automáticamente. El extremo no actualiza ni reemplaza la conexión OAuth entre su integración y Atlas.

Si no implementa el endpoint, esas aplicaciones de usuario final no reciben automáticamente las credenciales de usuario de base de datos rotadas. Debe actualizar las credenciales a través de otro mecanismo para que las aplicaciones puedan seguir autenticándose en la base de datos.

Exponga un punto final utilizando la siguiente estructura:

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

Usted registra su URL base con Atlas durante la incorporación. Los parámetros de ruta organizationId y projectId identifican la organización y el Proyecto de Atlas asociados con la integración. Puede utilizar una estructura de URL diferente si lo acuerda con Atlas durante la incorporación, pero la URL base registrada y los identificadores obligatorios deben seguir siendo inequívocos.

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

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

Su punto final debe:

  • Valide el Bearer token en cada solicitud y rechace los tokens no válidos o caducados con 401 Unauthorized.

  • Trate el token como confidencial y almacénelo utilizando controles de acceso adecuados.

  • Utilice HTTPS con un certificado TLS de una autoridad de certificación de confianza. Atlas no llama a puntos finales a través de HTTP sin cifrar, y los certificados autofirmados no se admiten en producción.

El cuerpo de la solicitud contiene los pares clave-valor de las credenciales para 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

Un arreglo de pares clave-valor de credenciales para actualizar.

secrets[].name

Requerido

El nombre canónico de las credenciales, acordado con Atlas durante la incorporación. Trate cada nombre acordado como un contrato estable y versionado.

secrets[].value

Requerido

El valor de credenciales actualizado. Los valores pueden contener caracteres especiales.

partial

Opcional

Cuando true, actualice solo las credenciales proporcionadas y deje las demás sin cambios. Cuando se omite o false, reemplace el conjunto completo de credenciales.

Estado
Significado
Comportamiento esperado

200 OK or 204 No Content

Las credenciales se aceptaron y almacenaron correctamente.

No se requiere cuerpo de respuesta.

400 Bad Request

El cuerpo de la solicitud estaba malformado.

Devuelva un mensaje de error que no exponga los valores de las credenciales.

401 Unauthorized

La validación del token falló.

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.

Devuelva el error para que Atlas pueda reintentar la solicitud.

Atlas reintenta las solicitudes fallidas (5xx respuestas 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.

Además de los requisitos de autenticación anteriores, su punto de conexión debe:

  • Cifrar credenciales en reposo.

  • Evitar que los valores de credenciales aparezcan en los registros de aplicación, los registros de solicitud, los mensajes de error, la telemetría o los archivos de configuración de texto sin formato.

  • Restringir el acceso a las credenciales almacenadas a los sistemas y al personal que lo necesiten.

  • Responder en 10 segundos. Si la persistencia de las nuevas credenciales requiere procesamiento en segundo plano, reconozca 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 de instalación se ha visto comprometido.

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

  • Registre su URL base de la función de retorno durante la incorporación.

  • Establezca y almacene de forma segura el token de acceso de instalación en ambos lados.

  • Acordar y documentar los nombres de las credenciales y la semántica de actualizar.

  • Implemente su punto final para 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 de extremo a extremo en un entorno de no producción con una instalación de no producción.

  • Probar la entrega duplicada y el comportamiento de reintento.