> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/integrations/builtin/credentials/microsoftentraserviceprincipal.md). # Microsoft Entra Service Principal credentials Documentation for the Microsoft Entra Service Principal credentials. Use these credentials to authenticate Microsoft services in n8n, a workflow automation platform. The Microsoft Entra Service Principal credential gives n8n app-only access to Microsoft Graph. Instead of signing in as a person, n8n authenticates as an app registration that an administrator sets up once in the Microsoft Entra admin center. This suits unattended and shared workflows: there's no user session to expire and no per-user consent to manage. You can use these credentials to authenticate the following nodes: * [Microsoft Excel (OneDrive)](/integrations/builtin/app-nodes/n8n-nodes-base.microsoftexcel.md) * [Microsoft Excel (SharePoint)](/integrations/builtin/app-nodes/n8n-nodes-base.microsoftexcelsharepoint.md) * [Microsoft OneDrive](/integrations/builtin/app-nodes/n8n-nodes-base.microsoftonedrive.md) * [Microsoft OneDrive Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.microsoftonedrivetrigger.md) * [Microsoft Outlook](/integrations/builtin/app-nodes/n8n-nodes-base.microsoftoutlook.md) * [Microsoft Outlook Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.microsoftoutlooktrigger.md) * [Microsoft SharePoint](/integrations/builtin/app-nodes/n8n-nodes-base.microsoftsharepoint.md) * [Microsoft Teams](/integrations/builtin/app-nodes/n8n-nodes-base.microsoftteams.md) * [Microsoft Teams Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.microsoftteamstrigger.md) * [Microsoft To Do](/integrations/builtin/app-nodes/n8n-nodes-base.microsofttodo.md) {% hint style="info" %} **Node version requirements** The Microsoft Excel (OneDrive), Microsoft Outlook, Microsoft SharePoint, and Microsoft Teams nodes support this credential from version 2 of the node. The Microsoft Excel (SharePoint) node supports it from version 1. {% endhint %} ## Prerequisites * A Microsoft 365 organization tenant. Personal Microsoft accounts don't support application permissions. * Access to the [Microsoft Entra admin center](https://entra.microsoft.com/) as an administrator who can create app registrations and grant admin consent, or an administrator who can grant consent for you. ## Supported authentication methods * OAuth2 client credentials, using a client secret or a certificate (signed client assertion) ## Related resources Refer to Microsoft's documentation for more information: * [Get access without a user](https://learn.microsoft.com/en-us/graph/auth-v2-service): how app-only authentication works * [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) * [Grant tenant-wide admin consent to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent) ## How app-only access differs from OAuth2 With the OAuth2 Microsoft credentials, nodes act as the user who signed in. With the Service Principal credential, there's no signed-in user, which changes how you use the nodes: * **You choose who or what to act on.** Each node shows an extra required parameter when you select this credential: **Access As** (a user or drive) in Microsoft OneDrive, Microsoft OneDrive Trigger, and Microsoft Excel (OneDrive), **Mailbox** in Microsoft Outlook and Microsoft Outlook Trigger, and **User** in Microsoft To Do. Enter a user principal name (UPN), for example `jane@contoso.com`, or a user object ID. In the **Access As** field you can instead select **Drive** and enter a drive ID. There's no list picker for these fields: paste the value directly. In the Microsoft Teams nodes, the **Authentication** option is labelled **Service Principal (App-Only)**, and the **Task** operations hide the **Team** picker and replace the **Plan**, **Bucket**, and **Assigned To** pickers with plain ID fields. * **Permissions apply tenant-wide.** Application permissions aren't scoped to one user. For example, the `Mail.Send` application permission lets the app send as any mailbox in the tenant unless you restrict it with an [Exchange Online application access policy](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access). n8n recommends scoping tenant-wide mail permissions with an application access policy. * **Pickers see the whole tenant.** For example, the Microsoft Teams **Team** picker lists every team in the organization, not just teams the app has joined. * **Some operations aren't available.** The nodes hide anything that only exists for a signed-in user, such as drive search or Teams chats, or block it with an explanatory error. Refer to [Operations not available with app-only access](#operations-not-available-with-app-only-access). ## Set up the app registration Complete these steps in the Microsoft Entra admin center before you create the credential in n8n. To set up an app registration for the Microsoft SharePoint node from the command line instead, refer to [Provision a SharePoint app registration with the Azure CLI](/integrations/builtin/credentials/microsoftentraserviceprincipal-sharepoint.md). ### Register an app 1. Open the [Microsoft Entra admin center](https://entra.microsoft.com/) and go to **Entra ID** > **App registrations**. 2. Select **New registration**. 3. Enter a **Name** for your app, for example `n8n service principal`. 4. In **Supported account types**, select **Accounts in this organizational directory only**. You don't need a redirect URI. 5. Select **Register**. 6. On the app's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**. You'll need both in n8n. ### Add application permissions 1. In your app registration, select **API permissions** > **Add a permission** > **Microsoft Graph**. 2. Select **Application permissions**. Don't select **Delegated permissions**: app-only access ignores delegated scopes, and the permission names differ between the two types. 3. Add the permissions for the nodes you plan to use. Refer to [Required application permissions by node](#required-application-permissions-by-node). 4. Select **Add permissions**. ### Grant admin consent 1. On the **API permissions** page, select **Grant admin consent for ``** and confirm. 2. Check that the **Status** column shows **Granted** for every permission. {% hint style="warning" %} **Missing admin consent fails with a generic permissions error** If nobody grants admin consent, everything looks fine at first: the credential saves and Microsoft still issues a token. But the token contains no permissions, so every operation fails with a generic Microsoft Graph permissions error, such as HTTP 403 `Authorization_RequestDenied` ("Insufficient privileges to complete the operation"). The credential values aren't the problem. To fix it, open the app registration's **API permissions** page, check that every permission shows **Granted**, and grant admin consent if not. n8n caches the access token, so retest the credential after granting consent. If it still fails, recreate the credential to force a fresh token. {% endhint %} ### Create a client secret 1. In your app registration, select **Certificates & secrets** > **Client secrets** > **New client secret**. 2. Enter a **Description**, for example `n8n credential`, and choose an expiry. 3. Select **Add**. 4. Copy the secret's **Value** right away. Microsoft only shows it once. ### Create the credential in n8n In n8n, create a new **Microsoft Entra Service Principal** credential and fill in these fields: 1. **Directory (Tenant) ID**: the Directory (tenant) ID from your app registration's **Overview** page. You can also use a verified domain, for example `contoso.onmicrosoft.com`. 2. **Application (Client) ID**: the Application (client) ID from your app registration's **Overview** page. 3. **Client Secret**: the client secret value you copied. 4. **Microsoft Graph API Base URL**: keep **Global** unless your tenant is in a sovereign cloud. Refer to [Sovereign cloud environments](#sovereign-cloud-environments). To authenticate with a certificate instead of a client secret, set **Authentication** to **Certificate** and paste your private key and certificate. The certificate must be uploaded to the app registration under **Certificates & secrets**. Save and test the credential. From n8n 2.40.0, the connection test only checks that the app can sign in, so it needs no application permission of its own. A missing permission or missing admin consent passes the test and fails when a node runs instead. Before n8n 2.40.0, the test read your organization from Microsoft Graph, so it also needed the `Organization.Read.All` (or `Directory.Read.All`) application permission. ## Required application permissions by node Add the application permissions for every node you plan to use, then grant admin consent. All permissions in this table are Microsoft Graph **Application** permissions, not Delegated permissions. | Node | Required application permissions | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | All nodes, before n8n 2.40.0 (credential test) | `Organization.Read.All` or `Directory.Read.All`. From n8n 2.40.0, the credential test needs no application permission. | | Microsoft OneDrive and Microsoft OneDrive Trigger | `Files.ReadWrite.All` (`Files.Read.All` is enough for read-only operations and the trigger) | | Microsoft Excel (OneDrive) | `Files.ReadWrite.All` | | Microsoft Outlook | `Mail.ReadWrite` (messages, drafts, folders, and attachments; also required by Reply and Draft: Send, which create or update a draft before sending), `Mail.Send` (send and reply), `Calendars.ReadWrite` (calendars and events), `Contacts.ReadWrite` (contacts), `MailboxSettings.Read` (loads the Categories dropdown). Add only the ones your operations use. | | Microsoft Outlook Trigger | `Mail.Read` | | Microsoft SharePoint | `Sites.Read.All` for read operations, `Sites.ReadWrite.All` for write operations. For items in document libraries, `Files.Read.All` (Item: Get) or `Files.ReadWrite.All` (Item: Delete) also works. To limit the app to chosen sites, grant `Sites.Selected` instead and refer to [Grant access per site](#grant-access-per-site). | | Microsoft Teams and Microsoft Teams Trigger | `Team.ReadBasic.All`, plus the permissions for your operations in the table below | | Microsoft To Do | `Tasks.ReadWrite.All` | The Microsoft Teams node needs `Team.ReadBasic.All` to list teams, plus a permission per operation: | Teams operation | Application permission | | ------------------------------------------------ | ------------------------------- | | Channel: Get, Get Many | `Channel.ReadBasic.All` | | Channel: Create | `Channel.Create` | | Channel: Update | `ChannelSettings.ReadWrite.All` | | Channel: Delete | `Channel.Delete.All` | | Channel Message: Get, Get Many, Get Many Replies | `ChannelMessage.Read.All` | | Task: all operations | `Tasks.ReadWrite.All` | | Trigger: New Channel | `Channel.ReadBasic.All` | | Trigger: New Channel Message | `ChannelMessage.Read.All` | | Trigger: New Team Member | `TeamMember.Read.All` | ## Grant access per site Tenant-wide `Sites.Read.All` or `Sites.ReadWrite.All` gives the app access to every SharePoint site in your organization. If your security team prefers to grant access site by site, use the `Sites.Selected` permission instead. The Microsoft SharePoint node (from version 2) and the Microsoft Excel (SharePoint) node support it. Per-site access takes two steps. The second step has no page in the Entra admin center or the SharePoint admin center, which is why many setups miss it: 1. **Add the permission and grant admin consent.** On the app registration, add the `Sites.Selected` application permission in place of the tenant-wide `Sites.*` permissions, and grant admin consent. 2. **Grant the app access to each site.** An administrator calls Microsoft Graph's site permissions endpoint once per site the app should reach: ```http POST https://graph.microsoft.com/v1.0/sites//permissions Content-Type: application/json { "roles": ["write"], "grantedToIdentities": [ { "application": { "id": "", "displayName": "" } } ] } ``` Use the `read` role for read-only access, or `write` for the node's write operations. You can send the request from [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) or any tool that can call Microsoft Graph. SharePoint administrators can use PnP PowerShell's [`Grant-PnPEntraIDAppSitePermission`](https://pnp.github.io/powershell/cmdlets/Grant-PnPEntraIDAppSitePermission.html) instead. For the whole path from an empty tenant to a granted site, refer to [Provision a SharePoint app registration with the Azure CLI](/integrations/builtin/credentials/microsoftentraserviceprincipal-sharepoint.md). Whoever sends the request needs permission to manage site permissions: in Graph Explorer, open **Modify permissions** and consent to `Sites.FullControl.All` before sending. A 403 `Access denied` response to this request means the account or tool sending it lacks that permission, not the app you're granting access to. To find a site's ``, request it by hostname and path: `GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite`. With `Sites.Selected`, the nodes can't search or list sites, because Microsoft Graph doesn't support site discovery without a tenant-wide read permission. Choose the site by pasting its URL or ID instead. A missing per-site grant surfaces as a 403 error on the operation, naming the permission it needs. ## Operations not available with app-only access Some Microsoft Graph operations only exist for a signed-in user. When you select this credential, the nodes hide or block them with an explanatory error. Use an OAuth2 credential if you need them: * **Microsoft OneDrive**: File: Search and Folder: Search. Microsoft Graph only offers drive search to signed-in users. * **Microsoft Excel (OneDrive)**: Workbook: Get Many, and searching for a workbook by name in the **Workbook** field. Set the field to **By ID** instead. * **Microsoft Teams**: the whole Chat Member, Chat Message, and Online Meeting resources. Channel Message: Create and Reply. Task: Get Many in Group Member mode. * **Microsoft Teams Trigger**: the New Chat and New Chat Message events, and the watch-all options. Pick a specific team or channel instead. The Microsoft Outlook, Microsoft Outlook Trigger, Microsoft SharePoint, and Microsoft To Do nodes have no blocked operations. In the Microsoft SharePoint node, site search needs the `Sites.Read.All` application permission; with only `Sites.Selected`, choose the site by URL or ID instead. File: Share and Folder: Share in Microsoft OneDrive stay available, but creating sharing links app-only can need extra tenant or admin configuration. The node shows a notice on these operations. ## Sovereign cloud environments Select the **Microsoft Graph API Base URL** that matches your tenant's cloud environment: * **Global ()**: standard Microsoft 365 tenants (default) * **US Government ()**: Azure US Government tenants, including GCC High * **US Government DOD ()**: Azure US Government Department of Defense tenants * **China ()**: Microsoft 365 operated by 21Vianet in China n8n derives the matching sign-in endpoint automatically, for example `login.microsoftonline.us` for the US Government clouds and `login.partner.microsoftonline.cn` for China, so you don't need to configure any token or authorization URLs. Complete the app registration in your cloud's own Entra admin center, and the nodes route all Microsoft Graph calls through the endpoint you selected. ## Common issues Here are common errors and issues with the Microsoft Entra Service Principal credentials: * **The credential test passes but every operation fails.** From n8n 2.40.0, the connection test only checks that the app can sign in, not which permissions it holds. A missing application permission, missing admin consent, or a missing per-site grant only surfaces when a node runs. * **Every operation fails with a generic permissions error.** This almost always means a missing application permission or missing admin consent. Refer to the warning in [Grant admin consent](#grant-admin-consent). The Microsoft SharePoint (version 2) and Microsoft Excel (SharePoint) nodes show a clearer message instead, naming the permission the operation needs: "The app registration is missing a consented application permission for this operation." * **Authentication fails with "Microsoft Entra authentication did not return an access token".** Microsoft rejected the token exchange, for example AADSTS7000215 (invalid client secret), AADSTS7000222 (expired client secret), or AADSTS700027 (rejected certificate assertion). Check that you pasted the client secret's **Value** rather than its Secret ID, that the secret hasn't expired, and, for certificate authentication, that the private key matches the certificate uploaded to the app registration. * **Permission or secret changes don't take effect right away.** n8n caches the access token. Retest the credential after granting consent or rotating a secret, and recreate it if the cached token keeps failing. * **"Microsoft Entra tenant ID is not a valid GUID or domain."** Enter the Directory (tenant) ID GUID from the app registration's **Overview** page, or a verified domain such as `contoso.onmicrosoft.com`. Don't enter a URL.