Resumen
Las Aplicaciones OAuth permiten que aplicaciones externas se conecten de forma segura a Astra en nombre de los usuarios. En lugar de compartir credenciales, los usuarios inician sesión en Astra y otorgan explícitamente permiso a la aplicación. Esta guía explica cómo funcionan las Aplicaciones OAuth, cómo crearlas y administrarlas, y cuándo usar Aplicaciones OAuth en lugar de Claves de API.
Instrucciones
¿Qué es una Aplicación OAuth?
Una Aplicación OAuth es una aplicación que registras en Astra para permitir que los usuarios autoricen de forma segura el acceso a su Workspace.
Cuando creas una Aplicación OAuth, Astra genera:
Un ID de cliente, que identifica tu aplicación.
Un Secreto de cliente, que autentica tu aplicación.
Cuando un usuario conecta tu aplicación a Astra, se le redirige a Astra para que inicie sesión y revise los permisos que tu aplicación está solicitando. El acceso se concede solo después de que el usuario aprueba la solicitud.
Casos de uso recomendados
Las Aplicaciones OAuth son ideales para:
Productos SaaS que se conectan a la cuenta Astra de un cliente
Aplicaciones que requieren el consentimiento del usuario antes de acceder a los datos de Astra
Aplicaciones multi-inquilino que sirven a múltiples clientes o Workspaces
Integraciones que permiten a los usuarios conectar su cuenta Astra a través de un botón Conectar Astra
Cuándo no usar Aplicaciones OAuth
Las Aplicaciones OAuth pueden no ser la mejor opción para:
Scripts internos y automatización de backend
Integraciones de sistema a sistema sin interacción del usuario
Trabajos programados que se ejecutan bajo una única cuenta de organización
Para estos escenarios, las Claves de API suelen ser más sencillas de administrar.
Cómo crear una Aplicación OAuth
Para crear una Aplicación OAuth:
Inicia sesión en tu cuenta de Astra.
Ve a Cuenta > Aplicaciones OAuth.
Haz clic en Crear App.
Introduce los detalles requeridos:
Nombre de la app: El nombre que se muestra a los usuarios durante la autorización.
URI de redirección: La URL a la que se envía a los usuarios después de aprobar el acceso.
Ámbitos (Scopes): Los permisos que requiere tu aplicación.
Haz clic en Crear.
Importante: Guarda tu Secreto de cliente inmediatamente
Una vez creada la app, Astra muestra el Secreto de cliente solo una vez.
Copia y almacena el ID de cliente y el Secreto de cliente en un lugar seguro antes de salir de la página.
Posteriormente, Astra seguirá mostrando el ID de cliente, pero el Secreto de cliente completo no se podrá volver a ver.
Comprender las URIs de redirección
Una URI de redirección es el destino al que Astra envía a los usuarios después de que aprueban o deniegan el acceso a tu aplicación.
La URI de redirección proporcionada durante la autorización debe coincidir exactamente con una de las URIs de redirección registradas para la Aplicación OAuth. Si los valores no coinciden, la solicitud de autorización fallará.
Ejemplos de URIs de redirección
Entorno de producción:
https://your-app.com/oauth/callback
Entorno de desarrollo local:
http://localhost:8787/callback
Comprender los ámbitos (scopes)
Los ámbitos definen los permisos que tu aplicación puede solicitar a Astra.
Los usuarios pueden revisar estos permisos antes de decidir si autorizan tu aplicación.
Ámbitos disponibles
Ámbito | Descripción |
Todos | Acceso completo a todas las capacidades de la API pública disponibles |
Chat | Chatear con Agentes |
Agentes: Leer | Ver Agentes |
Agentes: Escribir | Crear, actualizar y administrar Agentes |
Contactos: Leer | Ver contactos |
Contactos: Escribir | Crear, actualizar y administrar contactos |
Conversaciones: Leer | Ver historial de conversaciones |
Conocimiento: Leer | Ver bases de conocimiento |
Conocimiento: Escribir | Crear, actualizar y administrar bases de conocimiento |
Webhooks: Administrar | Crear y administrar webhooks |
Análisis: Leer | Acceder a datos de análisis |
Mejor práctica al trabajar con aplicaciones OAuth
Solicita solo los permisos que necesitas
Solicita solo los ámbitos requeridos para la funcionalidad de tu aplicación.
Solicitar menos permisos ayuda a los usuarios a entender a qué puede acceder tu aplicación y mejora la confianza durante el proceso de autorización.
Cómo funciona el flujo de autorización (experiencia del usuario)
Cuando un usuario conecta tu Aplicación OAuth a Astra:
El usuario hace clic en Conectar Astra en tu aplicación.
El usuario es redirigido a la página de autorización de Astra.
Astra muestra el nombre de la aplicación y los permisos solicitados.
El usuario inicia sesión en Astra si aún no lo ha hecho.
El usuario hace clic en Autorizar o Denegar.
Si se aprueba, Astra redirige al usuario a la URI de redirección configurada.
Tu aplicación recibe las credenciales de autorización y puede acceder a Astra en nombre del usuario.
Qué significa esto para los usuarios
Los usuarios nunca necesitan compartir su contraseña de Astra con tu aplicación.
Cada usuario otorga acceso individualmente.
El acceso se aplica solo al Workspace que el usuario autoriza.
Los usuarios pueden revocar el acceso en cualquier momento desconectando la aplicación.
Administrar Aplicaciones OAuth
La página Aplicaciones OAuth muestra todas las aplicaciones registradas.
Puedes revisar las aplicaciones existentes y eliminar aquellas que ya no necesites.
Cómo eliminar una Aplicación OAuth
Para eliminar una Aplicación OAuth:
Inicia sesión en tu cuenta de Astra.
Abre Cuenta → Aplicaciones OAuth.
Localiza la aplicación que deseas eliminar.
Elimina la aplicación.
Confirma la acción.
¿Qué sucede cuando se elimina una aplicación?
Cuando se elimina una Aplicación OAuth:
Las nuevas solicitudes de autorización ya no se pueden iniciar.
Los tokens de acceso existentes se revocan.
Los usuarios conectados pierden el acceso inmediatamente.
Los usuarios deben volver a conectarse si se crea una aplicación de reemplazo.
Aplicaciones OAuth vs. Claves de API
¿Qué opción deberías elegir?
Utiliza la siguiente tabla para determinar qué método de autenticación es mejor para tu caso de uso.
| Aplicaciones OAuth | Claves de API |
Usuarios previstos | Clientes y usuarios finales | Sistemas internos y servicios de backend |
Requiere autorización del usuario | Sí | No |
Pantalla de consentimiento del usuario | Sí | No |
Soporta múltiples clientes | Sí | No |
Tipo de credencial | Tokens de acceso de corta duración que se pueden renovar | Claves de API de larga duración |
Caso de uso típico | Integración "Conecta tu cuenta Astra" | Sincronización de datos automatizada o flujo de trabajo interno |
Utiliza Aplicaciones OAuth cuando los usuarios necesiten conectar su cuenta Astra y otorgar permiso a tu aplicación.
Utiliza Claves de API cuando estés creando automatizaciones internas, servicios de backend o integraciones que operen sin interacción del usuario.