Saltar al contenido principal

Configuración de la protección de Copilot Studio

Esta es la guía orientada a tareas para activar la integración. Para comprender qué hace el control, qué datos observa y cómo se muestra una llamada de herramienta bloqueada al usuario, lea primero Microsoft Copilot Studio.

La configuración abarca tres lugares y el orden es importante:

  1. Beak AI Security — registre el llamador y elija cómo se aplican los veredictos.
  2. Microsoft Entra — cree una aplicación y una credencial federada.
  3. Centro de administración de Power Platform — designe a Beak, por entorno.

Nota: Realícelos en ese orden. Al guardar en Power Platform se llama al endpoint /validate de Beak y se produce un error si la aplicación de Entra aún no está registrada en Beak. El error que muestra Microsoft — There was a problem connecting to the protection provider — no indica ese motivo.

Antes de comenzar​

Necesita:

  • Beak — el permiso settings:update en AI Security y la integración habilitada para su entorno de Beak. Si el panel indica que la URL base pública no está configurada, un operador de Beak debe establecerla antes de que se puedan calcular las cadenas de incorporación.
  • Microsoft Entra — permiso para registrar una aplicación en el inquilino que llamará a Beak.
  • Power Platform — el rol de Administrador de Power Platform.
  • Al menos una política activa que se aplique al tráfico de API. Sin una, nunca se bloqueará nada. Consulte Elegir la política.

Paso 1 — Registrar el llamador en Beak​

Vaya a Integrations → Microsoft Copilot Studio (consulte Integrations) e ingrese dos valores del inquilino de Entra del cliente:

CampoDe dónde provieneQué hace Beak con él
Directory (tenant) IDEntra ID → OverviewSe compara con la notificación tid del token en cada solicitud
Application (client) IDEl registro de aplicación del Paso 2Se compara con la notificación azp / appid del token
NameElección propiaSolo referencia. No se usa para autorización

Ambos identificadores deben ser GUIDs; Beak los valida antes de guardar.

Seleccione Register and generate endpoint. Beak genera la URL del endpoint y muestra las cadenas que necesita el siguiente paso.

Nota: El registro comienza en modo observe. Cada llamada de herramienta se evalúa y los bloqueos potenciales se registran, pero nada se bloquea hasta que active la aplicación. Esto es deliberado — consulte Implementar en etapas.

Dado que la autenticación utiliza credenciales de identidad federadas, no hay ningún secreto en ningún momento — nada que almacenar, nada que rotar. El par de identificadores anterior es la lista de permitidos: un token de cualquier otro inquilino o aplicación se rechaza incluso con la URL correcta.

Paso 2 — Crear la aplicación de Entra​

Después del registro, el panel muestra cuatro valores. Cópielos; no los vuelva a escribir.

ValorUtilizado para
Endpoint linkTanto el asunto de la credencial federada como el Endpoint link de Power Platform
Federated credential — IssuerEl campo Issuer de la credencial en Entra
Federated credential — Explicit subject identifierEl campo Value de la credencial en Entra
PowerShell commandEl script de Microsoft, que realiza todo el paso de una sola vez

Se recomienda la ruta con script, ya que calcula los valores codificados por usted. Ejecute el comando que se muestra en el panel; tome nota del App ID que imprime y colóquelo en el campo Application (client) ID del Paso 1 si aún no lo ha hecho.

Si registra la aplicación manualmente, tome el Issuer y el subject del panel en lugar de ensamblarlos. El subject codifica el GUID del inquilino en orden de bytes .NET y la URL del endpoint como base64url sin relleno, y un único carácter incorrecto produce un valor que parece correcto y nunca coincide. Este detalle es responsable de la mayoría de las configuraciones fallidas.

Nota: La URL del endpoint es inmutable una vez que el cliente guarda en Power Platform. Está codificada en el asunto de la credencial federada y Entra la compara exactamente — por lo tanto, cambiarla posteriormente, incluso añadiendo una barra diagonal al final, rompe su configuración de forma silenciosa. Dado que el protocolo falla de forma abierta, sus agentes reanudan la invocación de herramientas sin control y sin que se muestre ningún error en Power Platform.

Paso 3 — Designar a Beak en Power Platform​

Los pasos completos se encuentran en Microsoft Copilot Studio. En resumen: Security → Threat detection → Additional threat detection, seleccione el entorno, Set up, marque la casilla de uso compartido de datos, ingrese el App ID y el Endpoint link, elija Set error behavior y Save.

Dos aspectos que debe trasladar a Beak:

  • Cualquiera que sea la opción seleccionada en Set error behavior. Beak no puede leerla, y su propio comportamiento ante tiempos de espera agotados debe coincidir — consulte Si Beak no puede responder a tiempo.
  • Confirmación de que Save se realizó correctamente. El panel de Beak muestra entonces Reached from Power Platform, que es la única señal de estado que el flujo de configuración del cliente proporciona a Beak.

La configuración es por entorno. No existe un interruptor a nivel de inquilino, y un entorno recién creado no está protegido hasta que alguien lo active para él.

Elegir la política​

Dos cosas diferentes, en dos lugares diferentes:

  • La política en sí se define en Policies — sus reglas, categorías y acciones. Nada relacionado con Copilot Studio vive allí.
  • Qué política rige las llamadas de herramienta de Copilot Studio es el campo Policy de este panel.

Deje el campo en All active policies for API traffic y se evaluará cada política elegible. Fije una y se convertirá en la única autoridad para esta superficie.

Solo las políticas del tipo api_guardrail o hybrid son elegibles, porque una llamada de herramienta es tráfico de tipo API. El menú desplegable ofrece solo esas, por lo que no se puede seleccionar por error una política no elegible.

Nota: Una política escrita para otra superficie — una política endpoint_dlp para la extensión del navegador, por ejemplo — es visible en la lista de Policies y parece una opción válida, pero aquí no resuelve nada. Si una política previamente fijada se vuelve no elegible, porque fue desactivada o su tipo cambió, el panel lo indica y Beak evalúa cada política elegible en su lugar. Las llamadas de herramienta aún se inspeccionan, pero no según la política indicada en el campo, por lo que debe corregirlo en lugar de dejarlo así.

Si el panel informa que ninguna política se aplica al tráfico de API, nada se bloqueará sin importar lo demás que esté configurado. Cree una antes de aplicar la política.

Limitar a entornos específicos​

Power Platform environments limita la integración a IDs de entorno con nombre — uno por línea o separados por comas. Déjelo vacío para cubrir todos ellos.

Una llamada de herramienta de cualquier otro entorno recibe la respuesta allow sin ser evaluada y se registra como fuera del alcance, de modo que "nunca revisado" permanece distinguible de "revisado y no se encontró nada".

Nota: El ID de entorno llega en el cuerpo de la solicitud, no en el token, por lo que es un filtro de alcance y nunca un límite de seguridad. La autorización corresponde al inquilino y la aplicación del Paso 1.

Cómo se aplican los veredictos​

ConfiguraciónPredeterminadoQué decide
EnforcementObserveSi un bloqueo calculado se aplica realmente
Redaction policiesBlock the tool callQué hacer cuando una política indica "permitir esto con valores sensibles eliminados"
If Beak cannot answer in timeAllow the tool to runQué responde Beak cuando la evaluación se aproxima a su límite de tiempo interno

Políticas de redacción​

La respuesta de este protocolo es un booleano, por lo que un argumento de herramienta puede bloquearse pero nunca reescribirse. Por tanto, una política de redacción no tiene representación fiel aquí.

El bloqueo es el valor predeterminado porque la alternativa envía la llamada de herramienta con el valor sensible intacto mientras la política sigue reportándose como activada — un control que parece funcionar y no lo hace. Permitir está disponible como una elección deliberada y registrada.

Si Beak no puede responder a tiempo​

Microsoft permite un segundo para todo el intercambio y trata una respuesta tardía como si no hubiera respuesta, momento en el que Set error behavior decide. Su valor predeterminado es ejecutar la herramienta.

Beak limita la evaluación a su propio presupuesto más corto y responde a esta configuración cuando se supera, porque una respuesta que Beak elige siempre es mejor que un tiempo de espera que sufre. Configúrelo para que coincida con el Set error behavior del cliente: si los dos no coinciden, un momento lento produce una respuesta mientras su configuración espera la otra.

Nota: Se aplica un tiempo de espera incluso mientras se observa. El modo observe existe para suprimir falsos positivos de la política, y un tiempo de espera agotado significa que no se alcanzó ninguna decisión de política — por lo que esta configuración tiene efecto de cualquier manera.

Implementar en etapas​

Copilot Studio no tiene su propio modo sombra, por lo que Beak proporciona uno y está activo de forma predeterminada. Úselo. El radio de impacto de un falso positivo aquí no es un banner de advertencia — es un agente que se niega a completar una tarea que el usuario solicitó.

  1. Observe, error behavior = Allow — Beak registra los bloqueos potenciales y no bloquea nada. Revise el Registro de Auditoria y ajuste la política hasta que los bloqueos potenciales sean los que respaldaría.
  2. Enforce, error behavior = Allow — Beak ahora bloquea. Una interrupción de Beak degrada a no protegido en lugar de roto.
  3. Enforce, error behavior = Block — solo una vez que esté satisfecho tanto con la tasa de bloqueo como con los tiempos de respuesta de Beak.

Cada etapa es una configuración por inquilino y puede cambiarse en cualquier momento.

Cambiar la configuración posteriormente​

Todo lo registrado en el Paso 1 permanece editable, y la URL del endpoint no se ve afectada por ninguno de estos cambios — por lo que el cliente nunca tiene que rehacer Entra o Power Platform para lo siguiente:

  • Directory (tenant) ID y Application (client) ID — corrija un error tipográfico o redirija el endpoint a una aplicación de Entra diferente.
  • Name, Policy, Power Platform environments y las tres configuraciones de veredicto.

Dos acciones son diferentes:

  • Disable integration impide que Beak forme una opinión. Copilot Studio sigue llamando al endpoint y, dado que el protocolo falla de forma abierta, las llamadas de herramienta se ejecutan sin control — sin que se muestre ningún error al cliente. Prefiera cambiar al modo observe si la intención es dejar de bloquear en lugar de dejar de proteger.
  • Rotate endpoint URL genera una nueva URL y rompe la configuración de Entra del cliente. Copilot Studio ya no puede obtener un token y sus agentes reanudan la invocación de herramientas sin control, de forma silenciosa. La recuperación requiere actualizar tanto el asunto de la credencial federada en Entra como el Endpoint link en Power Platform. Trátelo como un cambio coordinado con el cliente, no como una acción de mantenimiento.

Mejores prácticas​

  • Registre en Beak antes de que el cliente guarde en Power Platform. De lo contrario, el guardado falla y el error no explica por qué.
  • Copie las cadenas de incorporación; nunca las vuelva a escribir. Beak calcula el asunto codificado precisamente porque codificarlo manualmente suele producir un valor que parece correcto y nunca coincide.
  • Confirme que una llamada de herramienta real llega al Registro de Auditoria antes de dar la configuración por completada. Un guardado exitoso demuestra accesibilidad, no que los veredictos estén fluyendo.
  • Mantenga la configuración de tiempo de espera en consonancia con Set error behavior, y revísela si el cliente cambia la suya.
  • Añada la configuración del entorno a cualquier proceso que cree entornos de Power Platform. La cobertura se deteriora silenciosamente a medida que crece el parque, porque los nuevos entornos no están protegidos de forma predeterminada.
  • Permanezca en modo observe hasta que los bloqueos potenciales parezcan correctos. Pasar directamente a la aplicación pone un falso positivo frente al usuario como una tarea rechazada.

Páginas relacionadas​