Skip to main content

​
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.
Looking for Microsoft Teams help desk and channel automation, or Exchange Online management? Those are separate integrations with their own pages: Microsoft Teams and Exchange Online.

​
Get your credentials

There is nothing to create in Azure for this method. You connect using a Microsoft work account through Serval’s official multi-tenant Entra application - personal Microsoft accounts are not supported.
1

Pick the right account

Use a work account that is allowed to consent to applications in your organization.
2

Plan for org-wide use

For the integration to work organization-wide, the person connecting must check Consent on behalf of your organization on Microsoft’s “Permissions requested” screen - this requires an admin. Microsoft re-confirms the full permission set on every connect and reconnect.

​
Connect in Serval

1

Choose Sign in with Microsoft

In the Microsoft Graph connect modal, choose to connect with your Microsoft work account.
2

Select permission presets

Every connection requests a base set of read permissions (your profile and basic details of other users, directory data, groups and group memberships, Teams team and channel details, channel messages, SharePoint and OneDrive content, plus offline access so Serval can refresh tokens automatically). On top of that, check the presets you need:Need something not in a preset? Use the All permissions search to add individual permissions from the full catalog.
3

Sign in and consent

Sign in with your work account. Serval always asks Microsoft to re-confirm permissions, so you’ll see the full list on Microsoft’s “Permissions requested” screen. For org-wide use, check Consent on behalf of your organization, then accept.
4

Done

Serval detects your tenant ID and tenant name automatically and stores the granted permissions. Tokens refresh automatically - no maintenance needed.
Reconnecting pre-selects your currently granted permissions, so adding a preset later is just: reconnect, check the new box, re-consent.

​
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.
Entra ID’s Active users list includes guests whose sign-in is enabled, so a guest can appear both there and under Guest users. The Exclude guest accounts switch keys off userType, not the sign-in state.

​
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.
Serval's SharePoint site-group permissions section showing a configured certificate with its expiry date, Download certificate and Regenerate buttons, the certificate thumbprint, and the numbered Set up in Azure steps

The SharePoint site-group permissions section - API Integration → Advanced

1

Generate the certificate in Serval

Open the Microsoft Graph integration, go to API Integration → SharePoint site-group permissions, and click Generate certificate.
2

Download the .cer file

Click Download certificate (.cer). This file holds only the public certificate - the half Azure needs.
3

Upload it to your app registration

Open App registrations in the Azure Portal, then go to your app → Certificates & secrets → Certificates → Upload certificate, and upload the .cer file. Serval’s Open Certificates & secrets in Azure link takes you straight to the right blade for your app.
4

Confirm the thumbprint

Check that the thumbprint Azure lists matches the thumbprint Serval shows next to the certificate.
5

Grant the SharePoint API permission

The certificate proves who Serval is. A SharePoint permission decides what Serval may read. That permission lives on a second API, separate from the app’s Microsoft Graph permissions.In the Azure Portal, open your app → API permissions → Add a permission → APIs my organization uses → Office 365 SharePoint Online → Application permissions → Sites.Read.All. Then click Grant admin consent for [Your Organization].Sites.Read.All on this API is enough to read site-group membership. Broader SharePoint permissions, such as Sites.FullControl.All, grant far more access than site-group ingestion needs.
6

Run the health check

Back in Serval, run the Verify SharePoint Site-Group Access health check to confirm Serval can read site-group membership.
Serval stores the private key encrypted and never exposes it - the download only ever contains the public certificate. Regenerating invalidates the previous certificate, so you must upload the new .cer to Azure and remove the old one.
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.

​
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 application 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”.
  • 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.
If the connection test is green but the users, groups, Intune, or SharePoint checks fail, your credentials are fine - it’s a permissions problem. The connection test only validates authentication. Reconnect with the right presets (Sign in with Microsoft) or add the missing application permissions and re-grant admin consent (Custom Application).

​
Gotchas and troubleshooting

The form field is literally labeled Client secret value - paste the secret’s Value, not the Secret ID. The value is only visible in Azure immediately after creation. Expired secrets are surfaced explicitly (AADSTS700082):
The client secret for application ‘<client ID>’ has expired. Please generate a new client secret in the Azure Portal and update it in Serval.
Other authentication failures you may see (invalid_client, then the generic fallback):
Client authentication failed for application ‘<client ID>’. Please verify the Client ID and Client Secret are correct.
Failed to authenticate with Microsoft Graph for tenant ‘<instance name>’. Please verify your Client ID, Client Secret, and Tenant ID in the Azure Portal.
Fix: create a new client secret in Certificates & secrets, copy its Value immediately, and update it in Serval.
The scope presets in the connect modal only apply to the Sign in with Microsoft (delegated) flow. A Custom Application uses application permissions: its effective access is exactly the application permissions granted on the app registration. To get the equivalent of a preset, add the matching permissions under API permissions → Microsoft Graph → Application permissions and grant admin consent.
The OAuth flow uses Microsoft’s multi-tenant “organizations” sign-in endpoint, which accepts organizational work accounts only. Personal Microsoft accounts cannot be used. (Details: Microsoft identity platform endpoints.)
If List SharePoint Sites, Ingest SharePoint Permissions, and Verify SharePoint Site-Group Access all fail with a bare accessDenied 403, that is usually one cause, not three: the app cannot enumerate sites tenant-wide, and the other two checks need a site to probe before they can test anything.The two configurations that produce it are the app holding Sites.Selected instead of Sites.Read.All, and a tenant that restricts site enumeration or search. In both cases SharePoint knowledge ingestion of sites already granted to the app keeps working - only automatic site discovery is affected.Fix: grant Sites.Read.All under App registrations → your app → API permissions → Microsoft Graph → Application permissions, then Grant admin consent. If Sites.Selected is intentional, these checks cannot verify your sites automatically - confirm ingestion health on the knowledge base itself, and run Diagnose Microsoft Graph Permissions to see the full capability breakdown.
The List Intune Managed Devices check fails without the DeviceManagementManagedDevices.Read.All permission. Check the Microsoft Intune (Read-only) preset during OAuth connect, or grant the DeviceManagement* application permissions on a custom app. The Read/write preset additionally enables privileged device actions (wipe, retire) via DeviceManagementManagedDevices.PrivilegedOperations.All.
SharePoint knowledge ingestion requires an active SharePoint Online license on the tenant - the SharePoint license health check verifies this by probing the root site. Either assign an SPO license or remove the SharePoint knowledge source to stop the sync failures. Access also requires the Sites.Read.All (or Sites.ReadWrite.All) permission.
Generating the certificate in Serval is only half the setup - Entra rejects the token request until the matching public certificate is registered on the app registration. Serval reports:
This certificate has not been uploaded to your Azure app registration yet.
Fix: download the .cer from API Integration → SharePoint site-group permissions, upload it in Azure under App registrations → your app → Certificates & secrets → Certificates, confirm the thumbprint matches, then re-run the Verify SharePoint Site-Group Access health check. Full walkthrough: SharePoint site-group permissions.
A 401 with an empty {} body means Entra accepted the certificate and issued a token. SharePoint then rejected that token, because it carries no SharePoint role. The cause is a missing application permission on the Office 365 SharePoint Online API. That grant is separate from the app’s Microsoft Graph permissions, so the Graph Sites.Read.All grant doesn’t satisfy it.Fix: in the Azure Portal, open your app → API permissions → Add a permission → APIs my organization uses → Office 365 SharePoint Online → Application permissions → Sites.Read.All. Click Grant admin consent, then re-run the Verify SharePoint Site-Group Access health check. Sites.Read.All is enough. Broader SharePoint permissions, such as Sites.FullControl.All, grant more access than the check requires. Full walkthrough: SharePoint site-group permissions.
Serval fails closed on permissions it cannot resolve. Classic site-group membership is unreadable through Microsoft Graph, so until you configure SharePoint site-group permissions, any document whose only grant comes from a site group stays hidden. A “Sign in with Microsoft” connection cannot do this - certificate credentials exist only on Custom Application connections.
This is intentional. Serval ingests Entra Security Groups (access control; members can include users, devices, service principals, and nested groups; full sync every 16 hours) and Entra Microsoft 365 Groups (collaboration; user members only; full sync every 8 hours, since collaboration groups change more often) as distinct resource types with different sync schedules and approval semantics. Don’t expect them to be merged.
For Sign in with Microsoft: just reconnect. Serval pre-selects your currently granted permissions as checked presets plus individual extras, and Microsoft re-confirms the full set on every connect - so check the new preset, re-consent, done. For a Custom Application: add the application permissions on the app registration and re-grant admin consent; no change is needed in Serval.
They live elsewhere. Microsoft Teams help desk and channel automation is the dedicated Microsoft Teams integration, and Exchange Online (PowerShell) management is the Exchange Online integration - each has its own docs page.
Need help? Contact support@serval.com for assistance with your Microsoft Graph integration.