> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/microsoft-sharepoint/configure-sharepoint-authentication-and-site-access.md).

# Configure SharePoint authentication and site access

## Which SharePoint Connection Should I Use?

When creating a SharePoint connection in StackAI, there are 3 available methods: through OAuth connection, an App-only (client credentials) connection, or an NTLM connection.

* **OAuth Connection (Delegated Access)**: An OAuth connection uses Microsoft’s OAuth 2.0 flow to authenticate on behalf of a user. StackAI accesses SharePoint using the permissions of the signed-in user.
* **App-Only Connection**: An App-Only connection uses an Azure App Registration with application permissions. So StackAI authenticates as an application, not a user.
* **NTLM Connection**: This is a legacy Microsoft authentication protocol commonly used in on-prem SharePoint or environments that do not support OAuth.

We recommend using a **SharePoint OAuth2 or App-Only Connection:**

* Use OAuth if you want access scoped to individual users.
* Use App-only if you want centralized control over permissions, or want access scoped to enterprise service accounts.

***

## Set up App-Only Connection

Create an application for the StackAI connection with Microsoft Graph **Sites.Selected** application permission. Grant this application access to each required site.

Choose how your administrator will grant site access before you create additional applications:

* **PnP PowerShell:** use your tenant's PnP app registration and an authorized administrator account. This route does not need the Admin App described in Step 1.
* **Microsoft Graph API:** use a separate Admin App with the permission needed to grant site access. Keep its credentials with your IT team; do not enter them in the StackAI connection.

Skip Step 1 if you use PnP PowerShell or already have the administrative application. Both routes use the StackAI SharePoint App created in Step 2.

### Step 1: Set up an Admin App (Optional)

1. Go to App Registrations on Microsoft Azure ([link](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade))
2. Create a new app registration
   1. Add a name to the app
   2. Select “Accounts in this organizational directory only (`your org name` only - Single tenant)
   3. Register

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F5cD6Qlq9cSTLD9Za2DBl%2Fimage.png?alt=media)

3. Set up the app API permissions:

Under `Manage` go to `API permissions`

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F9pL50V3vU0apkkK0gzJN%2Fimage.png?alt=media)

Click on “Add a permission”

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FXwu0cBzVeJe2kL2zcdZ4%2Fimage.png?alt=media)

Select Microsoft Graph

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F2TdA9GXREgIPVAztsdzD%2Fimage.png?alt=media)

Select “Application permissions”

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fik66mUcP8kOovgfqBnUr%2Fimage.png?alt=media)

Add `Sites.FullControl.All` permission

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FsyqU8RhB90o6Q2qEps3V%2Fimage.png?alt=media)

Grant admin consent to the app

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FhsjIWr8WKjDx2UAjaMl9%2Fimage.png?alt=media)

### Step 2: Register a SharePoint app in Azure Active Directory (Microsoft Entra)

1. Sign into the [Azure Portal](https://portal.azure.com/) with admin credentials.
2. Navigate to **Azure Active Directory > App registrations**.
3. Click **New registration**.
4. Enter your application name
5. Select “Accounts in this organizational directory only (`your org name` only - Single tenant)
6. Leave the redirect URI unset for this app-only client-credentials connection. The OAuth connector has a separate redirect-URI setup below.
7. Click **Register**.

### Step 3: Configure Permission Scope

1. Navigate to **API permissions** > **Add a permission** > **Microsoft Graph**

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FHaGB8KoYI8tvxjRPp487%2Fimage.png?alt=media)

2. Select **Application permissions** and add `Sites.Selected`. Step 5 grants read or write access to each required site.

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FxvTubjxPcoDM2zwx2hKa%2Fimage.png?alt=media)

3. Grant admin consent

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F0h6rOoidRfKGd164NdlC%2Fimage.png?alt=media)

If admin consent is not granted, the connection may appear as **Unhealthy** in StackAI.

{% hint style="info" %}
**Notes on SharePoint App permission**

Use `Sites.Selected` to restrict the application to explicitly granted sites. Administrator consent alone does not provide access; complete the site grant in Step 5.

If you need tenant-wide access instead, review `Sites.Read.All` for reading or `Sites.ReadWrite.All` for reading and writing with your Microsoft administrator. These permissions are broader than individual site grants.

With `Sites.Selected`, site discovery may be unavailable. Enter the site's full ID instead of relying on a site dropdown. The permission grant must cover the target site.

See Microsoft's [selected permissions guide](https://learn.microsoft.com/en-us/graph/permissions-selected-overview) for the consent and resource-grant requirements.
{% endhint %}

### Step 4: Create Client Secret

1. Under your app registration, go to **Certificates & secrets** > New client secret

   ![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FCWCQvzViaaBJy1nbVCSa%2Fimage.png?alt=media)
2. Add a description and select an expiry period.
3. Copy the generated **secret** **value** (not secret ID) immediately and store it securely. This is your **`sharepoint_client_secret`**. You won't be able to view it again after leaving the page.

   ![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FvXCm84FXAog31ugkQYrQ%2Fimage.png?alt=media)

### Step 5. Grant SharePoint Site Access to the SharePoint App

Each SharePoint site has a unique set of Microsoft Graph IDs. We will use these identifiers to grant permission to the specific sites.

For a sample site `https://<your organization domain>.sharepoint.com/sites/<site name>`, there are three components to construct the full ID.

1. Host Name: This is in the site URL. Example: `<your organization domain>.sharepoint.com`
2. Site Collection ID:
   1. Add `_api/site/id` to the end of the site URL. Example: `<your organization domain>.sharepoint.com/sites/<site name>/_api/site/id`
   2. Press Return key to run this url, and you will see an XML file. The `Guid` field is the Site Collection ID.

```xml
<d:Id xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
xmlns:georss="http://www.georss.org/georss" 
xmlns:gml="http://www.opengis.net/gml" 
m:type="Edm.Guid">xxxxxxxxxxxx</d:Id>
```

3. Site Web ID:
   1. Add `_api/web/id` to the end of the site URL. Example: `<your organization domain>.sharepoint.com/sites/<site name>/_api/web/id`
   2. Press Return key to run this url, and you will see an XML file. The `Guid` field is the Site Web ID.

```xml
<d:Id xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
xmlns:georss="http://www.georss.org/georss" 
xmlns:gml="http://www.opengis.net/gml" 
m:type="Edm.Guid">xxxxxxxxxx</d:Id>
```

4. Construct the full ID: Append all three identifiers together in the order of `Host Name,Site Collection ID,Site Web ID` separated by comma. Example: `<your organization domain>.sharepoint.com,12345678-90ab-cdef-1234-567890abcdef,abcdef12-3456-7890-abcd-ef1234567890`

Once you have the site ID, grant the StackAI SharePoint App access to that site. There are two ways to do this, and they have the same end result:

* **Option A: PnP PowerShell** (recommended). One command per site, and no access token to obtain or copy between commands. Does not require the Admin App from Step 1.
* **Option B: Microsoft Graph API.** Use this if you cannot install PowerShell modules in your environment. Requires the Admin App from Step 1.

Whichever option you choose, repeat it for each site you would like to add to the SharePoint app.

#### Option A: Grant access with PnP PowerShell (recommended)

[PnP PowerShell](https://pnp.github.io/powershell/) is Microsoft's community-maintained module for SharePoint administration. It calls the same Microsoft Graph endpoint as Option B, but it handles authentication for you, so there is no access token to obtain, copy, or refresh before it expires.

**Requirements**

* PowerShell 7.4 or later. Windows PowerShell 5.1 is not supported.
* An account with the **delegated** `Sites.FullControl.All` Microsoft Graph permission. Note this is a delegated permission granted to the account you sign in with, which is different from the application permission described in Step 1.
* An app registration for PnP PowerShell itself. As of September 9, 2024 PnP PowerShell no longer ships with a shared multi-tenant app, so each tenant registers its own once. If your organization already uses PnP PowerShell, this already exists and you can skip that command below.

```powershell
# Install the module. Once per machine.
Install-Module PnP.PowerShell -Scope CurrentUser

# Register an app for PnP PowerShell. Once per tenant, skip if you already have one.
Register-PnPEntraIDAppForInteractiveLogin `
  -ApplicationName "PnP.PowerShell" `
  -Tenant <your organization domain>.onmicrosoft.com

# Sign in as an administrator.
Connect-PnPOnline `
  -Url https://<your organization domain>.sharepoint.com/sites/<site name> `
  -ClientId <PNP_APP_CLIENT_ID> `
  -Interactive

# Grant the StackAI SharePoint App read access to the site.
Grant-PnPEntraIDAppSitePermission `
  -AppId <SHAREPOINT_APP_CLIENT_ID> `
  -DisplayName "StackAI SharePoint" `
  -Permissions Read `
  -Site https://<your organization domain>.sharepoint.com/sites/<site name>

# Confirm the grant was created.
Get-PnPEntraIDAppSitePermission `
  -Site https://<your organization domain>.sharepoint.com/sites/<site name>
```

A few notes on the parameters:

* `-AppId` is the Client ID of the StackAI SharePoint App from Step 2, not the Admin App.
* `-Permissions Read` is the equivalent of `"roles": ["read"]` in Option B. Use `Write` instead if your workflows create or update files.
* `-Site` accepts the site URL directly, so you do not need the composite site ID for this command. You still need it for Step 6.
* On older versions of the module these cmdlets are named `Grant-PnPAzureADAppSitePermission` and `Get-PnPAzureADAppSitePermission`. Both names refer to the same commands.

#### Option B: Grant access with the Microsoft Graph API

To grant permission to the specific sites, you will first need the access token from the Admin App. Note, this is different from the Client Secret.

You can find the Tenant ID, Admin App Client ID from the Azure Portal > Overview.

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FfIRWpyx3hiaxM2TY9AEE%2Fimage.png?alt=media)

You can find the Client Secret from the **Azure Portal** > **Manage** > **Certification & Secrets**.

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FGYH35ObnudPa0wBWHCfA%2Fimage.png?alt=media)

Below is the command to obtain the access token from the Admin App.

```bash
curl -sS -X POST "https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<ADMIN_APP_CLIENT_ID>" \
  -d "client_secret=<ADMIN_APP_CLIENT_SECRET>" \
  -d "grant_type=client_credentials" \
  -d "scope=https%3A%2F%2Fgraph.microsoft.com%2F.default"
```

With the access token, run the following command to grant read permission to the site. Run the command for each site you would like to add to the SharePoint app.

* Use the full site ID constructed in the previous step.
* Target App Client ID is the Client ID of the SharePoint app.

```bash
curl -sS -X POST "https://graph.microsoft.com/v1.0/sites/<SITE_ID>/permissions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
   "roles": ["read"],
   "grantedToIdentities": [
     {
       "application": {
         "id": "<TARGET_APP_CLIENT_ID>",
         "displayName": "Target App"
       }
     }
   ]
  }'
```

{% hint style="info" %}
The access token returned by the first command is valid for about one hour. If the second command fails with a `401`, request a new token and try again.
{% endhint %}

The `curl` commands above are written for bash. In Windows PowerShell, `curl` is an alias for `Invoke-WebRequest` and does not accept these flags, so run them from WSL, Git Bash, or Azure Cloud Shell, or use Option A instead.

### **Step 6: Setting Up App-Only Connection in StackAI**

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FqR7haRN32qmK7JxlHCQa%2Fimage.png?alt=media)

The connection requires several key pieces of information:

**1. Client ID** (string, required)

* **What it is:** A unique identifier for your Azure AD application (also called "Application (client) ID").
* **Where to find it:** In the Azure portal, under "Azure Active Directory" > Under "Manage" select "App registrations" > \[Your App] > "Overview".

**2. Client Secret** (string, required)

* **What it is:** A password-like value generated for your Azure AD application, used to authenticate your app.
* **Where to find it:** In the Azure portal, under "Azure Active Directory" > "App registrations" > \[Your App] > "Certificates & secrets". You must create a new client secret and copy the value. Make sure you copy the Client Secret Value, not the Secret ID.

**3. Tenant ID** (string, required)

* **What it is:** The unique identifier for your Microsoft 365 tenant (organization).
* **Where to find it:** In the Azure portal, under "Azure Active Directory" > "Overview" > "Tenant ID".

**4. SharePoint Site ID** (string, optional if the Entra App permission is `Sites.Read.All` and required if the permission is `Sites.Selected`)

* **What it is:** The unique identifier for the SharePoint site you want to access. This is not the site URL, but an internal ID.
* **Where to find it:** See [Step 5](#step-5.-grant-sharepoint-site-access-to-the-sharepoint-app) above on how to obtain the Site ID.

***

## Set up OAuth2 Connection

For the built-in OAuth connector, sign in from StackAI and have your administrator approve the requested permissions if your tenant requires approval. Complete the steps below only when configuring your own Microsoft Entra application and custom OAuth connector.

### Step 1: Register a New App in Microsoft Entra ID

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) (or [Azure Portal](https://portal.azure.com)).
2. Navigate to **Identity** > **Applications** > **App registrations**.
3. Click **New registration**.
4. Fill in the form:
   * **Name**: A descriptive name such as `StackAI SharePoint OAuth2 Connector`.
   * **Supported account types**: Single tenant
   * **Redirect URI**: copy the redirect URI shown in your StackAI connector configuration
5. Click **Register**.
6. On the app's **Overview** page, copy and save:
   * **Application (client) ID:** this becomes the **Client ID** in StackAI.
   * **Directory (tenant) ID:** this becomes the **Tenant ID** in StackAI.

### Step 2: Add Microsoft Graph API Permissions

The connector requests the following **delegated** Microsoft Graph permissions by default:

<table><thead><tr><th width="199.71875">Permission</th><th width="149.1328125">Type</th><th>Purpose</th></tr></thead><tbody><tr><td><code>User.Read</code></td><td>Delegated</td><td>Read the signed-in user's profile (used for health checks via <code>/me</code>)</td></tr><tr><td><code>Sites.Read.All</code></td><td>Delegated</td><td>Read all SharePoint sites the user can access</td></tr><tr><td><code>Sites.ReadWrite.All</code></td><td>Delegated</td><td>Read and write all SharePoint sites the user can access</td></tr><tr><td><code>offline_access</code></td><td>Delegated</td><td>Obtain refresh tokens so sessions persist without re-login</td></tr><tr><td><code>openid</code></td><td>Delegated</td><td>OpenID Connect sign-in</td></tr><tr><td><code>profile</code></td><td>Delegated</td><td>Read basic profile information</td></tr><tr><td><code>email</code></td><td>Delegated</td><td>Read the user's email address</td></tr></tbody></table>

> **Least-privilege alternative:** If you would like to use actions such as search files (i.e. search across files in SharePoint sites based on user question), `Sites.Read.All` is required for delegated access. `Sites.Selected` is not currently supported for the Microsoft search file endpoint.

Independent of site permissions, keep `User.Read` for the connection health check, which calls Microsoft Graph `/me`. Keep `offline_access` so authorization can return a refresh token. These permissions do not grant access to SharePoint files. See [Microsoft identity scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc).

To confirm the minimal scopes for the intended use case, you can check <https://www.stackai.com/settings/connectors/sharepoint>

![Configure SharePoint authentication and site access setup](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F9IYGVrv0rnQtHq2C1g8j%2FClipboard-20260507-192151-102.gif?alt=media)

To add these permissions in Azure:

1. In the app registration, go to **API permissions** > **Add a permission**.
2. Select **Microsoft Graph**.
3. Select **Delegated permissions**.
4. Search for and select each permission listed above: `User.Read`, `Sites.Read.All`, `Sites.ReadWrite.All`, `offline_access`, `openid`, `profile`, `email`.
5. Click **Add permissions**.

### Step 3: Grant Admin Consent

`Sites.Read.All` and `Sites.ReadWrite.All` are high-privilege permissions that require an administrator to pre-authorize them on behalf of the entire organization. Without this step, individual users will be prompted to consent (or blocked, if your tenant disables user consent).

1. In the app registration, go to **API permissions**.
2. Click **Grant admin consent for \<your tenant name>**.
3. Confirm the dialog that appears.

You should see all permissions show a green checkmark under the **Status** column with the label "Granted for \<tenant>".

> **Required role:** At minimum **Cloud Application Administrator**. For SharePoint site-level permissions managed via the SharePoint admin center, **Global Administrator** may be required.

### Step 4: Create a Client Secret

1. In the app registration, go to **Certificates & secrets** > **Client secrets**.
2. Click **New client secret**.
3. Enter a **Description** (e.g., `StackAI SharePoint Connector secret`) and choose an **Expires** duration.
4. Click **Add**.
5. **Copy the secret Value immediately** (it is only displayed once). This becomes the **Client Secret** in StackAI.

Once you have obtained the secret, you can complete the setup in StackAI UI at <https://www.stackai.com/settings/connectors/sharepoint>.

***

## Connection fields and action reference

See [Microsoft SharePoint](https://docs.stackai.com/integrations/catalog/microsoft-sharepoint.md) for the current connector fields and supported actions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/microsoft-sharepoint/configure-sharepoint-authentication-and-site-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
