Integra tu aplicación con Atlas App Connections.

Conceptos clave

Acceso delegado

Tu aplicación actúa en nombre de un usuario de Atlas, no como ella misma. Los roles de organización y los permisos de proyecto del usuario determinan qué operaciones se ejecutan correctamente. Si el usuario no puede realizar una acción, tu aplicación tampoco podrá realizarla en su nombre.

Configuración de delegación de la organización

Cada organización de Atlas controla si se permiten las conexiones con aplicaciones de terceros. Incluso cuando un usuario autoriza su aplicación, las operaciones con una organización específica solo se realizarán correctamente si dicha organización tiene habilitadas las conexiones con aplicaciones de terceros. La delegación está deshabilitada de forma predeterminada para las organizaciones existentes. Dado que un usuario puede pertenecer a varias organizaciones, una sola autorización puede tener éxito en algunas de ellas y fallar en otras, dependiendo de la configuración de delegación de cada organización.

Clave de prueba para intercambio de códigos (PKCE)

Una extensión de seguridad para el flujo de código de autorización OAuth 2.1 que protege contra ataques de interceptación de código de autorización. PKCE requiere que el cliente genere un code_verifier aleatorio, derive un code_challenge a partir de él y envíe el desafío con la solicitud de autorización. Posteriormente, el cliente demuestra que originó la solicitud enviando el code_verifier original al intercambiar el código de autorización por tokens.

Descripción general del flujo

haga clic para ampliar

El proceso se desarrolla en tres etapas:

1. Su aplicación genera un verificador y un desafío de código PKCE, redirige al usuario al punto final de autorización de Atlas y el usuario aprueba el acceso en la pantalla de consentimiento.

2. Tu aplicación intercambia el código de autorización por un token de acceso y un token de actualización.

3. Tu aplicación utiliza el token de acceso para llamar a la API de administración de Atlas y el token de actualización para obtener nuevos tokens de acceso antes de que caduquen.

Paso 1: Solicitud de autorización

Dirija al usuario al punto final de autorización de Atlas (https://cloud.mongodb.com/oauth/authorize) con los siguientes parámetros. Usted controla cómo su aplicación presenta este punto final: una redirección dentro de la ventana existente, una nueva ventana del navegador o una ventana emergente.

Envíe únicamente los parámetros de la tabla anterior. El punto final de autorización no requiere un parámetro resource, así que omítalo en la solicitud de autorización, aunque la especificación OAuth 2.1 lo defina.

El siguiente ejemplo divide la URL en varias líneas para facilitar su lectura. Envíela como una sola línea:

https://cloud.mongodb.com/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &state=<RANDOM_STATE_VALUE>

Paso 2: Intercambio de tokens

Intercambia el código de autorización por tokens realizando una solicitud POST al punto final de tokens de Atlas:

POST https://authorize.mongodb.com/tokens

Ejemplo de solicitud:

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'code=<AUTHORIZATION_CODE>' \
  --data 'code_verifier=<CODE_VERIFIER>' \
  --data 'redirect_uri=https://yourapp.example.com/callback' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

La respuesta incluye:

Paso 3: Actualización de tokens de acceso

Los tokens de acceso tienen una duración limitada (actualmente 10 minutos). Antes de realizar llamadas a la API de administración de Atlas después de su vencimiento, intercambie su token de actualización por un nuevo token de acceso:

curl --request POST \
  --url https://authorize.mongodb.com/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=<YOUR_REFRESH_TOKEN>' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>'

La respuesta siempre devuelve un nuevo access_token y un nuevo refresh_token. El token de actualización anterior se invalida inmediatamente. Reemplace siempre ambos valores almacenados.

Configuración de permisos y delegación de la organización

Las operaciones contra una organización específica de Atlas solo tienen éxito cuando se cumplen las dos condiciones siguientes:

• La organización tiene habilitadas las conexiones con aplicaciones de terceros. Los propietarios de la organización configuran este ajuste en Organization Settings > App Connections. Para obtener más información sobre estos ajustes, consulte la descripción general de las conexiones con aplicaciones de Atlas.

• El usuario que autoriza la operación tiene el rol requerido para dicha operación dentro de esa organización o proyecto.

Si la delegación está deshabilitada para una organización después de que un usuario ya haya autorizado su aplicación, las llamadas a la API dirigidas a esa organización devuelven una respuesta 403 Forbidden.

Una autorización completada no garantiza que las llamadas a la API de administración de Atlas tengan éxito. Atlas evalúa la configuración de delegación de la organización y los roles del usuario en cada solicitud, no solo en el momento de la autorización, por lo que el flujo de OAuth y la pantalla de consentimiento pueden completarse correctamente aunque las solicitudes sigan devolviendo 403 Forbidden.

Verificación del acceso a la organización

Llama a GET /api/atlas/v2/orgs después de la autorización para determinar con qué organizaciones puede interactuar tu aplicación. Atlas solo devuelve las organizaciones que permiten conexiones de aplicaciones de terceros, por lo que una lista vacía significa que ninguna organización a la que pertenezca el usuario las ha habilitado.

Una lista vacía es un paso de configuración, no un error. Indique al usuario que solicite al propietario de la organización que habilite las conexiones de la aplicación para la organización y rediríjalo a la descripción general de las conexiones de la aplicación Atlas. Evite presentar la lista vacía como un error de autorización o autenticación, ya que las credenciales y el consentimiento del usuario son válidos.

Dado que el acceso delegado conlleva los permisos del usuario que lo autoriza, las operaciones de escritura también dependen de los roles de dicho usuario. Las operaciones de aprovisionamiento comunes requieren los siguientes roles:

• Para crear un proyecto, el usuario necesita el rol Organization Owner o Organization Project Creator.

• Para crear un clúster, el usuario necesita el rol Project Owner o Project Cluster Creator en el proyecto de destino.

Un usuario con el rol Organization Member puede leer los recursos a los que tiene acceso, pero las operaciones de escritura devuelven 403 Forbidden. Especifique el rol requerido en el manejo de errores para que el usuario pueda solicitar el rol correcto. Para obtener más información sobre todos los roles disponibles, consulte Roles de usuario de Atlas.

Cuando tu aplicación crea una organización en nombre de un usuario, esta aún no permite conexiones con aplicaciones de terceros. Habilitarlas es un paso manual: contacta con MongoDB para que la organización se incluya en la lista de aplicaciones permitidas. Hasta entonces, tu aplicación no podrá interactuar con la organización, aunque el usuario la haya autorizado.

Puntos finales bloqueados y filtrados

El acceso delegado llega a la mayoría de los puntos finales de la API de administración de Atlas, pero Atlas trata algunos puntos finales de manera diferente, independientemente de los permisos del usuario que autoriza el acceso.

Los puntos de conexión bloqueados devuelven una respuesta 403 Forbidden incluso cuando el usuario que autoriza la operación tiene un rol que normalmente la permitiría. Atlas bloquea los puntos de conexión de configuración de federación, que leen y modifican la configuración de federación e inicio de sesión único (SSO). La configuración del proveedor de identidad se comparte entre todas las organizaciones de una federación, por lo que el acceso delegado a ella podría exponer o interrumpir el funcionamiento de organizaciones que nunca autorizaron su aplicación.

Los puntos finales filtrados aceptan la llamada, pero restringen lo que pueden ver o modificar, según las organizaciones que hayan dado su consentimiento para las conexiones con aplicaciones de terceros. Tu aplicación solo puede acceder a esas organizaciones, y Atlas bloquea el acceso a los recursos de las organizaciones que no hayan dado su consentimiento.

Los puntos de acceso que abarcan varias organizaciones, como aquellos que muestran todas las organizaciones, proyectos o clústeres a los que el usuario puede acceder, solo devuelven las organizaciones que permiten conexiones con aplicaciones de terceros. Para las solicitudes que crean recursos, Atlas valida la organización de destino y rechaza la llamada si dicha organización no ha dado su consentimiento.

El propietario de la organización opta por participar desde Organization Settings > App Connections. Para obtener más información, consulte Permisos y configuración de delegación de la organización.

Con el tiempo, Atlas podrá bloquear o filtrar puntos finales adicionales para el acceso delegado.

Plano de control versus plano de datos

La API de administración de Atlas proporciona acceso al plano de control: permite crear, configurar y administrar recursos de Atlas como organizaciones, proyectos, clústeres y usuarios. No proporciona acceso directo al plano de datos (lectura o escritura de documentos en las bases de datos).

Para acceder a los datos en los clústeres de Atlas, obtenga la cadena de conexión del clúster a través de la API de administración de Atlas y conéctese utilizando un usuario de base de datos y el controlador o la consola de MongoDB. La cadena de conexión y las credenciales de la base de datos son independientes del token de portador de OAuth.

La revocación afecta de forma diferente al acceso al plano de control y al plano de datos. Consulte Efectos en el plano de datos.

Creación de usuarios de base de datos

Cree usuarios de base de datos a través del punto final de la API de administración de Atlas POST /api/atlas/v2/groups/{groupId}/databaseUsers utilizando el token de portador del usuario que autoriza. El usuario debe tener un rol de proyecto que le permita administrar usuarios de la base de datos.

Prácticas recomendadas

• No superes el límite de usuarios dela base de datos. Atlas impone un límite predeterminado de 100 usuarios por proyecto. Reutiliza los usuarios existentes siempre que sea posible, en lugar de crear uno nuevo para cada operación, y desactiva los usuarios que ya no necesites para evitar alcanzar el límite.

• Utilice roles con ámbito definido. Cree usuarios de base de datos con los roles mínimos necesarios para su caso de uso, en lugar de atlasAdmin.

• Deshabilita los usuarios cuando ya no sean necesarios. Cuando un usuario revoque el acceso a tu aplicación, elimina los usuarios de la base de datos que tu aplicación haya creado en su nombre. Atlas no elimina automáticamente los usuarios de la base de datos cuando se revoca el acceso.

• Rote las credenciales según un cronograma definido. Si su aplicación almacena contraseñas de usuarios de la base de datos, rótelas periódicamente utilizando el punto final PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username}.

Si Atlas rota las credenciales de un recurso aprovisionado por tu aplicación, como la contraseña de un usuario de base de datos, puede notificar a tu aplicación mediante un webhook opcional, en lugar de requerir que actualices las credenciales manualmente. Esto no está relacionado con la rotación de tu token OAuth client_secret; para ello, consulta Almacenamiento de tokens y secretos. Para implementar el webhook,consulta Implementar el webhook de rotación de credenciales.

Cifrado de credenciales en reposo

Su aplicación maneja varias categorías de información confidencial que debe estar cifrada en reposo:

• Cadenas de conexión. Las cadenas de conexión de Atlas contienen credenciales integradas o usuarios de bases de datos de referencia. Cifre las cadenas de conexión almacenadas mediante el Estándar de Cifrado Avanzado (AES)-256 o un método de cifrado equivalente. No almacene cadenas de conexión en texto plano en archivos de configuración, variables de entorno ni bases de datos.

• Tokens OAuth. Los tokens de actualización son credenciales de larga duración. Guárdelos en un administrador de secretos cifrado (por ejemplo, HashiCorp Vault, Amazon Web Services (AWS) Secrets Manager o Azure Key Vault). No almacene los tokens de actualización en la base de datos de su aplicación sin cifrarlos.

• Secretos de cliente. Tu client_secret equivale a una contraseña. Guárdala en un gestor de secretos y cámbiala si sospechas que ha sido expuesta.

Manejo de la cadena de conexión

Cuando su aplicación recupera cadenas de conexión de la API de administración de Atlas en nombre de un usuario:

• Siempre que sea posible, recupere las cadenas de conexión en el momento en que las necesite, en lugar de almacenarlas a largo plazo.

• Si su aplicación debe conservar una cadena de conexión, almacene solo lo necesario (por ejemplo, el nombre de host y el puerto) por separado de las credenciales.

• No registre las cadenas de conexión ni las incluya en los mensajes de error o en los rastreos de pila.

Almacenamiento de tokens y secretos

• No incluyas tokens ni secretos en el control de versiones.

• No registre tokens de acceso, tokens de actualización ni secretos de cliente. Si su aplicación registra las solicitudes de la API de administración de Atlas para depuración, oculte el encabezado Authorization.

• Limita el acceso a los secretos en tu gestor de secretos únicamente a los servicios que los requieran.

• Rote su client_secret periódicamente e inmediatamente si sospecha que se ha producido una vulneración de seguridad. Póngase en contacto con MongoDB para rotar el secreto asociado a su aplicación OAuth.

Desencadenantes de revocación

La revocación puede producirse mediante cualquiera de las siguientes acciones:

• El usuario revoca el acceso desde la interfaz de usuario de Atlas (User Settings > Connected Apps).

• El propietario de la organizaciónrestringe las conexiones de aplicaciones de terceros para toda la organización desde Organization Settings.

• El token de actualización caduca porque se ha alcanzado el tiempo máximo de validez del token de actualización de la organización o porque el token ha permanecido inactivo durante un período superior al límite de tiempo de inactividad.

• Tu aplicación revoca sus propios tokens cuando ya no necesita acceso.

Revocación de tokens de su aplicación

Cuando un usuario desconecta su aplicación de su propia interfaz, o su integración ya no necesita acceso, revoque los tokens en lugar de dejar que caduquen. Envíe una solicitud POST al punto final de revocación:

curl --request POST \
  --url https://authorize.mongodb.com/tokens/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user '<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>' \
  --data 'token=<REFRESH_OR_ACCESS_TOKEN>' \
  --data 'token_type_hint=refresh_token'

Revocar un token de actualización también invalida todos los tokens de acceso emitidos a partir de él. El punto final devuelve 200 OK independientemente de si el token era válido o no, por lo que una respuesta de éxito debe interpretarse como una confirmación de que el token ya no se puede usar, en lugar de como una prueba de que existió.

Efectos del plano de control

La rapidez con que la revocación surte efecto depende de quién revoque el acceso:

• El propietario de una organización restringe las conexiones de aplicaciones de terceros: la API de administración de Atlas comprueba la configuración de delegación de la organización en cada llamada, por lo que las solicitudes dirigidas a esa organización comienzan a devolver 403 Forbidden inmediatamente.

• Un usuario revoca el acceso a tu aplicación: el token de actualización se invalida inmediatamente, pero cualquier token de acceso ya emitido permanece válido hasta su vencimiento. Dado que los tokens de acceso tienen una duración limitada, tu aplicación puede seguir realizando llamadas exitosas durante un máximo de 10 minutos. Transcurrido ese tiempo, las llamadas devuelven 401 Unauthorized.

• MongoDB elimina su cliente OAuth: la revocación se propaga en cascada a través de todas las organizaciones a las que está conectada su aplicación, lo que tarda hasta 15 minutos en completarse.

Diseñe su aplicación para manejar las respuestas 401 y 403 de forma proactiva en lugar de depender de la propagación inmediata.

Efectos del plano de datos

Revocar el acceso a la API de administración de Atlas no finaliza inmediatamente las conexiones existentes al plano de datos. Su aplicación accede al plano de datos a través de los usuarios de la base de datos que creó, autenticándose con credenciales independientes de sus tokens OAuth. Revocar un token no invalida dichas credenciales. Las sesiones abiertas del controlador de MongoDB y las conexiones del grupo de conexiones permanecen activas hasta que se cierran mediante eventos normales del ciclo de vida de la conexión, como un tiempo de espera, un cierre por inactividad o un cierre explícito por parte de su aplicación.

Dado que la revocación no elimina los usuarios de la base de datos que creó su aplicación, elimínelos como parte del proceso de desconexión. Para obtener más información, consulte Ciclo de vida del usuario de la base de datos.

Error Scenarios

Respuestas de error de OAuth

Los errores de los puntos finales de autorización y token siguen la estructura estándar de OAuth:

{
  "error": "error_code",
  "error_description": "Human-readable explanation"
}

La siguiente tabla enumera los valores comunes de error:

Si se introduce el mismo código de autorización más de una vez, el servidor invalida todos los tokens asociados a esa autorización como medida de seguridad contra la interceptación del código. En tal caso, el usuario deberá volver a autorizarse desde el principio.

Clientes con discapacidad

MongoDB puede deshabilitar un cliente registrado, por ejemplo, durante la respuesta a incidentes o la baja de un socio. Mientras su cliente esté deshabilitado, el servidor se negará a iniciar nuevos flujos de autorización o a emitir nuevos tokens.

• El punto final de autorización redirige al usuario a su redirect_uri con error=access_denied y un error_description de client is disabled.

• El punto final del token devuelve 401 con invalid_client y la misma descripción. Esto se aplica a todos los tipos de concesión, incluido refresh_token, por lo que su aplicación no puede intercambiar tokens de actualización existentes mientras esté deshabilitada.

Los tokens de acceso emitidos antes de que se deshabilitara el cliente siguen siendo válidos hasta que caduquen. Deshabilitar un cliente bloquea los nuevos tokens en lugar de invalidar los existentes.

Un cliente deshabilitado no puede recuperarse por sí solo. Considere client is disabled como una condición terminal: detenga los reintentos, muestre el error y comuníquese con el equipo de socios de MongoDB para que vuelvan a habilitar el cliente.