--- title: Microsoft Copilot Studio connector description: "Reference for the Microsoft Copilot Studio connector: discover Copilot Studio agents, tools, knowledge sources, owners, and identity bindings." component: openicf page_id: openicf:connector-reference:microsoft-copilot-studio canonical_url: https://docs.pingidentity.com/openicf/connector-reference/microsoft-copilot-studio.html llms_txt: https://docs.pingidentity.com/openicf/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md section_ids: microsoft_copilot_studio_requirements: Microsoft Copilot Studio requirements offline_inventory_job_permissions: Offline inventory job permissions install_the_microsoft_copilot_studio_connector: Install the Microsoft Copilot Studio connector configure_the_microsoft_copilot_studio_connector: Configure the Microsoft Copilot Studio connector connection_details: Connection details example_microsoft_copilot_studio_configuration: Example Microsoft Copilot Studio configuration test_the_microsoft_copilot_studio_connector: Test the Microsoft Copilot Studio connector microsoft_copilot_studio_remote_connector: Microsoft Copilot Studio remote connector implementation_specifics: Implementation specifics collection_architecture: Collection architecture live_data: Live data inventory_data: Inventory data inventory_behavior: Inventory behavior use_the_microsoft_copilot_studio_connector: Use the Microsoft Copilot Studio connector account_attributes: __ACCOUNT__ attributes agenttool_attributes: agentTool attributes agentknowledgebase_attributes: agentKnowledgeBase attributes agentidentitybinding_attributes: agentIdentityBinding attributes troubleshooting: Troubleshooting connector_initializes_but_test_fails: Connector initializes but test fails agents_reconcile_but_expected_agents_are_missing: Agents reconcile but expected agents are missing agents_reconcile_but_toolids_or_agenttool_is_empty: Agents reconcile but toolIds or agentTool is empty agents_reconcile_but_knowledgebaseids_or_agentknowledgebase_is_empty: Agents reconcile but knowledgeBaseIds or agentKnowledgeBase is empty agentidentitybinding_returns_no_records: agentIdentityBinding returns no records connected_agent_target_ids_are_missing: Connected-agent target IDs are missing implemented-interfaces-org-forgerock-openicf-connectors-m365copilot-M365CopilotConnector-1.5.20.33: OpenICF interfaces implemented by the Microsoft Copilot Studio connector config-properties-org-forgerock-openicf-connectors-m365copilot-M365CopilotConnector-1.5.20.33: Microsoft Copilot Studio connector configuration basic-configuration-properties-org-forgerock-openicf-connectors-m365copilot-M365CopilotConnector-1.5.20.33: Basic configuration properties --- # Microsoft Copilot Studio connector Microsoft Copilot Studio is Microsoft's low-code platform for building and deploying AI agents. The Microsoft Copilot Studio connector is a read-only connector that discovers Copilot Studio agents and governance-relevant objects including tools, knowledge sources, connected-agent references, owners, and identity bindings. Contact your Ping Identity Customer Success Outcome Manager (CSOM) or Account Executive to obtain this connector. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Retrieval of `agentIdentityBinding` is enabled through an offline inventory mechanism that requires an Agent Governance license. Contact your CSOM for details. | ## Microsoft Copilot Studio requirements Before you can use the connector, you must register an application with Azure. You need a Microsoft Azure subscription to complete this procedure: 1. Sign on to the [Azure portal](https://portal.azure.com/) as an administrative user. 2. Select App registrations under Azure services. 3. On the Register an application page, enter a name for the application, for example `FR-Connector`. 4. Select the supported account types and enter a Redirect URI. The redirect URI is the IDM or Advanced Identity Cloud URI that Azure should redirect to after successful authentication, for example `https://idm.example.com:8443/`. 5. On the new registration page, make a note of the Application (client) ID and the Directory (tenant) ID. You'll need these to configure the connector. 6. Generate a client secret: 1. Select Certificates & secrets > New client secret. 2. Enter a description, select an expiration date, and click Add. 3. Copy the client secret value. 7. Set the API permissions: | Service | Permission | | ----------------- | --------------------------------- | | Dynamics CRM | `mcp.tools`, `user_impersonation` | | Microsoft Graph | `user.read` | | PowerApps Service | `user` | 8. Navigate to the Power Platform admin center. 9. Navigate to Environments and select your environment. 10. Select Settings > Application Users. 11. Add the app you created and grant it the System Administrator role. ### Offline inventory job permissions The `agentIdentityBinding` object class depends on a separate offline inventory job. That job needs the following permissions: | Permission area | Required access | | ------------------ | -------------------------------------------------------------------------- | | Dataverse | Access to read Copilot Studio bot records and `authorizedsecuritygroupids` | | Microsoft Graph | `GroupMember.Read.All` or equivalent to resolve group details | | Azure Blob Storage | Permission to write the identity binding inventory JSON | The connector reads the inventory JSON using either a SAS URL or a local file path. When using a SAS URL, the connector performs an unauthenticated HTTP GET and doesn't send an `Authorization` header. ## Install the Microsoft Copilot Studio connector | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To check for an Advanced Identity Cloud application for this connector, refer to:- [Application management](https://docs.pingidentity.com/pingoneaic/latest/app-management/applications.html) - [App catalog](https://docs.pingidentity.com/pingoneaic/latest/app-management/app-catalog.html) | To obtain the connector `.jar` file, contact your Ping Identity Customer Success Outcome Manager (CSOM) or Account Executive. * If you're running the connector locally, place the `.jar` file in the `/path/to/openidm/connectors` directory. * If you're using a remote connector server (RCS), place the `.jar` file in the `/path/to/openicf/connectors` directory on the RCS. ## Configure the Microsoft Copilot Studio connector Create a connector configuration using the IDM admin UI: 1. From the navigation bar, click Configure > Connectors. 2. On the Connectors page, click New Connector. 3. On the New Connector page, type a Connector Name. 4. From the Connector Type list, select Microsoft Copilot Studio Connector - 1.5.20.33. 5. Complete the Base Connector Details and any applicable Additional Options. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------- | | | For a list of all configuration properties, refer to [Microsoft Copilot Studio Connector Configuration](#m365copilot-config-prop-ezLink). | 6. Click Save. When your connector is configured correctly, the connector displays as Active in the admin UI. Refer to [this procedure](configure-connector.html#connector-wiz-REST) to create a connector configuration over REST. ### Connection details The Microsoft Copilot Studio connector uses the following configuration properties: | Property | Type | Required | Default | Description | | ---------------------------- | ------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `tenantId` | String | Yes | None | Microsoft Entra tenant ID. | | `environmentUrl` | String | Yes | None | Dataverse environment URL, for example `https://org.example.crm.dynamics.com`. Don't include `/api/data/v9.2`; the connector appends it. | | `clientId` | String | Yes | None | Microsoft Entra application client ID. | | `clientSecret` | GuardedString | Yes | None | Microsoft Entra application client secret. | | `toolsInventoryUrl` | String | No | None | SAS URL for the identity binding inventory JSON. Used when `identityBindingScanEnabled=true`. | | `toolsInventoryFilePath` | String | No | None | Local path to the identity binding inventory JSON. Intended for development or test use. | | `httpTimeoutSeconds` | Integer | No | `30` | HTTP connect, socket, and connection request timeout. | | `logPayloads` | Boolean | No | `false` | Logs raw API payloads. Use only for development or troubleshooting. | | `identityBindingScanEnabled` | Boolean | No | `false` | Enables `agentIdentityBinding` reconciliation. Inventory isn't fetched when this is `false`. | | `includeUnpublishedAgents` | Boolean | No | `false` | Includes agents where `publishedon` is null. By default, unpublished agents are excluded. | ### Example Microsoft Copilot Studio configuration ```json { "connectorRef": { "bundleName": "org.forgerock.openicf.connectors.m365copilot-connector", "bundleVersion": "[1.5.0.0,1.6.0.0)", "connectorName": "org.forgerock.openicf.connectors.m365copilot.M365CopilotConnector" }, "configurationProperties": { "tenantId": "00000000-0000-0000-0000-000000000000", "environmentUrl": "https://org.example.crm.dynamics.com", "clientId": "11111111-1111-1111-1111-111111111111", "clientSecret": { "$crypto": { "type": "x-simple-encryption", "value": { "cipher": "...", "data": "...", "iv": "...", "key": "openidm-sym-default" } } }, "toolsInventoryUrl": "https://storageaccount.blob.core.windows.net/tools-inventory/copilot-studio/identity-bindings.json?", "httpTimeoutSeconds": 30, "logPayloads": false, "identityBindingScanEnabled": true, "includeUnpublishedAgents": false } } ``` ### Test the Microsoft Copilot Studio connector Test that the configuration is correct by running the following command: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system/m365copilot?_action=test" { "name": "m365copilot", "enabled": true, "config": "config/provisioner.openicf/m365copilot", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.m365copilot-connector", "connectorName": "org.forgerock.openicf.connectors.m365copilot.M365CopilotConnector" }, "displayName": "Microsoft Copilot Studio Connector", "objectTypes": [ "__ACCOUNT__", "__ALL__" ], "ok": true } ``` If the command returns `"ok": true`, your connector has been configured correctly and can authenticate to the Dataverse environment. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | `TestOp` validates connectivity by calling the Dataverse `bots` endpoint (`GET /api/data/v9.2/bots?$top=1&$select=botid`). It doesn't prove that the identity binding inventory exists. Verify the inventory source separately when validating `agentIdentityBinding`. | ### Microsoft Copilot Studio remote connector If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Microsoft Copilot Studio connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM. Refer to [Remote connectors](remote-connector.html) for configuring the Microsoft Copilot Studio remote connector. ## Implementation specifics ### Collection architecture The Microsoft Copilot Studio connector uses a split collection model. Live collection runs inside the Java connector during reconciliation, calling the Dataverse Web API to list Copilot Studio agents and bot components. Bot components are classified into tools, knowledge sources, topics, and connected-agent references. Offline collection is handled by a companion inventory job. That job reads Copilot Studio group authorization data, resolves Microsoft Entra group metadata, writes a normalized JSON artifact to Azure Blob Storage, and the connector reads that artifact during reconciliation when identity binding scanning is enabled. This split keeps reconciliation focused on Dataverse reads and avoids requiring Microsoft Graph permissions in the connector itself. #### Live data | Data | API / source | | -------------------------- | ------------------------------------------------------------------------- | | Agents | Dataverse `bot` table. | | Agent owner | Dataverse `bot` table with `owninguser` expansion. | | Agent tools | Dataverse `botcomponent` table, component type `9`, classified from YAML. | | Knowledge sources | Dataverse `botcomponent` table, component type `16`. | | Connected-agent references | Dataverse `botcomponent` table, component type `9`, classified from YAML. | | AI settings | Parsed from the Dataverse `bot.configuration` blob. | #### Inventory data The connector reads identity binding inventory from the following configured source when `identityBindingScanEnabled=true`: | Source | Configuration property | Used for | | ------------------ | ---------------------- | ---------------------- | | Azure Blob SAS URL | `toolsInventoryUrl` | `agentIdentityBinding` | ### Inventory behavior | Behavior | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Inventory source | `toolsInventoryUrl` or `toolsInventoryFilePath`. | | Identity binding gate | Inventory is fetched only when `identityBindingScanEnabled=true`. | | SAS URL behavior | SAS URL fetch is unauthenticated. The connector doesn't send a bearer token with the SAS request. | | Local file behavior | The connector reads the JSON file from `toolsInventoryFilePath`. Intended for dev/test. | | Missing inventory source | `agentIdentityBinding` search returns no data. GET-by-UID returns not found. | | Inventory cache | The client caches the inventory JSON for the connector instance lifetime. The connector is non-poolable so reconciliations get a fresh instance and fresh caches. | Expected inventory shape: ```json { "identityBindings": [ { "agentId": "00000000-0000-0000-0000-000000000000", "groupId": "11111111-1111-1111-1111-111111111111", "groupDisplayName": "Copilot Agent Users", "groupMail": "copilot-agent-users@example.com", "groupType": "Security" } ] } ``` ## Use the Microsoft Copilot Studio connector The Microsoft Copilot Studio connector discovers the following resource types: | ICF Native Type | Microsoft Copilot Studio / Dataverse Resource Type | Naming Attribute | Notes | | ---------------------- | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `__ACCOUNT__` | Copilot Studio agent / Dataverse `bot` row | `__NAME__` | Represents one Copilot Studio agent. UID is the Dataverse `botid`. By default, only published agents are returned. | | `agentTool` | Dataverse `botcomponent` row for tool components | `__NAME__` | Represents Power Platform connector tools and MCP tools. The connector classifies type `9` bot components by parsing the YAML `data` field. | | `agentKnowledgeBase` | Dataverse `botcomponent` row for knowledge source components | `__NAME__` | Represents knowledge sources attached to a Copilot Studio agent. These are Dataverse `botcomponent` records with component type `16`. | | `agentIdentityBinding` | Derived Microsoft Entra group-to-agent authorization binding | `__NAME__` | Not a native Dataverse object. Represents an authorized security group for an agent, derived from offline inventory and exposed as one object per agent/group pair. | ### `__ACCOUNT__` attributes | Attribute | Type | Multivalued | Description | | -------------------------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `platform` | String | No | Connector platform identifier. Current value is `COPILOT_STUDIO`. | | `agentId` | String | No | Dataverse `botid`. | | `statecode` | Integer | No | Dataverse state code. | | `statuscode` | Integer | No | Dataverse status code. | | `accessControlPolicy` | String | No | Label derived from Dataverse `accesscontrolpolicy`. Values include `Any`, `Agent readers`, `Group membership`, and `Any (multi-tenant)`. | | `authenticationMode` | String | No | Dataverse authentication mode. | | `runtimeProvider` | String | No | Dataverse runtime provider. | | `language` | String | No | Agent language. | | `schemaName` | String | No | Dataverse schema name. | | `publishedOn` | String | No | Published timestamp. | | `createdOn` | String | No | Created timestamp. | | `modifiedOn` | String | No | Modified timestamp. | | `toolIds` | String | Yes | Bot component IDs for child tool components. | | `knowledgeBaseIds` | String | Yes | Bot component IDs for child knowledge source components. | | `connectedAgentReferences` | String | Yes | Schema names of connected-agent wrapper components. | | `connectedAgentTargetSchemaName` | String | Yes | Target bot schema names parsed from connected-agent YAML. | | `connectedAgentTargetBotId` | String | Yes | Resolved target bot IDs for same-environment connected agents. | | `contentModeration` | String | No | Parsed from the `configuration` blob. | | `generativeActionsEnabled` | Boolean | No | Parsed from the `configuration` blob. | | `useModelKnowledge` | Boolean | No | Parsed from the `configuration` blob. | | `ownerPrincipalId` | String | No | Microsoft Entra object ID from Dataverse `owninguser.azureactivedirectoryobjectid`. | | `ownerDisplayName` | String | No | Owner display name from Dataverse `owninguser.fullname`. | | `ownerUserPrincipalName` | String | No | Owner UPN from Dataverse `owninguser.domainname`. | | `ownerMail` | String | No | Owner email from Dataverse `owninguser.internalemailaddress`. | ### `agentTool` attributes The connector reads Dataverse `botcomponent` rows with component type `9` and classifies them by parsing the YAML `data` field: | YAML value | Result | | -------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `kind: TaskDialog` and `action.kind: InvokeConnectorTaskAction` | `agentTool`, `toolType=Connector` | | `kind: TaskDialog` and `action.kind: InvokeExternalAgentTaskAction` | `agentTool`, `toolType=MCP` | | `kind: TaskDialog` and `action.kind: InvokeConnectedAgentTaskAction` | Connected-agent attributes on `__ACCOUNT__`, not an `agentTool` object | | `kind: AdaptiveDialog` | Topic; skipped by `agentTool` reconciliation | | Attribute | Type | Multivalued | Description | | --------------------- | ------ | ----------- | ------------------------------------------------------------------- | | `platform` | String | No | Connector platform identifier. | | `agentId` | String | No | Parent Dataverse `botid`. | | `toolType` | String | No | `Connector` or `MCP`. | | `connectionReference` | String | No | YAML `connectionReference`, when present. | | `operationId` | String | No | YAML `operationId` or `operationDetails.operationId`, when present. | | `description` | String | No | YAML `modelDescription`, when present. | | `schemaName` | String | No | Dataverse `botcomponent.schemaname`. | | `createdOn` | String | No | Dataverse created timestamp. | | `modifiedOn` | String | No | Dataverse modified timestamp. | ### `agentKnowledgeBase` attributes | Attribute | Type | Multivalued | Description | | ------------- | ------ | ----------- | ------------------------------------- | | `platform` | String | No | Connector platform identifier. | | `agentId` | String | No | Parent Dataverse `botid`. | | `schemaName` | String | No | Dataverse `botcomponent.schemaname`. | | `description` | String | No | Dataverse `botcomponent.description`. | | `createdOn` | String | No | Dataverse created timestamp. | | `modifiedOn` | String | No | Dataverse modified timestamp. | ### `agentIdentityBinding` attributes | Attribute | Type | Multivalued | Description | | ----------------- | ------ | ----------- | ------------------------------------------------------------------------- | | `platform` | String | No | Connector platform identifier. | | `agentId` | String | No | Dataverse `botid`. | | `agentVersion` | String | No | Current implementation emits `latest`. | | `kind` | String | No | Current implementation emits `GROUP`. | | `principal` | String | No | JSON string containing `groupId`, `displayName`, `mail`, and `groupType`. | | `permissions` | String | Yes | Current implementation emits an empty list. | | `scope` | String | No | Current implementation emits `ENVIRONMENT`. | | `scopeResourceId` | String | No | Agent ID associated with the binding. | ## Troubleshooting ### Connector initializes but test fails Check: 1. `tenantId` is valid. 2. `environmentUrl` points to the target Dataverse environment and doesn't include `/api/data/v9.2`. 3. `clientId` and `clientSecret` are valid. 4. The app registration is represented as a Dataverse application user in the target environment. 5. The application user has sufficient Dataverse permissions to read `bot` records. 6. The environment actually contains Copilot Studio agents. ### Agents reconcile but expected agents are missing Check: 1. `includeUnpublishedAgents` is set correctly. 2. The missing agents have a non-null `publishedon` value when `includeUnpublishedAgents=false`. 3. The Dataverse application user can read the relevant `bot` records. 4. The connector is pointed to the correct `environmentUrl`. ### Agents reconcile but `toolIds` or `agentTool` is empty Check: 1. The agent has Dataverse `botcomponent` records of component type `9`. 2. The `data` field contains YAML that classifies as `TaskDialog`. 3. The YAML action kind is either `InvokeConnectorTaskAction` or `InvokeExternalAgentTaskAction`. 4. The Dataverse application user can read `botcomponent` records. ### Agents reconcile but `knowledgeBaseIds` or `agentKnowledgeBase` is empty Check: 1. The agent has Dataverse `botcomponent` records of component type `16`. 2. The Dataverse application user can read `botcomponent` records. 3. The knowledge source belongs to the same parent bot ID returned in `_parentbotid_value`. ### `agentIdentityBinding` returns no records Check: 1. `identityBindingScanEnabled=true`. 2. Either `toolsInventoryUrl` or `toolsInventoryFilePath` is configured. 3. The inventory JSON contains an `identityBindings` array. 4. If using `toolsInventoryUrl`, the SAS token hasn't expired. 5. The SAS URL allows read access to the blob. 6. The offline inventory job has run successfully. 7. The agent uses group-based access control in Copilot Studio / Dataverse. ### Connected-agent target IDs are missing Check: 1. The connected-agent component is in the same Dataverse environment. 2. The YAML action contains `botSchemaName`. 3. A target agent exists in the same environment with a matching `schemaname`. 4. Cross-environment connected agents may populate `connectedAgentTargetSchemaName` without resolving `connectedAgentTargetBotId`. ## OpenICF interfaces implemented by the Microsoft Copilot Studio connector The Microsoft Copilot Studio connector implements the following OpenICF interfaces. You can find additional details in [ICF interfaces](interfaces.html): * Schema Describes the object types, operations, and options that the connector supports. * Search Searches the target resource for all objects that match the specified object class and filter. * Test Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid. This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out). You can invoke the test operation before a connector configuration has been validated. []() ## Microsoft Copilot Studio connector configuration The Microsoft Copilot Studio connector has the following configurable properties: ### Basic configuration properties | Property | Type | Default | Encrypted(1) | Required(2) | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------- | ------------------------ | ------------------------- | | `tenantId` | `String` | `null` | | [icon: check, set=fas]Yes | | Azure AD tenant ID (GUID). | | | | | | `environmentUrl` | `String` | `null` | | [icon: check, set=fas]Yes | | Dataverse environment URL, e.g. . Don't include `/api/data/v9.2`; the connector appends it. | | | | | | `clientId` | `String` | `null` | | [icon: check, set=fas]Yes | | Azure AD application (client) ID for OAuth2 client credentials. | | | | | | `clientSecret` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | Azure AD application client secret. | | | | | | `toolsInventoryUrl` | `String` | `null` | | [icon: times, set=fas]No | | HTTPS URL to identity bindings inventory JSON in Azure Blob Storage. | | | | | | `toolsInventoryFilePath` | `String` | `null` | | [icon: times, set=fas]No | | Local file path to inventory JSON. Dev/test only. | | | | | | `httpTimeoutSeconds` | `Integer` | `30` | | [icon: times, set=fas]No | | HTTP connect and read timeout in seconds. | | | | | | `logPayloads` | `Boolean` | `false` | | [icon: times, set=fas]No | | When true, log raw JSON payloads for debugging. Not recommended in production. | | | | | | `identityBindingScanEnabled` | `Boolean` | `false` | | [icon: times, set=fas]No | | When true, the connector reads the identity binding inventory (from toolsInventoryUrl or toolsInventoryFilePath) and returns agentIdentityBinding objects. When false (default), agentIdentityBinding searches return no data regardless of inventory configuration. | | | | | | `includeUnpublishedAgents` | `Boolean` | `false` | | [icon: times, set=fas]No | | When true, agents with no publish timestamp (never published / draft) are included in search results. When false (default), only published agents (those whose `publishedon` field is non-null) appear in reconciliations. UID lookups of unpublished agents return UnknownUidException when this flag is false. | | | | | (1) Whether the property value is considered confidential, and is therefore encrypted in IDM. (2) A list of operations in this column indicates that the property is required for those operations.