En esta guía aprenderás paso a paso a exponer tu propia API protegida por SSO dentro de Copilot Studio, de modo que cualquier usuario de tu organización pueda consumirla de forma segura y directa desde Microsoft Teams.
Resumen del escenario
Un desarrollador quiere que su copiloto llame a un servicio web interno que exige OAuth 2.0 y consentimiento de administrador, pero se topa con varios problemas:
- No dispone de los valores de registro (Client ID, Secret, URL de autorización/token).
- El conector personalizado da error de autenticación y la opción Agregar una API aparece deshabilitada.
- Los flujos creados en Power Automate no se muestran como acciones disponibles en Copilot Studio.
- No tiene claro cómo publicar el copiloto para todos los usuarios en Teams.
Beneficios de integrar tu API privada
Conectar una API empresarial eleva el valor del copiloto por múltiples razones:
- Conversaciones más ricas: los datos internos enriquecen las respuestas sin que el usuario abandone Teams.
- Seguridad centralizada: OAuth 2.0 delega la autenticación en Entra ID, evitando el almacenamiento local de credenciales.
- Reutilización: un único conector sirve a muchos copilot y flujos.
- Gobernanza: todas las llamadas quedan trazadas en Power Platform Admin Center, permitiendo auditoría y analítica.
Requisitos previos
- Rol Global Administrator o Application Administrator para registrar aplicaciones.
- Licencia Power Apps o Power Automate Premium, o un entorno Developer gratuito con Dataverse habilitado.
- Acceso al portal de Entra ID (antes Azure AD) y a Power Automate.
- Documentación de tu API (scopes, rutas REST, parámetros, esquema JSON de respuesta).
Guía paso a paso
| Paso | Qué hacer | Por qué ayuda |
|---|---|---|
| Registrar la aplicación en Entra ID | Pide al administrador que vaya a Entra ID › App registrations › New registration. Anota el Tenant ID y el Client ID. Configura como URI de redirección: https://global.consent.azure-apim.net/redirect. Añade permisos delegados requeridos por la API y otorga admin consent. | Permite que cualquier instancia del conector obtenga tokens sin que los usuarios introduzcan manualmente sus credenciales. |
| Crear el conector personalizado | En Power Automate › Custom connectors elige New custom connector › Create from blank. En la pestaña Security selecciona OAuth 2.0 (Entra ID) e introduce Tenant ID, Client ID, Client Secret y Resource/Audience (scope). Define las operaciones REST (GET/POST) y describe los parámetros y cuerpos de petición. Guarda, crea la conexión y prueba cada operación. | Centraliza la autenticación y evita duplicar código; Copilot Studio reutilizará esta conexión. |
| Convertir el flujo en Solution‑aware (opcional) | Mueve tu flujo a una Solution o créalo directamente allí. Si llamas a la API mediante el conector anterior, la autenticación irá incluida; si usas la acción HTTP clásica, añade un paso para obtener el token. Marca el flujo como Run‑only y habilita “Connections provided by run‑only user”. | Los flujos dentro de soluciones son los únicos que Copilot Studio muestra en la pestaña Acciones. |
| Conectar el complemento o flujo en Copilot Studio | Abre tu copiloto y ve a Acciones › Agregar. Busca tu conector o el flujo Solution‑aware. Selecciona la operación, asigna entradas (prompts) y salidas (variables). Guarda y prueba una conversación de ejemplo. | El copiloto podrá invocar tu API de forma dinámica durante la conversación. |
| Publicar y distribuir en Teams | En la esquina superior derecha pulsa Publicar › Teams y completa el asistente. Un administrador aprueba la aplicación en Teams admin center › Manage apps. Para visibilidad global, añade el copiloto a una directiva de configuración de Teams (Setup policies). Verifica que los usuarios dispongan de licencias Premium o de un plan pay‑as‑you‑go. | El copiloto aparecerá como una aplicación nativa en la barra lateral de Teams para todo el tenant. |
Detalles prácticos y buenas prácticas
Licencias y entornos
Cuando la opción Agregar una API se muestra en gris, suele deberse a que el entorno carece de Dataverse. Crea un entorno Developer gratuito (si tu organización lo permite) o asigna licencias Power Apps/Automate Premium. Si tu empresa opera con varios entornos, consolida los conectores compartidos en un entorno de producción para evitar duplicidades.
Seguridad y secretos
- Almacena el Client Secret en Azure Key Vault; dentro del conector selecciona Use Azure Key Vault para la referencia.
- Habilita certificados (X.509) en lugar de secretos si la política de seguridad lo exige.
- Concede permisos mínimos en API Permissions; utiliza least privilege.
- Renueva los secretos antes de su caducidad y notifica a los owners mediante alertas en Azure Monitor.
Pruebas y monitorización
Antes de exponer el copiloto a los usuarios finales:
- Desde la pestaña Test en el conector, ejecuta cada operación con ejemplos reales.
- En el flujo revisa el Run history para asegurarte de que los tokens se generan correctamente y de que la API responde con latencias aceptables.
- En Power Platform Admin Center › Analytics › Connectors monitoriza los picos y errores (errorCode, failureCount).
- Si el servicio es crítico, crea alertas en Azure Monitor para status codes ≥ 400 o latencias superiores a 2 segundos.
Gobernanza y ciclo de vida
- Documenta el proceso de consentimiento, los scopes concedidos y la fecha de expiración del secreto.
- Define responsables de mantenimiento (Owner y Backup Owner).
- Usa etiquetas (Environment variables) para apuntar a endpoints de Dev/QA/Prod sin editar el conector.
- Implementa una ventana de mantenimiento y comunica los cambios de versión del API.
Preguntas frecuentes
¿Puedo usar una API con autenticación básica?
Sí, pero perderías el inicio de sesión único. Si tu API no admite OAuth, crea el conector con tipo Basic Authentication o API Key y protege la contraseña en Key Vault.
¿Cómo paso parámetros dinámicos desde la conversación?
En Copilot Studio, al configurar la acción asigna variables conversacionales (por ejemplo {{$input.issueId}}) a los parámetros del conector. Marca los campos como Required para que el copiloto pregunte automáticamente al usuario si faltan datos.
Mi flujo no aparece en la lista de acciones; ¿qué hago?
Solo los flujos contenidos dentro de una Solution y con disparador Instant se muestran. Asegúrate además de compartir la solución con el propietario del copiloto o con toda la organización.
¿Cuántas operaciones de API puedo exponer?
Hasta 500 por conector. Sin embargo, la experiencia de conversación mejora si agrupas lógicamente las acciones clave y usas parámetros para variantes menores.
Conclusión
Integrar una API protegida por SSO en Copilot Studio no requiere código, pero sí entender la relación entre Entra ID, Power Automate y Teams. Al registrar la aplicación, crear un conector bien definido, alojar los secretos en Key Vault y distribuir el copiloto mediante políticas de Teams, obtendrás una experiencia fluida y governable. Sigue las mejores prácticas descritas para mantener la seguridad, el rendimiento y la trazabilidad a largo plazo.