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 (OAuth 2.0 with delegated permissions - recommended), or a Custom Application (OAuth 2.0 client credentials with application permissions) for advanced setups. 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 or school account through Serval’s official multi-tenant Entra application - personal Microsoft accounts are not supported.
1

Pick the right account

Use a work or school 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 or school 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 or school 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.

​
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

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 application permissions with admin consent - the same permissions SharePoint knowledge ingestion requires (see Get your credentials).

​
Verifying the connection

Serval runs six 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.”
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.
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 work or school accounts only - the connect modal explicitly says “Connect using your Microsoft work or school account.” Personal Microsoft accounts cannot be used. (Details: Microsoft identity platform endpoints.)
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.
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.