> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Graph

> Connect Microsoft 365 and Entra ID to Serval to sync users, groups, and enterprise apps, manage Intune devices and licenses, automate mail and calendar, and index SharePoint and OneDrive for the Serval knowledge base.

## 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

| Capability                                   | Description                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Entra ID user directory sync                 | Ingests all Entra ID (Azure AD) users on a recurring schedule so they are available throughout Serval.                                                                                                                                                                                                                                           |
| Entra group sync and membership provisioning | Syncs Entra Security Groups (access control - full sync every 16 hours, delta every 4) and Entra Microsoft 365 Groups (collaboration - full sync every 8 hours, delta every 4) as separate resource types, each with a Member entitlement. Serval can add or remove users from either group type for access requests and provisioning workflows. |
| Enterprise application sync                  | Ingests Entra enterprise applications and their app role assignments, mapping who has access to which app.                                                                                                                                                                                                                                       |
| Microsoft Intune device management           | Read Intune managed devices, configuration policies, apps, RBAC, and service settings. With the read/write preset, manage Intune and perform privileged device actions such as wipe and retire.                                                                                                                                                  |
| SharePoint and OneDrive knowledge base       | Indexes SharePoint sites and OneDrive document libraries as a Serval knowledge source for AI answers.                                                                                                                                                                                                                                            |
| License and subscription management          | Read directory and subscription data, and read or update license assignments from workflows.                                                                                                                                                                                                                                                     |
| Mail and calendar automation                 | Read, write, and send mail and manage calendars from workflows.                                                                                                                                                                                                                                                                                  |
| Groups, Teams, and guest access actions      | Create teams, manage groups, and invite or manage external guests in Microsoft Teams teams and channels from workflows.                                                                                                                                                                                                                          |
| Full Microsoft Graph API access              | Any Microsoft Graph API endpoint can be called from workflows through Serval's authenticated proxied requests, subject to the permissions granted to the connection.                                                                                                                                                                             |

Anything defined in the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/api/overview) can be accessed through Serval.

<Note>
  Looking for Microsoft Teams help desk and channel automation, or Exchange Online management? Those are separate integrations with their own pages: [Microsoft Teams](/sections/integrations/microsoft-teams) and [Exchange Online](/sections/integrations/exchange-online).
</Note>

## Get your credentials

<Tabs>
  <Tab title="Sign in with Microsoft (recommended)">
    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.

    <Steps>
      <Step title="Pick the right account">
        Use a work or school account that is allowed to consent to applications in your organization.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Custom Application">
    Create an app registration in Microsoft Entra ID with a client secret and Microsoft Graph **application** permissions, then grant admin consent. See Microsoft's guide: [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

    <Steps>
      <Step title="Open the portal">
        Go to the [Azure Portal](https://portal.azure.com) or the [Microsoft Entra admin center](https://entra.microsoft.com) and sign in with admin privileges.
      </Step>

      <Step title="Create the app registration">
        Navigate to **App registrations** in the left sidebar and click **New registration**. Configure: Name e.g. "Serval Microsoft Graph Integration"; Supported account types: **Accounts in this organizational directory only**; Redirect URI: leave blank. Click **Register**.
      </Step>

      <Step title="Copy the IDs">
        From the app's **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID** - you'll paste both into Serval's connect form.
      </Step>

      <Step title="Create a client secret">
        Navigate to **Certificates & secrets**, click **New client secret**, choose an expiration, and click **Add**. Immediately copy the secret **Value** - this is the "Client secret value" field in Serval.

        <Warning>
          Copy the secret **Value**, not the Secret ID. The value is only visible immediately after creation - if you navigate away, you'll need to create a new secret.
        </Warning>
      </Step>

      <Step title="Add application permissions">
        Navigate to **API permissions** → **Add a permission** → **Microsoft Graph** → **Application permissions**, and add the permissions your use cases need (e.g. `User.Read.All`, `Group.Read.All`, `Directory.Read.All`, `Sites.Read.All`, `Files.Read.All`, `DeviceManagementManagedDevices.Read.All`, `LicenseAssignment.ReadWrite.All`). The integration's effective permissions are exactly what you grant here - see the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for what each permission allows.
      </Step>

      <Step title="Grant admin consent">
        Click **Grant admin consent for \[Your Organization]** and confirm. Verify every permission shows "Granted for \[Your Organization]". Granting admin consent requires an appropriately privileged role - see [Microsoft's prerequisites](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal#prerequisites).

        <Note>
          Without this step, none of the permissions take effect and the connection will fail with a consent error.
        </Note>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Connect in Serval

<Tabs>
  <Tab title="Sign in with Microsoft (recommended)">
    <Steps>
      <Step title="Choose Sign in with Microsoft">
        In the Microsoft Graph connect modal, choose to connect with your Microsoft **work or school account**.
      </Step>

      <Step title="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:

        | Preset                                           | What it enables                                                                                                                                                                                 |
        | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | **OneDrive and SharePoint** (checked by default) | Gather knowledge from OneDrive and SharePoint (`Files.Read`, `Files.Read.All`)                                                                                                                  |
        | **Manage Licenses and Subscriptions**            | `Directory.Read.All`, `LicenseAssignment.Read.All`, `LicenseAssignment.ReadWrite.All`, `Subscription.Read.All`                                                                                  |
        | **Mail and Calendar**                            | `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`                                                                                                             |
        | **Groups and Collaboration**                     | `Group.Read.All`, `Group.ReadWrite.All`, `Team.Create`, `Team.ReadBasic.All`                                                                                                                    |
        | **Teams Guest Access**                           | `User.Invite.All`, `User.Read.All`, `Team.ReadBasic.All`, `TeamMember.ReadWrite.All`, `ChannelMember.ReadWrite.All`, `Channel.ReadBasic.All`, `GroupMember.ReadWrite.All`                       |
        | **Microsoft Intune (Read-only)**                 | `DeviceManagementManagedDevices.Read.All`, `DeviceManagementConfiguration.Read.All`, `DeviceManagementApps.Read.All`, `DeviceManagementServiceConfig.Read.All`, `DeviceManagementRBAC.Read.All` |
        | **Microsoft Intune (Read/write)**                | The read/write equivalents of the above, plus `DeviceManagementManagedDevices.PrivilegedOperations.All` for privileged actions like wipe and retire                                             |

        Need something not in a preset? Use the **All permissions** search to add individual permissions from the full catalog.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Done">
        Serval detects your tenant ID and tenant name automatically and stores the granted permissions. Tokens refresh automatically - no maintenance needed.
      </Step>
    </Steps>

    <Tip>
      Reconnecting pre-selects your currently granted permissions, so adding a preset later is just: reconnect, check the new box, re-consent.
    </Tip>
  </Tab>

  <Tab title="Custom Application">
    Fill in Serval's **Configure Microsoft Graph** form. All four fields are required.

    <Steps>
      <Step title="Instance Name">
        A descriptive name for this integration instance. Free text; placeholder "e.g., My Microsoft Graph".
      </Step>

      <Step title="Directory (tenant) ID">
        The tenant GUID from the app registration's Overview page; placeholder "e.g., 12345678-1234-1234-1234-34567890abcd". If it's wrong, Serval reports a Microsoft AADSTS50034 error:

        > The tenant '\<tenant ID>' does not exist or could not be found.
        > Please verify the Tenant ID in the Azure Portal.
      </Step>

      <Step title="Application (client) ID">
        The application GUID from the app registration's Overview page; placeholder "e.g., 12345678-1234-1234-1234-34567890abcd". If Microsoft can't find the app (error AADSTS700016), Serval reports:

        > The Microsoft application with client ID '\<client ID>' was not found in the directory '\<instance name>'.
        > This can happen if:
        > • The application has not been installed by an administrator
        > • The application has not been consented to by any user
        > • You may have provided the wrong Client ID
        > • You may have provided the wrong Tenant ID
        >
        > Please verify your Client ID and Tenant ID in the Azure Portal.
      </Step>

      <Step title="Client secret value">
        A password field; placeholder "Value from App registration, Certificates and secrets". Paste the secret **Value** (not the Secret ID). If the secret is wrong (error AADSTS7000215), Serval reports:

        > The client secret provided for application '\<client ID>' is invalid.
        > Please verify the client secret in the Azure Portal and update it in Serval.
      </Step>
    </Steps>

    <Note>
      **Editing later:** the stored client secret is shown obfuscated when you reopen the form. On update, leaving any field blank keeps its existing value - only fill in what you want to change. Each error message above is also followed by the original Microsoft error detail, which includes the AADSTS code.
    </Note>
  </Tab>
</Tabs>

## Verifying the connection

Serval runs five 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."

<Tip>
  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).
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Connection fails with a consent error (AADSTS65001 or unauthorized_client)">
    Admin consent is required either way. With Sign in with Microsoft, org-wide operation requires checking **Consent on behalf of your organization** on Microsoft's "Permissions requested" screen. With a Custom Application, every Microsoft Graph application permission must be explicitly granted admin consent in the Azure portal - the integration can only do what was consented on the app registration. Serval surfaces these as (AADSTS65001):

    > The user or administrator has not consented to use the application '\<client ID>'.
    > An administrator must grant consent for the application in the Azure Portal.

    or (unauthorized\_client):

    > The client is not authorized to request an access token for tenant '\<instance name>'.
    > This typically means:
    > • The application is not properly configured in Azure AD
    > • Required API permissions have not been granted
    > • Admin consent may be required
    >
    > Please check the application configuration in the Azure Portal.

    **Fix:** in the Azure portal, open the app registration's **API permissions** page and click **Grant admin consent for \[Your Organization]**.
  </Accordion>

  <Accordion title="Client secret rejected or expired">
    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.
  </Accordion>

  <Accordion title="Custom Application ignores the permission presets">
    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.
  </Accordion>

  <Accordion title="Sign in with Microsoft rejects a personal Microsoft account">
    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](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols#endpoints).)
  </Accordion>

  <Accordion title="The Intune health check fails even though the connection is green">
    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`.
  </Accordion>

  <Accordion title="SharePoint knowledge sync keeps failing">
    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.
  </Accordion>

  <Accordion title="Security Groups and Microsoft 365 Groups appear as two separate resources">
    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.
  </Accordion>

  <Accordion title="Need more permissions after connecting">
    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.
  </Accordion>

  <Accordion title="Teams help desk or Exchange Online features seem missing">
    They live elsewhere. Microsoft Teams help desk and channel automation is the dedicated [Microsoft Teams integration](/sections/integrations/microsoft-teams), and Exchange Online (PowerShell) management is the [Exchange Online integration](/sections/integrations/exchange-online) - each has its own docs page.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Microsoft Graph integration.