Skip to main content

Configuring Copilot Studio protection

This is the task-oriented guide to switching the integration on. For what the control does, what data it sees, and what a blocked tool call looks like to a user, read Microsoft Copilot Studio first.

Configuration spans three places and the order matters:

  1. Beak AI Security — register the caller and choose how verdicts behave.
  2. Microsoft Entra — create an application and a federated credential.
  3. Power Platform admin center — nominate Beak, per environment.

Note: Do them in that order. Saving in Power Platform calls Beak's /validate endpoint and fails if the Entra application is not yet registered in Beak. The error Microsoft shows — There was a problem connecting to the protection provider — does not say that is the reason.

Before you start​

You need:

  • Beak — the settings:update permission in AI Security, and the integration enabled for your Beak environment. If the panel reports that the public base URL is not set, a Beak operator has to set it before the onboarding strings can be computed.
  • Microsoft Entra — permission to register an application in the tenant that will call Beak.
  • Power Platform — the Power Platform Administrator role.
  • At least one active policy that applies to API traffic. Without one, nothing will ever be blocked. See Choosing the policy.

Step 1 — Register the caller in Beak​

Go to Integrations → Microsoft Copilot Studio (see Integrations) and enter two values from the customer's Entra tenant:

FieldWhere it comes fromWhat Beak does with it
Directory (tenant) IDEntra ID → OverviewCompared against the token's tid claim on every request
Application (client) IDThe app registration from Step 2Compared against the token's azp / appid claim
NameYour own choiceReference only. Not used for authorisation

Both identifiers must be GUIDs; Beak validates them before saving.

Select Register and generate endpoint. Beak mints the endpoint URL and shows the strings the next step needs.

Note: Registration starts in observe mode. Every tool call is evaluated and would-be blocks are recorded, but nothing is blocked until you switch enforcement on. This is deliberate — see Roll out in stages.

Because authentication uses Federated Identity Credentials, there is no secret at any point — nothing to store, nothing to rotate. The pair of identifiers above is the allowlist: a token from any other tenant or application is rejected even against the correct URL.

Step 2 — Create the Entra application​

After registering, the panel shows four values. Copy them; do not retype them.

ValueUsed for
Endpoint linkBoth the federated credential subject and the Power Platform Endpoint link
Federated credential — IssuerThe credential's Issuer field in Entra
Federated credential — Explicit subject identifierThe credential's Value field in Entra
PowerShell commandMicrosoft's script, which does the whole step in one go

The scripted path is recommended, because it computes the encoded values for you. Run the command shown in the panel; note the App ID it prints, and put that App ID into the Application (client) ID field from Step 1 if you have not already.

If you register the application by hand, take the Issuer and subject from the panel rather than assembling them. The subject encodes the tenant GUID in .NET byte order and the endpoint URL as unpadded base64url, and a single wrong character produces a value that looks correct and never matches. That one detail accounts for most failed setups.

Note: The endpoint URL is immutable once the customer saves in Power Platform. It is encoded into the federated credential subject and Entra matches it exactly — so changing it later, even by a trailing slash, breaks their configuration silently. Because the protocol fails open, their agents then resume invoking tools unchecked with no error shown anywhere in Power Platform.

Step 3 — Nominate Beak in Power Platform​

Full steps are in Microsoft Copilot Studio. In brief: Security → Threat detection → Additional threat detection, select the environment, Set up, tick the data-sharing box, enter the App ID and the Endpoint link, choose Set error behavior, and Save.

Two things to carry back to Beak:

  • Whichever Set error behavior was chosen. Beak cannot read it, and its own timeout behaviour should agree — see If Beak cannot answer in time.
  • Confirmation that Save succeeded. The Beak panel then shows Reached from Power Platform, which is the only health signal the customer's setup flow gives Beak.

Configuration is per environment. There is no tenant-wide switch, and a newly created environment is not protected until someone turns this on for it.

Choosing the policy​

Two different things, in two different places:

  • The policy itself is defined under Policies — its rules, categories, and actions. Nothing about Copilot Studio lives there.
  • Which policy governs Copilot Studio tool calls is the Policy field in this panel.

Leave the field on All active policies for API traffic and every eligible policy is evaluated. Pin one and it becomes solely authoritative for this surface.

Only policies of kind api_guardrail or hybrid are eligible, because a tool call is API-shaped traffic. The dropdown offers only those, so an ineligible policy cannot be selected by mistake.

Note: A policy written for another surface — an endpoint_dlp policy for the browser extension, for example — is visible in the Policies list and looks like a valid choice, but it resolves to nothing here. If a previously pinned policy becomes ineligible, because it was deactivated or its kind changed, the panel says so and Beak evaluates every eligible policy instead. Tool calls are still inspected, but not by the policy named in the field, so fix it rather than leaving it.

If the panel reports that no policy applies to API traffic, nothing will be blocked no matter what else is configured. Create one before enforcing.

Narrowing to specific environments​

Power Platform environments limits the integration to named environment IDs — one per line, or comma-separated. Leave it empty to cover all of them.

A tool call from any other environment is answered allow without being evaluated, and recorded as out of scope, so "never looked at" stays distinguishable from "looked at and found nothing".

Note: The environment ID arrives in the request body, not in the token, so it is a scoping filter and never a security boundary. Authorisation is the tenant and application from Step 1.

How verdicts are applied​

SettingDefaultWhat it decides
EnforcementObserveWhether a computed block is actually applied
Redaction policiesBlock the tool callWhat to do when a policy says "allow this with sensitive values removed"
If Beak cannot answer in timeAllow the tool to runWhat Beak answers when evaluation approaches its internal deadline

Redaction policies​

This protocol's answer is a boolean, so a tool argument can be blocked but never rewritten. A redaction policy therefore has no faithful representation here.

Blocking is the default because the alternative sends the tool call with the sensitive value intact while the policy still reports as having fired — a control that appears to work and does not. Allowing is available as a deliberate, recorded choice.

If Beak cannot answer in time​

Microsoft allows one second for the whole exchange and treats a late answer as no answer, at which point Set error behavior decides. Its default is to run the tool.

Beak holds evaluation to its own shorter budget and answers this setting on breach, because an answer Beak chooses always beats a timeout it suffers. Set it to match the customer's Set error behavior: if the two disagree, a slow moment produces one answer while their configuration expects the other.

Note: A timeout is applied even while observing. Observe mode exists to suppress false positives from policy, and a timeout means no policy decision was reached at all — so this setting takes effect either way.

Roll out in stages​

Copilot Studio has no shadow mode of its own, so Beak provides one and it is on by default. Use it. The blast radius of a false positive here is not a warning banner — it is an agent refusing to complete a task the user asked for.

  1. Observe, error behavior = Allow — Beak records would-be blocks and blocks nothing. Review the Audit Log and tune the policy until the would-be blocks are ones you would stand behind.
  2. Enforce, error behavior = Allow — Beak now blocks. A Beak outage degrades to unprotected rather than broken.
  3. Enforce, error behavior = Block — only once you are satisfied with both the block rate and Beak's response times.

Each stage is a per-tenant setting and can be changed at any time.

Changing the configuration later​

Everything registered in Step 1 stays editable, and the endpoint URL is unaffected by any of it — so the customer never has to redo Entra or Power Platform for these:

  • Directory (tenant) ID and Application (client) ID — fix a typo, or re-point the endpoint at a different Entra application.
  • Name, Policy, Power Platform environments, and all three verdict settings.

Two actions are different:

  • Disable integration stops Beak forming an opinion. Copilot Studio keeps calling the endpoint and, because the protocol fails open, tool calls run unchecked — with no error shown to the customer. Prefer switching to observe mode if the intent is to stop blocking rather than to stop protecting.
  • Rotate endpoint URL mints a new URL and breaks the customer's Entra configuration. Copilot Studio can no longer obtain a token and their agents resume invoking tools unchecked, silently. Recovery needs both the federated credential subject in Entra and the Endpoint link in Power Platform updated. Treat it as a coordinated change with the customer, not a maintenance action.

Best Practices​

  • Register in Beak before the customer saves in Power Platform. The save fails otherwise, and the error does not explain why.
  • Copy the onboarding strings; never retype them. Beak computes the encoded subject precisely because hand-encoding it usually produces a value that looks right and never matches.
  • Confirm a real tool call reaches the Audit Log before calling the setup done. A successful Save proves reachability, not that verdicts are flowing.
  • Keep the timeout setting in step with Set error behavior, and revisit it if the customer changes theirs.
  • Add environment setup to whatever process creates Power Platform environments. Coverage decays quietly as the estate grows, because new environments are unprotected by default.
  • Stay in observe mode until the would-be blocks look right. Moving straight to enforcement puts a false positive in front of a user as a refused task.