# Microsoft Power Platform Integration

Connect your Microsoft Power Platform environment to Capsule Security for complete visibility into your AI agents, workflows, and conversation history across Copilot Studio and Power Automate.

## Overview

img
This integration uses Microsoft Entra ID (Azure AD) authentication to sync:

- **Agents** - Copilots built in Copilot Studio
- **Tools** - Actions, plugins, Power Automate flows, and connectors
- **Knowledge Bases** - Data sources and knowledge articles attached to copilots
- **Conversations** - Chat sessions and conversation history
- **Audit** - Activity logs with action invocations and session tracking


## Prerequisites

Before you begin, ensure you have:

- An active **Microsoft Power Platform** environment with Copilot Studio and/or Power Automate
- An **Azure Entra ID** account with one of the following permissions:
  - **Environment Admin** role in Power Platform, OR
  - **System Administrator** role in the environment
- Access to the **Capsule Security** portal


For more information about Power Platform roles, see [Administering Power Platform](https://learn.microsoft.com/en-us/power-platform/admin/admin-documentation).

## Step 1: Configure the Integration in Capsule

Start the integration setup from the Capsule Security portal.

### Steps

1. Log in to the **Capsule Security** portal
2. Click **Integrations** in the left sidebar
3. Find the **Microsoft Power Platform** card and click **Set up Integration**
4. Click **Connect with Microsoft**
5. You'll be redirected to Microsoft's sign-in page


## Step 2: Authorize the Capsule Application

Grant Capsule the necessary permissions to access your Power Platform resources.

### Steps

1. Sign in with your Microsoft account that has the required permissions (see Prerequisites)
2. Review the permissions requested by the Capsule application
3. Click **Accept** to grant consent


### Permissions explained

Capsule requests the following permissions across Microsoft APIs. Most grant read-only access used for discovery and monitoring; a few setup permissions (application install, role assignment, and user provisioning) are required to install the Capsule application and maintain ongoing synchronization.

#### Dynamics CRM (1)

| Permission | Type | Description | Admin consent required | Justification |
|  --- | --- | --- | --- | --- |
| user_impersonation | Delegated | Access Common Data Service as organization users | No | Query Dataverse for environment data, copilots, flows, and users on behalf of the authorizing user |


#### Microsoft Graph (5)

| Permission | Type | Description | Admin consent required | Justification |
|  --- | --- | --- | --- | --- |
| AiEnterpriseInteraction.Read.All | Application | Read all AI enterprise interactions | Yes | Ingest enterprise AI interaction records for conversation and activity history |
| AuditLogsQuery.Read.All | Application | Read audit logs data from all services | Yes | Query the Purview unified audit log for Copilot Studio agent interactions, the only source of activity for Microsoft 365 Copilot (Lite) agents |
| Reports.Read.All | Application | Read all usage reports | Yes | Retrieve usage reports for adoption and activity insights |
| User.Read | Delegated | Sign in and read user profile | No | Sign in the authorizing user and read their profile during setup |
| User.Read.All | Application | Read all users' full profiles | Yes | Resolve owners and participants across discovered agents and flows |


#### Power Automate (4)

| Permission | Type | Description | Admin consent required | Justification |
|  --- | --- | --- | --- | --- |
| Activity.Read.All | Delegated | Allow the application to read activities | No | Read flow run activity for audit and run history |
| Approvals.Read.All | Delegated | Allow the application to read approvals | No | Read approval steps referenced by flows |
| Flows.Read.All | Delegated | Allow the application to read flows | No | Discover and read Power Automate flow definitions |
| Flows.Read.Plans | Delegated | Allow the application read only permission for flow | No | Read flow plan metadata |


#### Power Platform API (23)

| Permission | Type | Description | Admin consent required | Justification |
|  --- | --- | --- | --- | --- |
| AiFlows.Ai.Read | Delegated | AI related read operations on AI flow | No | Read AI-related configuration on AI (Copilot) flows |
| AiFlows.Connections.Read | Delegated | Read AI Flow Connection | No | Read connections used by AI flows |
| AiFlows.Runs.Read | Delegated | Read Copilot Flow Run | No | Read Copilot flow run history |
| AiFlows.Workflows.Read | Delegated | Read AI flow | No | Read AI flow definitions |
| AiTools.Prompt.Read | Delegated | Read AI Prompts | No | Read AI prompt definitions used by agents |
| Analytics.AdvisorRecommendations.Read | Delegated | Analytics.AdvisorRecommendations.Read | No | Read advisor recommendations for posture insights |
| AppManagement.ApplicationPackages.Install | Delegated | Install Application Packages | No | Install the Capsule application package into environments during setup |
| AppManagement.ApplicationPackages.Read | Delegated | Read Application Packages | No | Read installed application packages |
| Authorization.RoleAssignments.Read | Delegated | Power Platform role assignment reader | No | Read Power Platform role assignments |
| Authorization.RoleAssignments.Write | Delegated | Power Platform role assignment writer | No | Assign the role Capsule needs for ongoing data synchronization |
| Connectivity.Connections.Read | Delegated | Read Connections | No | Read connections attached to agents and flows |
| Connectivity.Connectors.Read | Delegated | Read Connectors | No | Read connector definitions used as agent tools |
| CopilotGovernance.Features.Read | Delegated | Read copilot governance features | No | Read Copilot governance features |
| CopilotGovernance.Settings.Read | Delegated | Read copilot governance settings | No | Read Copilot governance settings |
| CopilotStudio.MinimalBot.Read | Delegated | Read access for MinimalBot | No | Read Copilot Studio bot definitions |
| EnvironmentManagement.Environments.Read | Delegated | Read Environments | No | Discover Power Platform environments |
| EnvironmentManagement.Groups.Read | Delegated | Read Environment Groups | No | Read environment groups |
| EnvironmentManagement.Settings.Read | Delegated | Read Environment Management Settings | No | Read environment management settings |
| Governance.CrossTenantConnectionReports.Read | Delegated | Read Cross-Tenant Connection Reports | No | Read cross-tenant connection reports for data-egress visibility |
| PowerAutomate.Flows.Read | Delegated | Read Power Automate Flows | No | Read Power Automate flows |
| ResourceQuery.Resources.Read | Delegated | Read Resources | No | Query Power Platform resources during environment discovery |
| Security.Recommendations.Read | Delegated | Read Power Platform Security Information | No | Read Power Platform security recommendations |
| UserManagement.Users.Apply | Delegated | Apply user management operations | No | Provision the Capsule application user required for ongoing synchronization |


For more information about the consent experience, see [User and admin consent in Azure](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/user-admin-consent-overview).

## Step 3: Automatic Environment Discovery

After you grant consent, Capsule automatically configures the integration.

### What happens

- All Power Platform environments you have access to are discovered
- Copilot Studio bots and Power Automate flows within those environments are detected
- Required access permissions are configured automatically


No manual environment configuration is needed.

## Tenants That Restrict Copilot Studio with Security Groups

Some tenants limit who can use Copilot Studio to members of specific Microsoft Entra security groups, through the **Copilot Studio authors** tenant setting and related settings in the Power Platform admin center. Capsule installs into each environment by creating an application user for the Capsule Entra application and assigning it the System Administrator security role. When agent creation and management are scoped to security groups, that application user cannot be created until the Capsule application is a member of one of the groups.

### Symptoms

- Setup fails for every environment, or for a subset of them, even though the authorizing user is a Global Administrator and a System Administrator in the environment
- Adding the Capsule application manually in the Power Platform admin center (**Environments → your environment → Settings → Users + permissions → Application users → New app user**) fails the same way: the business unit list does not load, or the panel reports that the user is not a member of the organization


Each environment is provisioned independently, so a restriction that covers only some environments produces a partial install.

### Fix

1. In the [Microsoft 365 admin center](https://admin.microsoft.com), go to **Teams & groups → Active teams & groups** and create a dedicated security group for Capsule, for example `Capsule Security`. Do not reuse a group that drives Copilot Studio licensing or internal cross-charging: Capsule counts as an extra member there and skews those reports.
2. In the [Microsoft Entra admin center](https://entra.microsoft.com), add the **Capsule** enterprise application as a member of the group. The application appears under **Enterprise applications** once consent has been granted in Step 2 above.
3. In the [Power Platform admin center](https://admin.powerplatform.microsoft.com), go to **Manage → Tenant settings → Copilot Studio authors** and add the group.
4. Review any other Copilot Studio settings your tenant scopes to the same security groups, such as those controlling who can manage or publish agents, and add the Capsule group to each of them.
5. Return to the Capsule portal, open **Integrations → Microsoft Power Platform**, and run the setup again. Confirm that every environment you expect to monitor completes.


> **Note:** Environment-level security groups (**Manage → Environments → Edit → Security group**) do not block Capsule. Microsoft lets [application users run in any environment secured with a security group](https://learn.microsoft.com/en-us/power-platform/admin/control-user-access) without being a member, so no change is needed there.


## Synced Data Objects

Capsule ingests data from both Copilot Studio and Power Automate through a unified Power Platform integration. Both services share the same Entra ID app and are discovered automatically from each environment.

### Environments

During setup, Capsule uses the Microsoft Discovery Service to automatically detect all Power Platform environments accessible by the authorizing user. Each environment is registered with:

| Field | Description |
|  --- | --- |
| Name | The environment's friendly name in Power Platform |
| URL | The Dataverse instance URL |
| Environment Type | `Production`, `Sandbox`, or `Development` - classified from the Microsoft organization type |


All Copilot Studio agents, Power Automate flows, and users within each discovered environment are then synced automatically.

### Copilot Studio

#### Agents

Copilot Studio bots are ingested as **Agents** in Capsule. Each agent includes:

| Field | Description |
|  --- | --- |
| Name | The copilot name as defined in Copilot Studio |
| Type | `Conversational` |
| Accessibility | `Public`, `Tenant`, or `Limited` - derived from the bot's authentication mode and access control policy |
| Owner | The platform user who owns the copilot |


#### Agent Components

Each copilot's components are parsed and categorized:

| Component | Category | Description |
|  --- | --- | --- |
| **Model Agent** | Model | The foundational LLM powering the copilot (e.g., GPT-4o). Includes system instructions. |
| **Skills** | Tool | Actions and plugins the copilot can invoke, including connector-based tools |
| **Knowledge Sources** | Data Source | Knowledge bases attached to the copilot (e.g., Dataverse, SharePoint, external websites) |
| **File Attachments** | Data Source | Uploaded files used as data sources, categorized by MIME type |
| **Access Channels** | Access Channel | Deployment channels such as Copilot Chat and Microsoft Teams |
| **External Triggers** | Access Channel | External trigger integrations and their connection types |
| **Connected Agents** | Connected Agent | Other AI agent plugins linked to the copilot |


#### Conversation Transcripts

Capsule fetches conversation transcripts for each copilot and extracts individual activity events:

| Activity Type | Description |
|  --- | --- |
| Tool Invocation | A tool or action was called during the conversation |
| Error | An error occurred during the session |
| Session Started | A new conversation session was initiated |
| Agent Reasoning | The copilot's internal reasoning trace |
| Data Source Accessed | A knowledge source or file was accessed |
| Channel Accessed | An access channel interaction was recorded |
| User Message | A message sent by the user |
| Agent Message | A response generated by the copilot |


### Power Automate

#### Flows

Power Automate workflows are ingested as **Flows** in Capsule. Only modern automation flows (non-managed) are collected.

| Field | Description |
|  --- | --- |
| Name | The flow name as defined in Power Automate |
| Type | `DAG` (directed acyclic graph) |
| Status | `Active`, `Inactive`, or `Draft` - mapped from the workflow state code |
| Description | Optional flow description |


#### Flow Steps

Each flow's definition is parsed to extract its individual steps:

| Step Type | Description |
|  --- | --- |
| **Input** | Trigger steps that start the flow (e.g., scheduled, manual, event-based) |
| **Output** | Response steps that return data |
| **Condition** | Branching logic (`If`, `Switch`) |
| **Loop** | Iteration steps (`Foreach`, `Until`) |
| **Subflow** | Nested scopes or child workflow invocations |
| **External Call** | HTTP requests, API connections, and OpenAPI connector calls |
| **LLM** | AI Builder model invocations |
| **Data Operation** | Variable manipulation, data transformation (Compose, Filter, Select, etc.) |


#### Flow Step Connections

Connections between steps represent the execution graph:

| Connection Type | Description |
|  --- | --- |
| Data | Standard sequential execution |
| Conditional | Branch taken when a condition evaluates to true, or a specific switch case |
| Default | Fallback branch (else / default case) |
| Error | Branch taken when a preceding step fails |


#### Flow Runs

Capsule collects flow run history from the last 30 days:

| Field | Description |
|  --- | --- |
| Status | The run outcome (e.g., Succeeded, Failed, Cancelled) |
| Duration | Total run time |
| Trigger Type | What initiated the run |
| Error Code / Message | Error details if the run failed |


### Connectors

Power Platform connectors are captured across both Copilot Studio and Power Automate:

- **In Copilot Studio** - connector references are extracted from bot component actions. Each skill's connector type is identified from its connection reference (e.g., SharePoint, Outlook, Dataverse).
- **In Power Automate** - connector references are extracted from the flow definition. Each step that uses an API connection (OpenApiConnection, ApiConnection, Http) captures the connector's API ID, operation ID, and connection name.


Connectors provide visibility into which external services and data sources your AI agents and automation flows are interacting with.

### Power Apps

Capsule extends the Power Platform integration to cover Power Apps, providing visibility into canvas and model-driven apps within each discovered environment.

### Users

Platform users are collected from each Power Platform environment and deduplicated across Copilot Studio and Power Automate. Each user includes their name, email, and job title from the Dataverse system user record.

## After Setup

Once the integration is configured:

- Initial sync begins automatically
- First sync may take several minutes depending on data volume
- View synced agents in **Inventory → Agents**
- View conversations in **Observability → Filter Activity Type - Session**


## Troubleshooting

### Common Issues

1. **Consent failed or permissions error**
  - Verify you have Environment Admin or System Administrator permissions
  - Ensure your account has access to the Power Platform environments
2. **Setup fails for every environment, even as a Global Administrator**
  - Your tenant likely restricts Copilot Studio to security groups. See [Tenants That Restrict Copilot Studio with Security Groups](#tenants-that-restrict-copilot-studio-with-security-groups)
3. **No environments discovered**
  - Confirm Copilot Studio or Power Automate resources exist in your environments
  - Check that you have the necessary permissions to access these resources
4. **Sync not completing**
  - Allow several minutes for the initial sync to complete
  - Contact support if the issue persists


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your organization ID, integration status, and any error messages


For Power Platform-specific issues:

- [Power Platform documentation](https://learn.microsoft.com/en-us/power-platform/)
- [Copilot Studio documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/)
- [Power Automate documentation](https://learn.microsoft.com/en-us/power-automate/)
- [Microsoft support](https://support.microsoft.com/)