Set Up Copilot Connectors to Index External Data with Correct Permissions

To bring external content into Microsoft 365 Copilot, create a synced connector in the Microsoft 365 admin center under Copilot > Connectors > Gallery, choose Custom setup, and on the Users tab set access permissions to Only people with access to this data source so each indexed item keeps the source system's access control list. Map source identities to Microsoft Entra users, pilot the connection with Rollout to limited audience, and schedule regular full crawls, because only full crawls update permissions.

Who this is for and what you will have at the end

This guide is for Microsoft 365 and AI administrators who want Copilot to answer from systems such as ServiceNow, Confluence, Salesforce, file shares or SQL databases, without exposing content to people who can't see it in the source.

At the end you will have:

• A choice between synced and federated connectors, matched to your licensing.
• A synced connection with source permissions enforced and identities mapped.
• The Microsoft Graph connector agent installed for an on-premises source, if needed.
• A staged rollout, a crawl schedule and a monitoring routine.
• The ACL model to follow if you build a custom connector with the Microsoft Graph connectors API.

How Copilot connectors work

Copilot connectors (formerly Microsoft Graph connectors) come in two families:

A synced connector uses the Microsoft Graph connectors API to ingest items into the Microsoft Graph index. Each item has content, metadata such as title and URL, and an access control list. After ingestion, the item is full-text searchable and semantically indexed, and both Copilot and Microsoft Search filter results by the user's access. Connectors check for changes on a schedule.

Federated connectors don't index anything; they query the source at runtime with OAuth on behalf of the user, which suits live or sensitive data that shouldn't be copied into Microsoft 365. This guide focuses on synced, tenant-configured connectors, because that's where ACL design decides who sees what.

Prerequisites

Roles and access

• AI administrator in the Microsoft 365 admin center to create, view and manage connections and staged rollouts.
• Admin access to the external service for prebuilt connectors, for example a Confluence admin or Google Workspace Super Admin.
• A service account in the source with read access to everything you intend to index. The "discovered items" count in the admin center reflects what these credentials can see.

Licensing

Indexing synced connector data has no extra cost for tenants with Microsoft 365 licenses. Semantic search features require at least one Microsoft 365 Copilot license in the tenant.

Network

If the source sits behind an IP firewall, allow the Copilot connector service ranges for your region. For Microsoft 365 Enterprise these are 52.250.92.252/30 and 52.224.250.216/30 (NAM), 20.54.41.208/30 and 51.105.159.88/30 (EUR), and 52.139.188.212/30 and 20.43.146.44/30 (APC).

Step 1: Decide the permission model before you create anything

This is the decision that's hardest to undo. In Custom setup > Users > Access Permissions you choose between:

• Only users with access to the content (shown afterwards as Only people with access to this data source): the connector indexes the source ACLs and Copilot trims results per user.
• Everyone in the organization (shown as Visible to everyone): every user can find every indexed item.

Choosing Everyone for a source that has restricted content is a direct path to oversharing through Copilot. And you can't fix it later: updating access permissions after creating the connection isn't supported. You must delete the connection and recreate it.

Use Everyone only for content that is genuinely public inside the organization, such as a company-wide knowledge base, and confirm that with the content owner.

Map source identities to Microsoft Entra ID

ACLs only work if source users resolve to Entra users. By default, the connector matches the user's email in the source to UserPrincipalName or Mail in Microsoft Entra ID. If the source uses a different identity (non-Entra ID), use Map Identities to build a mapping:

1. Select the target Entra property: User Principal Name (UPN), Microsoft Entra ID or Microsoft Entra object ID.
2. Select one or more source user properties and apply a regular expression to each, for example (\w+)$ to take the last word.
3. Build a formula from the outputs, such as {0}.{1}@contoso.com.
4. Select Preview to test five random users; each shows Success or Failed.

Plan this carefully. Only one mapping applies to all users, conditional mappings aren't supported, and you can't change the mapping after the connection is published. The preview only samples five users, so a formula that doesn't resolve every user can still produce mapping failures after the connection is created; watch for error 2006 and the User & group Errors count.

Step 2: Install the connector agent for on-premises sources

On-premises connectors, such as file share, Microsoft SQL, Oracle SQL, Confluence Data Center and GitHub server, need the Microsoft Graph connector agent on a Windows server that can reach both the source and the internet.

Recommended configuration for one agent handling up to three connections:

• Windows 10, Windows Server 2016 R2 or later, with .NET Framework 4.7.2 and .NET Core Desktop Runtime 10.0 (x64).
• 8 cores at 3 GHz, 16 GB RAM, and 40 GB disk for 5 million items plus 9 GB per additional million.
• Outbound port 443 to *.events.data.microsoft.com, *.office.com, https://login.microsoftonline.com, https://gcs.office.com/ and https://graph.microsoft.com/. Proxy authentication isn't supported.

Register an app for the agent in Microsoft Entra ID with these Microsoft Graph application permissions, then grant admin consent:

Authenticate the agent with a client secret or, preferably, a certificate. When using a certificate, grant NT Service\GcaHostService access to its private key. Download the agent from https://aka.ms/gca, make sure the PowerShell execution policy allows remote signed scripts, then sign in to the configuration app with an account that holds the AI administrator role and register it.

# Check that remote signed scripts are allowed before installing
Get-ExecutionPolicy -List
 
# Confirm the agent can reach the connector service
Test-NetConnection gcs.office.com -Port 443

Step 3: Create the connection with Custom setup

1. Sign in to the Microsoft 365 admin center and go to Copilot > Connectors.
2. On the Connectors tab, select Gallery and choose the data source.
3. Enter a display name users will recognize in Copilot and search results.
4. Enter the source URL, for example https://contoso.service-now.com, and choose the authentication method.
5. Turn on Rollout to limited audience and add pilot users or groups.
6. Select Custom setup rather than accepting defaults, and work through the three tabs below.

Users tab

Set Access Permissions as decided in Step 1 and configure identity mapping.

Content tab

Under Manage properties:

• Choose the Content property used for full-text indexing and snippets.
• Assign semantic labels. title is the most important; also map url, Created By, Last modified by, Authors, Created date time, Last modified date time, File name and File extension where the source has them. Properties mapped to labels must be retrievable.
• Set schema attributes: SEARCH (full-text), QUERY (property queries), RETRIEVE (shown in results) and REFINE (filters). Only string properties can be searchable, int properties can't be refined, and you can't add or remove the refinable attribute after setup.

Sync tab

Configure Full crawl and Incremental crawl schedules: recurrence, days, a frequency between 15 minutes and 12 hours, and a start time. Leaving fields blank lets the service choose.

Incremental crawls only process new or changed items and don't process permission updates. Schedule full crawls regularly so ACL changes and deletions in the source reach the index.

7. Select Create. On the success screen, add a description of the content, how users refer to it and when they use it. Microsoft's guidance is to write it so Copilot can discover the connection's content when it's relevant.

Step 4: Pilot, then widen the rollout

The staged rollout supports up to 100 users and 15 Microsoft 365 groups, and applies to both Search and Copilot experiences. During the pilot, test with users who should and shouldn't see specific items.

To change the audience, go to Copilot > Connectors > Your Connections, select Edit next to Staged in the Staged Rollout column, and add or remove users and groups. When you're satisfied, choose End Staging and then Remove. Results then appear for everyone in the organization who has access according to the ACLs.

Custom connectors: write the ACL yourself

If you build a connector with the Microsoft Graph connectors API, every externalItem must include an acl. Each entry has a type (user, group, everyone, everyoneExceptGuests or externalGroup), a value (the Entra object ID, or the external group ID), and an accessType of grant or deny. The app needs ExternalItem.ReadWrite.OwnedBy (least privileged) and the payload is limited to 30 MB.

{
  "acl": [
    { "type": "user", "value": "e811976d-83df-4cbd-8b9b-5215b18aa874", "accessType": "grant" },
    { "type": "externalGroup", "value": "14m1b9c38qe647f6a", "accessType": "deny" }
  ],
  "properties": {
    "title": "Error in the payment gateway",
    "priority": 1,
    "assignee": "john@contoso.com"
  },
  "content": { "value": "Error in payment gateway...", "type": "text" }
}

Send it with PUT https://graph.microsoft.com/v1.0/external/connections/{connectionId}/items/{itemId}. A deny entry always takes precedence over grant. If the source uses its own groups, create external groups with the group sync APIs instead of expanding group membership into every item's ACL, and translate non-Entra users to Entra users. The same permission-trimming principle applies to any retrieval pipeline you build yourself, as covered in production LLMOps and enterprise RAG architecture.

Security and compliance considerations

• Sensitivity labels and encryption on data from connectors aren't recognized by Microsoft 365 Copilot Chat, so label-based exclusions such as those in excluding labeled files from Copilot don't apply to connector content. Control exposure with ACLs and with what you choose to index.
• Copilot interactions are still audited like any other; monitor them with DSPM for AI.
• To cut off a source quickly, delete the connection in Your Connections.

Verify the connection

1. Open Your Connections, select the connection and review Index status: Items, Users, Groups, Group memberships, Item Errors and User & group Errors. Use Refresh for current counts.
2. After the first full crawl, compare Total number of discovered items with Completely indexed items and Partially indexed items (partial can mean an incomplete ACL).
3. As a pilot user with source access, ask Copilot about a specific item and confirm it cites the source.
4. As a pilot user without access, ask the same question and confirm the item isn't returned.

Troubleshooting

For a full error export, install DownloadErrorScript from the PowerShell Gallery and run it with the connection ID.

Closing checklist

• Synced or federated decided per source, and licensing confirmed for Copilot grounding.
• Only people with access to this data source selected for any source with restricted content.
• Identity mapping previewed and tested before publishing.
• Connector agent sized, certificate-authenticated and allowed through the proxy, for on-premises sources.
• Semantic labels mapped, especially title and url, and a clear connection description added.
• Full crawls scheduled so permission changes are picked up.
• Pilot completed with positive and negative access tests before ending staged rollout.

References

• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/overview
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/prerequisites
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/deployment-overview
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/manage-access-permissions
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/map-non-entra-id
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/staged-rollout
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/connector-agent
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/view-details
• https://learn.microsoft.com/en-us/microsoft-365/copilot/connectors/error-responses
• https://learn.microsoft.com/en-us/graph/connecting-external-content-manage-items
• https://learn.microsoft.com/en-us/graph/api/externalconnectors-externalconnection-put-items
• https://learn.microsoft.com/en-us/graph/api/resources/externalconnectors-acl
• https://learn.microsoft.com/en-us/purview/ai-m365-copilot-considerations