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.

Integre su aplicación con Atlas App Connections

Atlas App Connections es la plataforma OAuth 2.1 de MongoDB Atlas que permite a su aplicación actuar en nombre de los usuarios de Atlas a través de acceso delegado por el usuario. Cuando un usuario autoriza su aplicación, su aplicación recibe un conjunto de tokens que puede utilizar para llamar a la Atlas Administration API con los mismos permisos que el usuario tiene en sus organizaciones de Atlas. Para obtener una descripción general de la plataforma y cómo las organizaciones gestionan las aplicaciones conectadas, consulte Descripción general de las conexiones de aplicaciones de Atlas.

Esta guía cubre la integración completa:

  • Iniciando el OAuth 2.1 Flujo de código de autorización con Clave de prueba para intercambio de código (PKCE)

  • Intercambiar códigos de autorización por tokens y actualizar tokens

  • Utilizar la Atlas Administration API con acceso delegado

  • Comprender el alcance y los límites del acceso delegado

  • Configuración del acceso a la red y administración de usuarios de base de datos

  • Manejo de revocaciones y errores

Acceso delegado
Su aplicación actúa en nombre de un Atlas user, no como ella misma. Los roles de la propia organización del usuario y los permisos del Proyecto determinan qué operaciones tienen éxito. Si el usuario no puede realizar una acción, su aplicación tampoco puede realizarla en su nombre.
Configuración de delegación de la organización
Cada organización de Atlas controla si se permiten las conexiones de aplicaciones de terceros. Incluso cuando un usuario autoriza su aplicación, las operaciones contra una organización específica tienen éxito solo si esa organización tiene habilitadas las conexiones de aplicaciones de terceros. La delegación está deshabilitada por defecto para las organizaciones existentes. Dado que un usuario puede pertenecer a varias organizaciones, una sola autorización puede ser correcta para algunas de las organizaciones del usuario y fallar para otras, en función de la configuración de delegación de cada organización.
Clave de prueba para intercambio de código (PKCE)
Una extensión de seguridad para OAuth 2.1 Flujo de código de autorización que protege contra ataques de intercepción de código de autorización. PKCE requiere que el cliente genere un code_verifier aleatorio, derive un code_challenge de él y envíe el desafío con la solicitud de autorización. El cliente demuestra entonces que originó la solicitud enviando el code_verifier original al intercambiar el código de autorización por tokens.

Antes de empezar, confirme que tiene:

  • Estado de socio de diseño aprobado.

  • Una aplicación OAuth registrada. MongoDB le proporciona un client_id durante la incorporación. Los clientes confidenciales (aplicaciones web del lado del servidor) también reciben un client_secret. Los clientes públicos (aplicaciones nativas y de una sola página) se autentican solo con el client_id y no reciben un secreto.

  • Una URI de redireccionamiento registrada con su aplicación OAuth. Las URI de redireccionamiento deben usar HTTPS excepto para las direcciones de bucle invertido (localhost, 127.0.0.1, ::1), que pueden usar HTTP en cualquier puerto. Los URI de redirección no deben contener fragmentos (#).

  • Familiaridad con el OAuth 2.1 Flujo de código de autorización y clave de prueba para el intercambio de código (PKCE).

Si necesita activos de marca de MongoDB para su integración, como el logotipo de MongoDB, consulte la página recursos de marca de MongoDB.

Desarrolle y lance su integración en producción. Atlas no proporciona entornos separados para socios.

Todos los puntos de conexión de OAuth y API utilizan dos URL base de producción:

Base
URL

Base de autorización ({OAUTH_BASE})

https://authorize.mongodb.com

Base de la nube ({CLOUD_BASE})

https://cloud.mongodb.com

A lo largo de esta guía, estos nombres representan las URL anteriores. Por ejemplo, el endpoint del token es {OAUTH_BASE}/tokens.

El extremo de autorización donde los usuarios inician sesión y conceden acceso está host en la base de la nube ({CLOUD_BASE}/oauth/authorize), mientras que el token y otros extremos de OAuth están host en la base de autorización ({OAUTH_BASE}). Esta división es intencional. La Atlas Administration API está alojada en la base de la nube ({CLOUD_BASE}/api/atlas).

Tip

Descubrir puntos finales automáticamente

Atlas publica metadatos del servidor OAuth 2.1 en {OAUTH_BASE}/.well-known/oauth-authorization-server. Muchas Librerías de clientes OAuth y SDK pueden leer este punto final para descubrir y configurar automáticamente los puntos finales de autorización, token y relacionados, lo que evita codificar las URL de los puntos finales.

Atlas aplicación Connections utiliza el OAuth 2.1 Flujo de código de autorización con Clave de prueba para el intercambio de código (PKCE). Este flujo requiere la interacción del usuario: el usuario inicia sesión en Atlas y aprueba los permisos que solicita su aplicación.

El flujo se desarrolla en tres pasos:

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

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

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

Dirija al usuario al punto de conexión 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 endpoint: un redirect dentro de la ventana existente, una nueva ventana del navegador o una ventana emergente.

Parameter
Requerido
Descripción

response_type

Requerido

Debe ser code.

client_id

Requerido

El ID de cliente de su aplicación, proporcionado por MongoDB durante la incorporación.

redirect_uri

Requerido

El URI HTTPS donde Atlas envía el código de autorización después de la aprobación del usuario. Debe coincidir con un URI registrado con su aplicación OAuth.

code_challenge

Requerido

El desafío de código PKCE derivado de su code_verifier. Generar una string aleatoria de 43a 128caracteres como el code_verifier, luego calcular BASE64URL(SHA256(code_verifier)).

code_challenge_method

Requerido

Debe ser S256. El método plain no se admite y se rechaza.

state

Requerido

Un valor opaco que su aplicación utiliza para mantener el estado entre la solicitud de autorización y la función de retorno. Utilice esto para proteger contra ataques de falsificación de solicitudes entre sitios (CSRF) y para restaurar el estado de la aplicación después del redireccionamiento.

Envíe solo los parámetros de la tabla anterior. El punto final de autorización no requiere un parámetro resource, por lo que debe omitirlo de la solicitud de autorización, aunque la especificación de OAuth 2.1 define uno.

El siguiente ejemplo divide la URL en varias líneas para mejorar la legibilidad. Envíalo 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>

Después de que el usuario inicia sesión en Atlas, verá una pantalla de consentimiento que enumera los permisos que su aplicación está solicitando:

  • Saber a qué recursos de Atlas tiene acceso

  • Actuar en su nombre en las organizaciones de Atlas

La pantalla de consentimiento también muestra el siguiente aviso al usuario:

Al autorizar una aplicación:

  • Le está permitiendo acceder y realizar acciones en sus recursos de MongoDB Atlas al igual que usted, utilizando los permisos de su cuenta.

  • Se puede revocar el acceso en cualquier momento.

Si el usuario hace clic en Authorize, Atlas redirige a su redirect_uri con una code de autorización, el valor state que proporcionó y un parámetro iss. Si el usuario hace clic en Decline, Atlas redirige con un parámetro error.

Su controlador de función de retorno debe:

  1. Verifique que state coincida con el valor que envió en la solicitud de autorización para evitar ataques CSRF.

  2. Verifique que iss coincida con la base de autorización (https://authorize.mongodb.com) para evitar ataques de suplantación del servidor de autorización.

  3. Compruebe si hay un parámetro error y gestione la denegación con elegancia antes de intentar usar el code.

Los códigos de autorización son de un solo uso y caducan en 10 minutos. Intercámbielos rápidamente.

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

POST https://authorize.mongodb.com/tokens
Body Parameter
Requerido
Descripción

grant_type

Requerido

Debe ser authorization_code.

code

Requerido

El código de autorización recibido de la redirección.

redirect_uri

Requerido

La misma URI de redireccionamiento utilizada en la solicitud de autorización.

code_verifier

Requerido

La string original del verificador de código PKCE.

client_id

Requerido

ID de cliente de su aplicación.

client_secret

Condicional

El secreto de cliente de su aplicación. Necesario solo para clientes confidenciales (aplicaciones web del lado del servidor). Los clientes públicos (aplicaciones nativas y de una sola página) se autentican solo con el client_id y omiten este parámetro.

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:

Campo
Tipo
Descripción

access_token

string

Bearer token para autenticar solicitudes de Atlas Administration API. De corta duración. Utilice el valor expires_in para determinar cuándo actualizar en lugar de codificar un tiempo de vida.

refresh_token

string

Token utilizado para obtener un nuevo token de acceso cuando el actual caduque. Almacene esto de forma segura.

token_type

string

Siempre Bearer.

expires_in

entero

Tiempo de vida del token de acceso en segundos. Actualmente 600 (10 minutos). Utilice este valor para determinar cuándo actualizar, en lugar de codificar rígidamente una vida útil, ya que el valor por defecto puede cambiar.

Los tokens de acceso tienen una vida útil corta (actualmente 10 minutos). Antes de realizar llamadas a la Atlas Administration API después de la caducidad, intercambie su refresh token por un nuevo access token:

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. Siempre reemplace ambos valores almacenados.

Importante

Los tokens de actualización caducan después de 7 días de inactividad (el tiempo de vida de inactividad). Independientemente de la actividad, los usuarios deben volver a autenticarse cada 30 días (la vida útil máxima). Organization Owner pueden configurar límites más estrictos. Cuando un token de actualización caduca, el usuario debe volver a autorizar su aplicación. Diseñe su aplicación para gestionar esto con elegancia solicitando al usuario que se reconecte.

Después de obtener un token de acceso, útícelo para realizar solicitudes de la Atlas Administration API incluyéndolo en el encabezado Authorization:

Authorization: Bearer <ACCESS_TOKEN>

Ejemplo de solicitud:

curl --request GET \ --url 'https://cloud.mongodb.com/api/atlas/v2/orgs' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --header 'Accept: application/vnd.atlas.2023-01-01+json'

Su aplicación actúa con los mismos permisos que tiene el usuario que autoriza en el momento de cada solicitud. Si los roles del usuario cambian después de la autorización, los permisos efectivos de su aplicación cambian en consecuencia.

Las operaciones contra una organización Atlas específica solo se realizan correctamente cuando se cumplen las dos condiciones siguientes:

  • La organización tiene habilitadas las conexiones de aplicaciones de terceros. Organization Owner configura esta configuración en Organization Settings > App Connections. Para obtener más información sobre estas configuraciones, consulte Descripción general de las conexiones de la aplicación Atlas.

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

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

Una autorización completada no garantiza que las llamadas a la Atlas Administration API tengan éxito. Atlas evalúa la configuración de delegación de la organización y los roles del usuario en cada solicitud, no una sola vez en el momento de la autorización, para que el flujo de OAuth y la pantalla de consentimiento puedan completarse sin problemas mientras que las solicitudes siguen devolviendo 403 Forbidden.

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

Una lista vacía es un paso de configurar, no un error. Indique al usuario que pida a un Organization Owner que habilite las conexiones de aplicaciones para la organización y diríjalos a Atlas App Connections Overview. Evite presentar la lista vacía como un error de autorización o autenticación, porque las credenciales y el consentimiento del usuario son válidos.

Dado que el acceso delegado implica los permisos del propio usuario autorizador, las operaciones de guardar también dependen de los roles de ese usuario. Las operaciones de provisionamineto comunes requieren los siguientes roles:

Un usuario que solo tiene asignado el rol de Organization Member puede leer los recursos a los que tiene acceso, pero las operaciones de guardar devuelven 403 Forbidden. Especifique el rol necesario en su manejo de errores para que el usuario pueda hacer la solicitud del rol correcto. Para aprender todos los roles disponibles, consulte Roles de usuario de Atlas.

Cuando su aplicación crea una organización en nombre de un usuario, la nueva organización aún no permite conexiones de aplicaciones de terceros. Habilitarlos es un paso manual: póngase en contacto con MongoDB para que la organización se incluya en la lista de permitidos. Hasta entonces, su aplicación no puede realizar acciones en la organización, aunque el usuario autorizó su aplicación.

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

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

Los puntos de conexión filtro aceptan llamar, pero restringen lo que puede ver o cambiar en función de qué organizaciones han optado por las conexiones de aplicaciones de terceros. Su aplicación solo puede acceder a esas organizaciones, y Atlas bloquea el acceso a los recursos de una organización que no ha optado por participar.

Los puntos de conexión que abarcan organizaciones, como los que enumeran todas las organizaciones, proyectos o clústeres a los que el usuario puede acceder, devuelven solo las organizaciones que permiten conexiones de aplicaciones de terceros. Para las solicitudes que crean recursos, Atlas valida la organización de destino y rechaza llamar cuando esa organización no ha aceptado participar.

Un Organization Owner opta por participar desde Organization Settings > App Connections. Para aprender más, consulte Permisos y configuración de delegación de la organización.

Atlas puede bloquear o filtrar puntos finales adicionales para acceso delegado con el tiempo.

La Atlas Administration API proporciona acceso al plano de control: puede crear, configurar y gestionar recursos de Atlas como organizaciones, proyectos, clústeres y usuarios. No proporciona acceso directo al plano de datos (lectura o escritura de documentos en sus bases de datos).

Para acceder a los datos en los clústeres de Atlas, recupere la cadena de conexión del clúster a través de Atlas Administration API y conéctese utilizando un usuario de base de datos y el driver o shell de MongoDB. La cadena de conexión y las credenciales de la base de datos están separadas del Bearer token de OAuth.

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

El acceso delegado vincula los tokens de su aplicación al usuario autorizador. Si el rol de ese usuario cambia, se da de baja al usuario o este no se vuelve a autenticar durante la vida útil del token de actualización, su aplicación pierde los permisos que necesita, aunque su integración en sí siga activa.

Si su integración necesita acceso continuo a la Atlas Administration API que no dependa de que un usuario específico permanezca autorizado, por ejemplo, cambiar el tamaño de los clústeres o las regiones de implementación de forma continua, cree una cuenta de servicio para la organización y el Proyecto del cliente en lugar de depender del acceso delegado para ese flujo de trabajo.

Una cuenta de servicio se autentica utilizando el OAuth 2.0 flujo de credenciales de cliente en lugar del flujo de código de autorización, por lo que no depende de la sesión activa de un usuario. Cada cuenta de servicio pertenece a una sola organización y puede conceder acceso a cualquier número de proyectos en esa organización. Los roles de Atlas limitan qué operaciones pueden autenticar los tokens de acceso de la cuenta de servicio, de la misma manera que los roles limitan a un usuario. Una cuenta de servicio no puede iniciar sesión en la Interfaz de Usuario de Atlas y, al igual que el acceso delegado, no proporciona acceso al plano de datos.

Para crear una cuenta de servicio para la organización de un cliente, consulte Descripción general de las cuentas de servicio y Crear una cuenta de servicio para una organización.

La mayoría de las integraciones de emparejar hacen provisionamineto de recursos de Atlas en nombre del usuario que autoriza. La siguiente secuencia cubre la ruta común desde una conexión autorizada hasta una cadena de conexión utilizable. Cada solicitud utiliza el Bearer token de Paso 2: Intercambio de tokens.

1

Llamar a GET /api/atlas/v2/orgs para enumerar las organizaciones a las que el usuario autorizado puede acceder, luego a GET /api/atlas/v2/orgs/{orgId}/groups para enumerar los proyectos dentro de una organización.

Solo las organizaciones que permiten conexiones de aplicaciones de terceros aparecen como objetivos utilizables. Para aprender más, consulta Permisos y configuración de delegación de la organización.

2

llamar a POST /api/atlas/v2/groups con el nombre del proyecto y el orgId de la organización de destino. Atlas valida el orgId en el cuerpo de la solicitud y devuelve 403 Forbidden cuando esa organización no permite conexiones de aplicaciones de terceros.

3

Llame a POST /api/atlas/v2/groups/{groupId}/clusters con el nombre del clúster, el tipo de clúster y la especificación de replicación. La creación del clúster es asincrónica. Sondee GET /api/atlas/v2/groups/{groupId}/clusters/{clusterName} hasta que el stateName del clúster sea IDLE.

4

Llamar a POST /api/atlas/v2/groups/{groupId}/databaseUsers para crear la identidad que su aplicación utiliza para el acceso al plano de datos. Para obtener orientación sobre el rol y el ciclo de vida, consulte Ciclo de vida del usuario de base de datos.

5

Agregue las direcciones IP salientes de su aplicación a la lista de acceso del Proyecto, o configure una opción de conectividad privada. Para aprender más información, consulte Configuración de red y lista de permitidos de IP.

6

Lea el campo connectionStrings del recurso del clúster, luego conéctese con un driver de MongoDB utilizando el usuario de base de datos que creó. La cadena de conexión y las credenciales de la base de datos están separadas del Bearer token de OAuth.

Para ver los esquemas completos de solicitud y respuesta de cada punto de conexión, consulte la Especificación de la Atlas Administration API.

La Atlas Administration API solo está disponible a través de internet pública. No está disponible a través del emparejamiento de nube privada virtual (VPC) o de nodos privados. Su aplicación debe poder acceder a cloud.mongodb.com en el puerto 443.

Nota

El acceso delegado a la Atlas Administration API omite cualquier restricción de la lista de acceso a la API del plano de control (lista de permitidos de IP de clave de API) que el cliente ha configurado. El acceso se rige por los permisos del usuario autorizador y las configuraciones de delegación de la organización, no por las restricciones de IP del plano de control. Para aprender más, consulte Limitaciones.

Para el acceso al plano de datos, el clúster de Atlas al que se está conectando puede tener configurada una lista de acceso IP. Las direcciones IP salientes de su aplicación deben agregarse a la lista de acceso IP del clúster, o debe configurar el emparejamiento de red o un nodo privado adecuado para su implementación.

Patrones de conectividad en la versión inicial:

  • Su aplicación es responsable de configurar la lista de permitidos de IP para el acceso al plano de datos. Esto no se gestiona automáticamente por la plataforma Atlas aplicación Connections.

  • Para cada clúster que su aplicación aprovisiona o acceda, agregue sus IP salientes o rangos de enrutamiento entre dominios sin clase (CIDR) a la lista de acceso IP del clúster utilizando el punto final POST /api/atlas/v2/groups/{groupId}/accessList.

  • Nunca exponga el plano de datos a Internet público. Siempre restrinja el acceso al plano de datos con listas de acceso IP o conexiones privadas, como el emparejamiento de red o los nodos privados.

Su aplicación puede necesitar crear y gestionar usuarios de base de datos al provisionamineto de clústeres de Atlas en nombre de los usuarios. Los siguientes patrones son compatibles en la versión inicial.

Cree usuarios de base de datos a través del punto final de la Atlas Administration API POST /api/atlas/v2/groups/{groupId}/databaseUsers utilizando el Bearer token del usuario autorizador. El usuario debe tener un rol de Proyecto que permita la gestión de usuarios de base de datos.

  • Manténgase dentro del límite de usuarios de base de datos. Atlas aplica un límite por defecto de 100 usuarios de base de datos por proyecto. Reutilice los usuarios de base de datos existentes siempre que sea posible en lugar de crear un nuevo usuario para cada operación, y desaprovisione los usuarios que ya no necesite para evitar alcanzar el límite.

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

  • Desaprovisione a los usuarios cuando ya no sean necesarios. Cuando un usuario revoca el acceso a su aplicación, borre los usuarios de base de datos que su aplicación creó en su nombre. Atlas no remueve automáticamente a los usuarios de base de datos cuando se revoca el acceso.

  • Rotar credenciales en un cronograma definido. Si su aplicación almacena contraseñas de usuario de base de datos, rótelas regularmente utilizando el punto final PATCH /api/atlas/v2/groups/{groupId}/databaseUsers/ {databaseName}/{username}.

Importante

Atlas no borra automáticamente los usuarios de base de datos u otros recursos que creó su aplicación cuando un usuario revoca el acceso. Su aplicación es responsable de limpiar los recursos que creó. La falta de desaprovisionamiento de los usuarios de base de datos deja las credenciales activas en la cuenta de Atlas del usuario después de que desconecten su aplicación. Para aprender más, consulte Limitaciones.

Si Atlas rota las credenciales de un recurso que su aplicación aprovisionó, como la contraseña de un usuario de base de datos, puede notificar a su aplicación a través de un webhook opcional en lugar de requerirle que actualice las credenciales usted mismo. Esto no está relacionado con la rotación de su OAuth client_secret; para ello, consulte Almacenamiento de tokens y secretos. Para implementar el webhook, consulte Implemente el webhook de rotación de credenciales.

En esta sección se describen los requisitos mínimos de seguridad para el manejo de credenciales e información confidencial en su integración. Estas prácticas reducen el radio de impacto de un incidente de seguridad y son obligatorias para los emparejar de diseño.

Su aplicación gestiona varias categorías de información confidencial que debe cifrarse en reposo:

  • cadena de conexión. Las cadenas de conexión de Atlas contienen credenciales incrustadas o hacen referencia a usuarios de base de datos. Cifre cualquier cadena de conexión almacenada utilizando el Estándar de cifrado avanzado (AES)-256 o un cifrado equivalente. No almacene cadenas de conexión en texto sin formato en archivos de configuración, almacenes de variables de entorno o bases de datos.

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

  • Secretos de cliente. Su client_secret equivale a una contraseña. Almacénelo en un administrador de secretos y rótelo si sospecha que se ha expuesto.

Tip

Preferir autenticación sin secretos

Atlas admite la autenticación sin secretos mediante PKCE, lo que remueve por completo la necesidad de gestionar un client_secret. Cuando su tipo de cliente lo permita, utilice la autenticación sin secretos como la opción más segura en lugar de provisionamineto y almacenar un secreto de cliente.

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

  • Recupere las cadenas de conexión cuando se necesiten, en lugar de almacenarlas a largo plazo, si es posible.

  • 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 registro cadenas de conexión ni las incluya en mensajes de error ni en rastros de pila.

  • No confirmes tokens o secretos al control de código fuente.

  • No haga un registro de tokens de acceso, tokens de actualización o secretos de cliente. Si su aplicación registra solicitudes de Atlas Administration API para depuración, oculte el encabezado Authorization.

  • Limite el acceso a los secretos en su administrador de secretos solo a los servicios que los requieran.

  • Gire su client_secret periódicamente e inmediatamente si se produce una sospecha de compromiso. Póngase en contacto con MongoDB para rotar el secreto asociado con su aplicación OAuth.

Comprender el comportamiento de revocación es importante para diseñar una integración resiliente. La revocación puede activarse de varias maneras y afecta de forma diferente al acceso al plano de control y al plano de datos.

La revocación puede producirse a través de cualquiera de las siguientes acciones:

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

  • Organization Owner restringe las conexiones de aplicaciones de terceros para toda la organización desde Organization Settings.

  • El token de actualización caduca porque se alcanzó la duración máxima del token de actualización de la organización o el token estuvo inactivo más allá del límite de duración de inactividad.

  • Su aplicación revoca sus propios tokens cuando ya no necesite tener acceso.

Importante

Los activadores anteriores revocan los tokens emitidos a través del flujo de OAuth. No afectan a una cuenta de servicio que haya creado para el acceso continuo (consulte Continuous Access with Service Accounts), ya que una cuenta de servicio no está vinculada a la autorización de ningún usuario individual.

No revoque ni borre las credenciales de la cuenta de servicio de un cliente únicamente porque un usuario individual revoque el acceso delegado o se le dé de baja de la organización. La cuenta de servicio representa la autorización continua de su integración, no el acceso individual de ese usuario.

Revoque las credenciales de la cuenta de servicio cuando el cliente borre o desconecte su integración de su cuenta, según lo que esa acción signifique en su producto.

Cuando un usuario desconecta su aplicación de su propia interfaz, o su integración de lo contrario ya no necesita acceso, revoque los tokens en lugar de dejar que caduquen. Envíe una solicitud POST al punto de conexión 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'
Parameter
Requerido
Descripción

token

Requerido

El token de acceso o el token de actualización que se va a revocar.

token_type_hint

Opcional

access_token o refresh_token. Ayuda al servidor a optimizar la búsqueda de tokens.

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 tanto, considere una respuesta de éxito como confirmación de que el token ya no se puede usar en lugar de como prueba de que existía.

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

  • Un Organization Owner restringe las conexiones de aplicaciones de terceros: la Atlas Administration API comprueba la configuración de delegación de la organización en cada llamada, por lo que las solicitudes a esa organización comienzan a devolver 403 Forbidden inmediatamente.

  • Un usuario revoca el acceso de su aplicación: el refresh token se invalida inmediatamente, pero cualquier access token ya emitido sigue siendo válido hasta que caduque. Dado que los tokens de acceso son de corta duración, su aplicación puede seguir realizando llamar exitosas hasta 10 minutos. Después de eso, llaman devuelven 401 Unauthorized.

  • MongoDB borrar su cliente OAuth: la revocación se propaga por 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 gestionar las respuestas 401 y 403 de forma proactiva en lugar de depender de la propagación inmediata.

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

Dado que la revocación no remueve los usuarios de base de datos que su aplicación creó, limpie estos como parte de su flujo de desconexión. Para aprender más información, consulta Ciclo de vida del usuario de base de datos.

Scenario
Estado
Acción recomendada

Token de acceso caducado

401

Utilice el token de actualización para obtener un nuevo token de acceso.

Token de acceso revocado

401

Solicitar al usuario que vuelva a autorizar. El token de actualización también se invalida.

Token de actualización caducado o revocado

400

Solicitar al usuario que vuelva a autorizar. Reinicie el flujo de código de autorización.

Credenciales de cliente no válidas

401

Verifique su client_id y client_secret.

Delegación deshabilitada para la organización

403

Informar al usuario que su organización de Atlas no permite conexiones de aplicaciones de terceros. Remítalos a su Organization Owner.

Punto final bloqueado

403

El punto final solicitado no está disponible a través de acceso delegado. Remueva la llamada de su integración.

El usuario carece del rol requerido

403

El usuario autorizador no tiene el rol requerido para esta operación. Informar al usuario y sugerirle que solicite el rol necesario a su Organization Owner.

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

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

La siguiente tabla enumera los valores comunes de error:

Código de error
Cuándo
Acción recomendada

invalid_request

Falta un parámetro obligatorio o está mal formado.

Compruebe los parámetros obligatorios y el formato.

invalid_client

Error de autenticación del cliente.

Verifique su client_id y client_secret.

invalid_grant

El código de autorización ha caducado o ya se ha utilizado, o el token de actualización no es válido.

Reinicie el flujo de código de autorización.

unauthorized_client

El cliente no está autorizado para este tipo de concesión.

Verifique que su registro de cliente incluya authorization_code.

access_denied

El usuario negó el consentimiento.

Informar al usuario. No reintentar automáticamente.

invalid_target

El parámetro resource no es válido o falta.

Verifique que el recurso esté registrado para su cliente.

unsupported_token_type

El valor token_type_hint es inválido.

Utilice access_token o refresh_token.

Si el mismo código de autorización se presenta más de una vez, el servidor invalida todos los tokens asociados a esa concesión como medida de seguridad contra la intercepción de código. Cuando esto ocurre, el usuario debe volver a autorizar desde el principio.

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 niega 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 de conexión de token devuelve 401 con invalid_client y la misma descripción. Esto se aplica a cada tipo 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 el cliente fuera deshabilitado siguen siendo válidos hasta que caduquen. Deshabilitar un cliente bloquea nuevos tokens en lugar de invalidar los existentes.

Un cliente deshabilitado no puede recuperarse por sí solo. Tratar client is disabled como una condición terminal: dejar de reintentar, mostrar el error y ponerse en contacto con el equipo de socios de MongoDB para que el cliente se vuelva a habilitar.

Califique esta página