Onboarding

Onboarding a Copilot Studio agent

One connector serves every agent. Each agent gets its own connection carrying its own agent id and connection key. Onboarding touches the registry, Key Vault, Entra and Copilot Studio. It does not touch PingFederate's key configuration.

Who does what, in order

flowchart TD
  subgraph OP["Operator, repository"]
    O1["1. Registry entry: slug, agent id,<br/>groups, capabilities"]
    O3["2. Issue connection key,<br/>store SHA-256 fingerprint only"]
  end
  subgraph KV["Key Vault"]
    K4["3. Create the three keys in the vault,<br/>grant sign access per key"]
  end
  subgraph EN["Entra ID"]
    E5["4. Create the mirror agent identity<br/>under our blueprint, assign the Bridge API role"]
  end
  subgraph DEP["Operator, deployment"]
    O6["5. Generate the deployed registry<br/>with Key Vault names and mirror ids"]
    O7["6. Create the PingFederate client<br/>(terraform, no key material)"]
    O8["7. Roll out the three services"]
  end
  subgraph CS["Copilot Studio maker portal"]
    C9["8. Agent sign-in: Authenticate manually,<br/>Entra ID V2 with federated credentials"]
    C11["9. Create the connection with agent id and key,<br/>add the tool, publish, confirm Connected"]
  end
  O1 --> O3 --> K4 --> E5 --> O6 --> O7 --> O8 --> C9 --> C11

The order after the design review: keys are created in the vault, not in the repository.

The steps

The sequence below includes the changes from the design review. In the August deployment the runbook allowed key pairs to be generated in the repository, and the one mirror identity was created by hand.

Add a registry entry

The agent's Entra Agent ID object id comes from the agent's metadata in Copilot Studio. The registry entry gives it a slug, groups and capabilities. The registry changes by commit and review only. The entity id https://<bridge>/agents/<slug> is derived, never written.

Issue the connection key

The key is printed once. Only the SHA-256 of the secret is stored. Give the key to whoever creates the agent's connection. If it is lost, rotate it.

Create the keys in Key Vault

Three EC P-256 keys per agent, non-exportable. Sign access is granted per key, not per vault: the bridge's identity on fed_entity, the attestation service's identity on attester and instance.

Create the mirror identity

An agent identity under our blueprint, assigned the agent role on the Bridge API. It is created once. Tokens for it are obtained at request time.

Generate the deployed registry

A script writes the registry the services load: Key Vault key names, public keys read from the vault, and the real mirror ids. It is committed and never edited by hand.

Create the PingFederate client

Terraform creates one OAuth client per agent from the registry. The agent is deliberately left out of PingFederate's static attester file. Its absence is what sends PingFederate to the trust chain.

Roll out the services

The registry is part of each image. The gateway, the bridge and the attestation service are rebuilt and rolled out.

Wire the agent in Copilot Studio

Steps 8 and 9 in the diagram. Set the agent's sign-in to manual authentication with Entra ID V2 and federated credentials. Create the connection with the agent id and key, add the tool with the user token set to System.User.AccessToken, publish, and confirm the connection shows Connected.

Check it

Ask the agent "list my accounts" and confirm three things:

the gateway logs tier connection for the right slug;
the attestation service logs entra_token verification and a client_id of https://<bridge>/agents/<slug>;
PingFederate logs a successful attestation-based client authentication for that client_id, with the attester resolved from the chain.

Rotating a connection key

The registry holds a current fingerprint and an optional next fingerprint, so a rotation has no outage.

Rotate. Issue a new key. Its fingerprint is stored as the next fingerprint, and both keys work.
Update the connection. Deploy, then put the new key in the agent's Copilot Studio connection.
Promote. The new key becomes current and the old one stops working. Deploy again.

Handling a step-up in Copilot Studio

A payment over threshold, or an account opening that needs identity proofing, can outlast the connector's HTTP limit. The bridge waits up to 30 seconds. Past that it returns a pending state and a task id.

Task state	What the agent does
`auth-required`	Tell the customer to check their phone. Resume with `tasks/get` and the task id on the customer's next turn.
`completed`	Done. Return the result to the customer.
`failed`	Read the error. Denied, expired and mismatched approvals are final. If the approval arrived after the starting token expired, send the original request again and it permits without a new push.

Changed by the design review. The first version polled inside one agent flow. An agent flow must respond within 100 seconds, so the resume is now turn-based, and payment submission gets an idempotency key so a repeated request cannot submit twice.

What the review changes in onboarding

Keys are generated in the vault, as non-exportable EC-HSM keys. The repository key generation step is removed.
One sign-in app per agent, created with its federated credential by script, replaces the shared connector app.
A service account owns each connection, and connections are never shared.
The mirror identity is created by script and the whole sequence is run end to end as automation, which closes outcome O7.

NextReference