> For the complete documentation index, see [llms.txt](https://docs.strongdm.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.strongdm.com/admin/deployment/integrations/microsoft-copilot-studio.md).
# Microsoft Copilot Studio Connector
{% hint style="warning" %}
This feature is currently in a closed-access tech preview. Functionality and documentation may change. Contact StrongDM for more information.
{% endhint %}
## Overview
The Microsoft Copilot Studio connector allows your Copilot agents to securely interact with StrongDM-managed resources. End users can list their entitled resources and run commands against SSH servers and SQL databases directly from a Copilot agent, without embedding credentials or changing your existing StrongDM infrastructure.
When a user interacts with a Copilot agent that has the StrongDM connector, StrongDM authenticates the user via OAuth and enforces access based on their existing StrongDM entitlements. All commands run through StrongDM's control plane and are authorized and logged just like any other StrongDM-mediated access.
No database credentials, SSH keys, or secrets are exposed to Copilot at any point. Credential injection and command execution happen exclusively on your organization's StrongDM-managed nodes.
## How It Works
The integration connects Microsoft Copilot Studio to StrongDM through the following flow:
1. A StrongDM administrator creates a Microsoft Copilot Studio connection in the StrongDM Admin UI and receives OAuth credentials and several URLs.
2. A Copilot developer creates a custom connector in Microsoft Copilot Studio and then adds the connector to their agent, using the StrongDM credentials and URLs.
3. When an end user invokes a StrongDM tool through the Copilot agent, the user is redirected through an OAuth flow with StrongDM (if not already authenticated). StrongDM issues a short-lived access token scoped to that user.
4. Copilot resource interactions on the user's behalf flow through StrongDM's control plane and the organization's StrongDM nodes, which route the traffic as they would normal user actions.
## Prerequisites
### StrongDM requirements
To set up the Microsoft Copilot Studio connector, you need the following in StrongDM:
* Your organization must have the Microsoft Copilot Studio connector feature enabled. Contact StrongDM support to inquire about access to the tech preview.
* Administrator permission level
* At least one operational StrongDM node (gateway, relay, or proxy cluster) with access to the target resources
* The resources you want to expose through Copilot must be configured in StrongDM.
* Your organization must be on the US StrongDM control plane.
### Microsoft requirements
On the Microsoft side, you need the following:
* Microsoft Copilot Studio environment with permissions to create or edit agents
* Ability to add custom connectors to a Copilot Studio agent
For detailed information about working with connectors in Microsoft Copilot Studio, see [Microsoft's Copilot Studio documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/).
## Policies
If your organization has the Policy feature enabled, commands issued through the Copilot connector are authorized against your configured policies and logged in the policy logs, in the same way as other StrongDM-mediated access, including PBAC for PostgreSQL resources. Policy log entries also indicate when the access was initiated through Copilot.
Be aware of the following limitations with respect to policy and Copilot:
* **Justification and TOTP MFA policies are not supported.** Policies that require a justification or TOTP MFA through the StrongDM Desktop application will deny access when triggered via Copilot.
* **Device trust** status will always be unknown or exempt, depending on whether the user is configured to be exempt from device trust.
* **Geolocation and source IP address** are based on the IP address the user initially authenticated with, and they do not reflect the user's current location if it changes after initial authentication.
## Limitations
Be aware of the following limitations during the Tech Preview:
* **US control plane only:** The Microsoft Copilot Studio connector is available only for organizations on the US StrongDM control plane that have been given access to the tech preview feature.
* **Rate limiting:** The connector is rate-limited to prevent excessive requests.
* **Supported resource types:** Only SSH servers and SQL databases (PostgreSQL, MySQL, and Microsoft SQL Server) are supported. Other resource types are not available through the connector.
* **No agent-specific entitlements:** Access is enforced based on the end user's StrongDM entitlements only. Composite identity authorization (combining agent identity and user identity) is not supported in this release.
* **Microsoft Copilot Studio only:** The connector works with Microsoft Copilot Studio agents. Other agentic platforms are not supported through this integration.
* **Request and response size and time limits:** Requests and responses are limited to 512 KiB, and command execution is limited to 25 seconds. If these limits are exceeded (for example, from a SQL query that returns a large result set) an error will be returned and displayed by the agent. To avoid hitting these limits, adjust your prompts to request data in smaller batches or with row limits applied.
* **SSH resource locking:** For SSH resources that require a resource lock, access is denied unless the end user has already locked the resource outside of Copilot (via the StrongDM Desktop application or CLI). To access such a resource through a Copilot agent, the user must acquire the lock externally before their session and release it when finished (or rely on lock expiration if enabled).
### Supported Resources
During the Tech Preview, the connector supports the following StrongDM resource types:
* **SSH servers:** Run shell commands against SSH resources to which the user has access.
* **SQL databases:** Run SQL queries against supported database resources to which the user has access. Supported databases include PostgreSQL, MySQL, and Microsoft SQL Server.
End users can also list the resources to which they are entitled in StrongDM, including the health status of those resources. Note that this listing includes all resource types to which the user is entitled, not only SSH and SQL resources.
## Set Up the StrongDM Integration
Follow these steps to set up the Microsoft Copilot Studio integration in StrongDM.
1. Log in to the StrongDM Admin UI.
2. Go to **Integrations** and then under **SaaS Agents**, find **Microsoft Copilot Studio** and click **Connect**.
3. Enter a **Name** for the connection (for example, "Copilot Production" or "Copilot Dev Team") and then click **Connect**.
4. StrongDM generates a **Client ID** and **Client Secret** and shows those as well as an **Authorize URL**, **Token URL**, **Refresh URL**, and **OpenAPI URL**. Leave this tab open to copy these values when configuring the connector in Microsoft Copilot Studio, or store them securely.
{% hint style="warning" %}
Copy the client secret before closing this configuration screen. You will not be able to retrieve it later.
{% endhint %}
## Configure the Connector in Microsoft Copilot Studio
After you have the client ID, client secret, and URLs from StrongDM, add the a custom connector to your Copilot Studio agent. At a high level, the steps are as follows:
1. Open Microsoft Copilot Studio.
2. Go to **Tools**, click **New tool**, choose **Custom connector**, and then choose **Import an OpenAPI from URL** from the **New custom connector** dropdown.
3. On the popup **Import an OpenAPI from URL** view, enter a **Connector name** (such as "StrongDM") and for **Paste in the URL for the Open API**, paste the value from the StrongDM connector setup screen that was called **OpenAPI URL** and then click **Import**.
4. The settings on the **General** tab can be adjusted as needed, such as the connector's icon or description.
5. Open the **Security** tab and ensure the **Authentication type** is set to "OAuth 2.0". Fill in the **Client ID**, **Client secret**, **Authorization URL**, **Token URL**, and **Refresh URL** from the StrongDM connector setup screen. Leave **Scope** empty.
6. The **Definition** tab includes information about the connector that is pulled in from the Open API specification. There should be three **Tools** available in the list on the left-hand side.
7. The **Code** tab can be skipped.
8. The **Test** tab requires the connector to be created to proceed, so click **Create connector**, and wait for the connector to be created and create a connection (which requires authenticating to link to your StrongDM account) and test if desired. If you don't want to create a connection to your StrongDM account and test here, you don't have to. You will just be prompted to do so on first use later.
9. Return to the Microsoft Copilot Studio home page and navigate to **Agents** in the sidebar. Then click **Create blank agent**.
10. In the agent's **Tools** tab, click **Add a new tool**, and then search for the name of the custom connector you just added. The tools available via that connector should appear as results. Select one, and choose **Add and configure**. Repeat for the other tools.
11. Now that your agent has the custom connector's tools configured, chat with the agent and ask it what StrongDM resources are available to it. Note that the agent will typically prompt you with "Let's get you connected first" and ask you to open the Connection Manager to authorize before proceeding (see [End User Authentication](#end-user-authentication)). Once connected, you can watch the agent use the List Available Resources tool and respond. You may also test an interaction with a resource at this stage (for example, try asking "How many users are in the development database?" or "What OS version is the build server running?").
For detailed steps on how to add and configure connectors in Copilot Studio, see [Microsoft's documentation on custom connectors](https://learn.microsoft.com/en-us/connectors/custom-connectors) .
### **Optional: Enable Database Targeting for Execute SQL Command**
The Execute SQL Command tool supports an optional parameter that allows the agent to target a specific database on a StrongDM resource that provides access to multiple databases on the same server. Optional parameters are disabled by default in Copilot Studio, so this requires additional configuration.
To enable this behavior, follow these steps.
1. Open the configuration for the Execute SQL Command tool.
2. Click the ellipsis (…) menu at the top of the page and select **Open code view**.
3. On the second line, immediately after the `kind: TaskDialog` line, add the following block:
```yml
inputs:
- kind: AutomaticTaskInput
propertyName: database
shouldPromptUser: false
inputSettings:
defaultValue: =Blank()
```
4. Click **Save**. The agent is now able to pass an optional database name when executing SQL commands.
{% hint style="info" %}
Alternatively, instead of using the code view, you can use the graphical tool input editor to add a `database` input field, configure it not to re-prompt the user, and set it to an empty value (no value) if not found.
{% endhint %}
## End User Authentication
When an end user first interacts with a StrongDM tool through a Copilot agent, the agent prompts them to connect to the StrongDM control plane.
After clicking the **Connection Manager** link, they are taken to a page where they can select or create a connection for the custom connector created previously.
Clicking **Sign in** takes the user to the StrongDM OAuth endpoint. If they are not already authenticated, they are prompted to log in to their StrongDM account and are then prompted to connect.
Clicking **Connect** associates this specific agent instance with the displayed StrongDM user account. The user can then return to the agent and click **Retry** to continue.
This connection flow grants the agent a token that can be used to issue requests for up to three days, as long as the associated authentication remains valid. If the user explicitly logs out of StrongDM or the organization's session timeout is reached, the token is no longer valid.
If a user needs to change or delete the connection, they can do so in the **Connections** section of the Microsoft Power Apps page.
{% hint style="info" %}
Access is enforced strictly based on the user's existing StrongDM entitlements. If a user does not have access to a resource in StrongDM, they cannot access it through Copilot. Although resources that the user is able to request access to (but does not currently have) are not visible through Copilot, the user can request access to such resources through the StrongDM UI. Once access is approved, those resources will become accessible through Copilot.
{% endhint %}
## Auditing and Logging
All commands executed through the Copilot connector are logged in StrongDM's existing audit surfaces, just as any other user interaction with a resource would be. When viewed in the StrongDM Admin UI, log entries created through the Copilot integration also indicate the integration associated with the entry.
{% hint style="info" %}
The CLI, SDKs, and Log Stream interfaces do not currently include Copilot integration activity. Copilot-related access is visible in the Admin UI activity logs only. This is intentional during the tech preview.
Additionally, a "User authorized integration" activity is logged to the activity logs whenever an end user authorizes a Microsoft Copilot Studio agent.
{% endhint %}
## Troubleshooting
### User cannot authenticate through the Copilot agent
Verify that the user has an active StrongDM account and is able to log in to StrongDM directly. The OAuth flow requires a valid StrongDM user identity.
Also verify that the integration settings in StrongDM match those in the custom connector, particularly the Client ID.
### User cannot see or access a resource
Confirm that the user is entitled to the resource in StrongDM. Go to **Access** > **Roles** in the Admin UI and verify that the resource is attached to a role the user is a member of. The connector enforces the same entitlements as any other StrongDM access method.
If the user is unable to access a specific database on a resource (rather than the default database), verify that the optional database parameter is enabled as described in [Optional: Enable Database Targeting](#optional-enable-database-targeting-for-execute-sql-command). Also check that the resource configuration in StrongDM does not have **Restrict Database** (for PostgreSQL resources) or **Override Default Database** (for Microsoft SQL Server) set in a way that conflicts.
### Commands fail or time out
* Check that the StrongDM node (gateway, relay, or proxy cluster) that has access to the target resource is online and healthy. You can verify node status in the Admin UI under **Networking**.
* In Tech Preview, check to verify that the command Copilot ran is using the StrongDM resource ID rather than the resource name. Sometimes during testing, Copilot mistakenly used the resource name. This is a known issue that will be corrected for in the future.
* For SSH resources, check whether the resource requires a lock and verify that the user account associated with the agent is currently holding that lock.
* Ensure that the request will not generate a response exceeding 512 KiB or require more than 25 seconds to execute. Try requesting data in smaller batches.
* Ensure that the request and response do not contain non-UTF-8 characters.
* If a request fails with a `429` error mentioning resource exhaustion, this likely indicates that too many Copilot agents in the organization are concurrently executing commands against StrongDM.
### Commands that were working have started failing
Check that the user is still authenticated to StrongDM and still has access to the desired resource. The SDM authentication token may have expired independently of Copilot (for example, due to a session timeout or explicit logout). Try disconnecting and reconnecting to StrongDM in the agent's Connection Manager to refresh the authentication.
### Error code reference
The following table shows common error codes and their meanings.
| Error | Meaning |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Command execution failed: invalid operation: commands can only be executed against the default database on this resource` | The optional database parameter is not configured, or the resource does not allow targeting a non-default database. |
| `401 permission denied` | The user's authentication is invalid (expired, logged out, or the account has been deleted). |
| `403 Command execution failed: permission denied` | The user is authenticated but no longer has access to the target resource. |
| `429 resource exhausted: Sorry! You've made too many requests…` | Too many Copilot agents in the organization are executing commands simultaneously. |
| `500 failed to execute command: permission denied: access denied` | The SSH resource requires a lock that the user has not acquired. |
| `500 Deadline exceeded - execution time limit exceeded` | The command exceeded the 25-second execution time limit. |
| `500 Invalid byte sequence for encoding "UTF8"` | The command or its response contains non-UTF-8 characters. |
| `500 Response size exceeds maximum allowed size of 524,288 bytes` | The response exceeded the 512 KiB size limit. Try requesting data in smaller batches. |
| `ConnectorTimeoutError` (The connector has timed out after 240000 seconds) | Copilot's 30-second timeout was hit before StrongDM responded. Despite the message text, this usually indicates a connectivity issue (for example, no egress node is available to reach the target resource). |
### Still encountering issues?
Contact your StrongDM Tech Preview team. When reaching out, please provide the following information:
* Integration name
* Resource name or resource ID
* Error message and code displayed in the Copilot agent
* StrongDM account of the affected user
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.strongdm.com/admin/deployment/integrations/microsoft-copilot-studio.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.