Microsoft 365 Copilot Search Integration with SharePoint and OneDrive Support
Overview
This feature enables Servicely's AI Copilot to search Microsoft 365 content — SharePoint, OneDrive for Business, and external items (connectors) — on behalf of the logged-in user. Searches use the Microsoft Graph Copilot Retrieval API with the user's own delegated OAuth token, so SharePoint access permissions are fully respected.
Prerequisites
- Microsoft Azure Active Directory (Entra ID) tenant
- Azure AD application registration with the following delegated permissions (not application):
- Files.Read.All
- Sites.Read.All
- ExternalItem.Read.All (if using external connectors)
- offline_access (for refresh token support)
- Microsoft 365 Copilot licences (required for the /copilot/retrieval Graph API endpoint)
Setup Steps
1. Configure the Azure AD Application Registration
In the Azure Portal:
- Navigate to Azure Active Directory → App registrations and select (or create) your Servicely app registration.
- Under API permissions, add the delegated permissions listed above and grant admin consent.
- Under Authentication, add the Servicely SSO redirect URI:https://<your-servicely-host>/sso/oauth_callback/
- Under Certificates & secrets, note your Client ID, and Client Secret.
2. Create a System OAuth Provider
In Servicely, navigate to Admin → Integrations → System OAuth Providers and create a new record:
Field | Value |
|---|---|
Name | ms-graph-copilot (or any name — you will reference it in step 3) |
Client ID | Your Azure AD app's Application (client) ID |
Client Secret | Your Azure AD app's client secret |
Authorization URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize |
Token URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
Redirect URL | https://{your-servicely-host}/sso/oauth_callback |
Scopes | https://graph.microsoft.com/.default |
Grant Type | authorization_code |
Note: If Scopes is left blank, the system defaults to https://graph.microsoft.com/.default.
3. Link the OAuth Provider to your OIDC Identity Provider (Recommended)
In Servicely, navigate to Administrator → Authentication → Identity Providers and open your Azure AD OIDC/SAML provider record.
- In the Linked OAuth Providers field, add the OAuth Provider record created in step 2.
This tells Servicely to automatically capture and store the user's Microsoft access and refresh tokens every time they log in via Azure AD SSO.
4. Set the Application Property
In Servicely, navigate to Admin → Application Properties and set:
Property Key | Value |
|---|---|
microsoft.search.oauth.provider.name | The Name of the OAuth Provider created in step 2 (e.g. ms-graph-copilot) |
This property tells the Microsoft search service which OAuth Provider to use for Copilot Retrieval queries.
How It Works
Token Lifecycle
- When a user logs in via Azure AD SSO, Servicely automatically saves their access token and refresh token to the SystemAPIOutboundToken table, linked to the user and the configured OAuth Provider.
- Tokens are automatically refreshed when they expire — no user action needed after initial login.
- If a user has never logged in via Azure AD SSO (or their token record is missing), the system will prompt them to complete an OAuth consent flow via a "Connect your Microsoft account" link.
Search Behavior
- Searches run against SharePoint, OneDrive for Business, and external items simultaneously in a single batched Graph API call.
- Results are ranked by relevance score and the top 5 chunks (default) are returned to the AI assistant.
- If a data source returns an error (e.g. user has no access), that source is skipped and results from other sources are still returned.
Using the Search in AI Assistant Scripts
The MSSearch global is available in Servicely AI assistant tool scripts:
// Basic search — runs as the currently logged-in userlet results = MSSearch.search("change management process")// Each result contains:// - title : Document/page title// - summaryChunk : Relevant text extract// - relevanceScore: Score between 0 and 1 (higher = more relevant)// - resourceLink : URL to the source document// - resourceType : e.g. "listItem", "site"// - author : Author from document metadata (may be null)// - dataSource : "sharePoint", "oneDriveBusiness", or "externalItem"
Troubleshooting
User sees "Microsoft authorization required" message
The user's delegated token is missing or has not yet been initialized.
Resolution: The user must log out and log back in via Azure AD SSO. Once they re-authenticate, their token is automatically captured and stored.
If the user is not using Azure AD SSO, they will be redirected to a consent URL at:
https://<your-servicely-host>/sso/oauth_outbound_redirect/<token-record-id>
They must visit this URL and complete the Microsoft OAuth consent flow.
Search returns no results
- Confirm the user has Microsoft 365 content in SharePoint or OneDrive.
- Confirm the Azure AD app has the required delegated permissions and admin consent has been granted.
- Confirm the user has a Microsoft 365 Copilot license — the /copilot/retrieval endpoint requires it.
- Check Servicely application logs for errors from MsGraphSearchService — look for batch response error messages that indicate the specific failure reason.
Token not being stored at login
- Confirm the Azure AD Identity Provider record has the OAuth Provider linked (step 3 above).
- Check Servicely logs during login for errors.
InvalidConfigurationException: SystemOAuthProvider for copilot search not defined
The application property microsoft.search.oauth.provider.name is not set or is blank.
Resolution: Follow step 4 above.
InvalidConfigurationException: No System OAuth Provider found with name <name>
The name in the application property does not match any existing OAuth Provider record.
Resolution: Verify the Name field on the OAuth Provider record exactly matches the value in microsoft.search.oauth.provider.name.
Security Considerations
- Servicely stores OAuth access and refresh tokens encrypted in the database.
- Searches run with the logged-in user's permissions — users cannot access SharePoint content they are not permitted to see in Microsoft 365.
- Application-level (app-only) credentials are not used for search — delegated user tokens only.