Microsoft Graph

​

About Microsoft Graph

Microsoft Graph connects Serval to Microsoft 365 and Entra ID through the Microsoft Graph API, giving your workflows and ingestion access to Entra ID users and groups, enterprise applications, Microsoft Intune device management, license and subscription management, mail and calendar, and SharePoint/OneDrive content for the Serval knowledge base. Anything in the Microsoft Graph API surface can be reached through Serval’s proxied request layer, subject to the permissions you grant. Authentication: Sign in with Microsoft (recommended; OAuth 2.0 with delegated permissions), or a Custom Application (OAuth 2.0 client credentials with application permissions). Data sync: Background sync of Entra ID users, Entra Security Groups (full sync every 16 hours, delta every 4), Entra Microsoft 365 Groups (full sync every 8 hours, delta every 4), and enterprise applications with their app role assignments - plus continuous indexing of SharePoint and OneDrive content as a knowledge source.

​

What the Microsoft Graph integration enables

Anything defined in the Microsoft Graph API can be accessed through Serval.

​

Get your credentials

​

Connect in Serval

​

User sync settings

User sync runs on the integration’s settings page under User Sync. Two switches control who becomes a Serval user; both require the organization admin role.

• Create new users: when on, user sync creates a Serval user for anyone it doesn’t recognize. When off, it only updates people who already exist and skips the rest.
• Exclude guest accounts: when on, the built-in Microsoft Graph user sync skips Entra ID guest accounts (external people invited into your tenant with a userType of Guest, listed under Users > Guest users in the Microsoft 365 admin center). Guests that an earlier built-in sync already created in Serval are retired on the next sync, the same way user sync handles a user removed from the directory. Built-in Microsoft Graph user syncs have this on by default. When off, guests sync like members.

A new custom-only user-ingestion configuration starts with guest exclusion off. Customizing an existing built-in sync keeps its current setting. If guest exclusion is on, the workflow must provide a guest classification for every returned user or the sync fails. With Deactivate absent users off, excluded guests that were synced previously remain active.

​

Profile photos

User sync fetches each synced user’s profile photo (the 96x96 thumbnail, well under the 100KB cap Serval accepts for synced photos) and sets it as their Serval profile photo. A synced photo fills in only when the person has no photo yet and never replaces one they set themselves.

• Permissions: photo reads are covered by the User.Read.All application permission that user sync already requires; ProfilePhoto.Read.All alone also suffices. The Sign in with Microsoft base permission set covers photo reads too. If the connection cannot read photos, users still sync - the sync logs the denied photo reads and carries on without avatars.
• Where photos come from: Microsoft generates sized thumbnails for photos served through a Microsoft 365 mailbox. A photo stored only in Entra ID for a user without a mailbox may not be available at thumbnail sizes, in which case that user syncs without a photo.
• When photos apply: a synced photo fills in when the person has no Serval photo yet. It never replaces an existing photo - one they set themselves or one an earlier sync stored - and removing a photo in Entra does not remove an avatar Serval already synced.

​

SharePoint Site Assets

When Site Assets selection is enabled for your team, in Knowledge → Manage Sources → Choose items to sync → Choose SharePoint paths, open a site to find its Site Assets document library. Its displayed name can vary by language. Expand the library to select a folder such as SitePages/Benefits; Serval syncs supported files inside the selected path using the normal document permissions and original file links. Site Assets is offered explicitly in the picker. Existing whole-site selections do not automatically add a previously undiscovered Site Assets library. Selecting a folder inside Site Assets keeps that scope independent of the site selection; deselecting it stops that subtree from syncing. A SitePages folder inside Site Assets contains files and is separate from the site’s modern Site Pages collection below.

​

SharePoint site pages

In Knowledge → Manage Sources → Choose items to sync → Choose SharePoint paths, open a site and select Site Pages to sync its modern pages without selecting its document libraries. This selection covers the site’s page collection, including pages with nested SharePoint URLs. Individual pages and page folders cannot be selected in this picker. Serval reads published modern pages through Microsoft Graph’s Pages API. Text web parts and text exposed by standard web parts are extracted; original page URLs are retained for citations. Links in text are preserved. Linked documents, embedded applications, images, video, and dynamically loaded content are not automatically ingested. Classic publishing and wiki pages that Graph does not return as sitePage resources are not supported. A .aspx extension alone does not identify a supported page. Page access is read from each page’s own SharePoint role assignments, rather than inferred from a document library. This uses the existing certificate setup on a Custom Application connection. When permission sync and enforcement are enabled, pages remain hidden when their permissions cannot be read or mapped. A delegated Sign in with Microsoft connection does not provide this certificate path. Tenant permission-denied responses need investigation; do not grant broader permissions merely because a page cannot be read. When permission enforcement is enabled, a failed file or page permission read also removes earlier grants until a successful read restores them. Transient SharePoint failures can therefore temporarily hide affected content while the sync retries. Scheduled syncs reconcile the selected page collection. Modification timestamps determine content refreshes; checked-out pages retain their last indexed published content and selection without ingesting the draft. Pages missing from a completed listing receive an individual read: a confirmed 404 marks a deletion, while a denied or failed read does not prove deletion. At most 100 missing pages are checked per run; larger removals are reconciled over later syncs. Empty or unsupported page updates remove previously indexed content. This is polling, not a Pages delta feed: changes remain subject to the source’s sync interval. Listings stop with an error after 200 result pages, and failed or incomplete listings do not authorize removal of unseen pages. Pages with unknown publication metadata are skipped without preventing other pages from refreshing; the incomplete listing cannot authorize deletion. Unsupported web parts produce a warning; a page with no extractable text or description is reported as having no content.

​

SharePoint site-group permissions

This step is optional, and it applies to Custom Application connections only. Set it up when SharePoint documents get their access from classic site groups. Classic SharePoint site groups - Owners, Members, Visitors, and any custom group you create on a site - are not exposed through the Microsoft Graph API. Reading their membership requires the SharePoint REST API, which issues app-only tokens only to a client that authenticates with a certificate. A client secret is not enough: SharePoint rejects secret-minted app-only tokens with “Unsupported app only token”. Without a certificate, Serval cannot see who belongs to a site group, so it fails closed: documents whose access flows only through a site group stay hidden from the people who should see them. Serval generates the key pair for you, keeps the private key encrypted, and hands you only the public certificate to upload. The app registration also needs the Sites.Read.All and Files.Read.All Microsoft Graph application permissions with admin consent - the same permissions SharePoint knowledge ingestion requires (see Get your credentials). Grant those alongside the Office 365 SharePoint Online Sites.Read.All permission from the setup steps. Each API needs its own admin consent. The Graph permissions let Serval read documents, and the SharePoint permission lets Serval read site-group membership.

​

Retrieve a SharePoint policy document

The Fetch Latest Expense Policy Document from SharePoint workflow searches by name or keywords and retrieves the latest version of the top search result. Check the returned name and link to confirm that it selected the document you need. For supported text formats, such as plain text, CSV, JSON, and XML, the workflow returns up to 100,000 characters and indicates when the content is truncated. For Word, Excel, PowerPoint, PDF, and other binary formats, it returns the document link and metadata so you can open the file. It also returns the link when a text document has no download URL.

​

Verifying the connection

Serval runs ten health checks against your Microsoft Graph connection. Test Microsoft Graph Connection - Verifies Serval can authenticate by deliberately requesting a Graph resource that doesn’t exist: a “resource not found” reply proves the token is valid. This check tests only authentication, never permissions.

• Success: “Microsoft Graph authentication token is valid and working”
• Failure: “Could not get a valid authentication token for Microsoft Graph. Please check your Client ID, Client Secret, and Tenant ID configuration.”

List Microsoft Graph Users - Confirms Serval can list users from your directory (up to 100).

• Success: “Successfully listed [number] users from Microsoft Azure AD”
• Failure: “Unable to list users from Microsoft Azure AD.” followed by a status-specific hint - for a permissions (403) failure: “The Microsoft Graph app may not have the required permissions. Check the app’s permission configuration in Azure AD.”

List Microsoft Graph Groups - Confirms Serval can list groups from your directory (up to 100).

• Success: “Successfully listed [number] groups from Microsoft Azure AD”
• Failure: “Unable to list groups from Microsoft Azure AD.” followed by the same status-specific hints as the users check.

List Intune Managed Devices - Confirms Serval can list managed devices from Microsoft Intune (up to 10). Requires the DeviceManagementManagedDevices.Read.All permission.

• Success: “Successfully listed [number] managed devices from Microsoft Intune”
• Failure: “Unable to list managed devices from Microsoft Intune. This health check requires the DeviceManagementManagedDevices.Read.All permission.”

Diagnose Microsoft Graph Permissions - Probes every Graph capability Serval relies on (directory users and groups, SharePoint root site, site enumeration, site search, file reads, Intune devices) and reports which permission grants each one that is denied. Start here when several checks fail at once: it distinguishes a rejected token from missing permissions, and separates “SharePoint is unreachable” from “SharePoint is reachable but tenant-wide enumeration is not”. On a connection that signs in as a user (delegated), it skips site enumeration, which Microsoft only allows for app-only connections, and tells you to reconnect instead of adding application permissions.

• Success: “All [number] probed Microsoft Graph capabilities are permitted: …”
• Failure: a per-capability list, e.g. “Enumerate all SharePoint sites - grant Sites.Read.All (needed for discovering sites to offer as knowledge bases …)”, followed by where to grant it in Azure. Remember that a permission which is added but never admin-consented still returns 403.

List SharePoint Sites - Confirms Serval can enumerate the SharePoint sites available for knowledge base ingestion.

• Success: “Successfully listed [number] SharePoint sites”
• Failure (enumeration denied): explains that the app either holds Sites.Selected rather than Sites.Read.All, or the tenant restricts site enumeration - and that ingestion of sites already granted keeps working either way.

Ingest SharePoint Permissions - Confirms Serval can read SharePoint permission lists (site-level and per-file ACLs), which SharePoint knowledge permission ingestion depends on.

• Success: “SharePoint permissions are readable: read [number] site-level permission entries on …”
• Failure (blocked): if site enumeration is denied there is no site to probe, and the check reports itself blocked on List SharePoint Sites rather than guessing at a cause of its own.

Resolve User Group Memberships - Confirms Serval can resolve a user’s transitive Entra ID group memberships, which SharePoint knowledge permission enforcement performs at search time. Check SharePoint Online License - Verifies your Microsoft 365 tenant has a SharePoint Online license and the root site is accessible, which SharePoint knowledge base ingestion requires.

• Success: “SharePoint Online is licensed and the root site is accessible”
• Failure (no license): “This Microsoft 365 tenant does not have a SharePoint Online license. SharePoint knowledge base ingestion requires an active SPO license. Please assign a SharePoint Online license to the tenant, or remove the SharePoint knowledge source to stop sync failures.”
• Failure (permissions): “The Microsoft Graph app does not have permission to access SharePoint sites. Ensure the Sites.Read.All or Sites.ReadWrite.All permission is granted.”

Verify SharePoint Site-Group Access - Confirms Serval can read classic SharePoint site groups through the SharePoint REST API, which is what enables site-group permission ingestion. Only relevant if you set up SharePoint site-group permissions.

• Success: “SharePoint site groups are readable: found [number] site groups on “[site]” - site-group permission ingestion is enabled.”
• Failure (no certificate): “A certificate credential is required for SharePoint site-group ingestion.” Generate one in Serval and upload it to your app registration.
• Failure (certificate not uploaded): “The generated certificate has not been uploaded to your Azure app registration yet (Microsoft error AADSTS700027).” Upload the downloaded .cer under Certificates & secrets → Certificates and re-run the check.
• Failure (missing SharePoint API permission): “Serval authenticated with the certificate, but SharePoint rejected the request - the app registration is missing an application permission on the SharePoint API.” Grant Sites.Read.All on Office 365 SharePoint Online and re-run the check.
• Not applicable: on a Sign in with Microsoft connection, the check reports that site-group ingestion needs a Custom Application connection instead of failing. There’s no certificate to configure on such a connection.

​

Gotchas and troubleshooting

---

Need help? Contact support@serval.com for assistance with your Microsoft Graph integration.