Skip to main content
Version: v1.7.3-14 🚧

SharePoint OAuth setup

Overview​

SharePoint Online OAuth enables users to connect their Microsoft 365 accounts and import documents from SharePoint sites without sharing service account credentials.

note

This page covers the administrator setup. To learn how end users import documents from SharePoint, see Import from SharePoint Online. For the OAuth setting reference and configuration through the API or SDK, see Data connectors and OAuth.

Prerequisites​

  • A Microsoft Entra ID tenant (formerly Azure Active Directory).
  • Global Administrator or Application Administrator role in Microsoft Entra ID.
  • An Enterprise h2oGPTe deployment with a public HTTPS URL.

Step 1: Register a multi-tenant app in Microsoft Entra ID​

  1. Sign in to the Azure Portal.
  2. Go to Microsoft Entra ID > App registrations.
  3. Select New registration.
  4. Set the following fields:

    • Name: Enter a name (for example, H2O GPTe SharePoint Connector).

    • Supported account types: Select Any Entra ID Tenant + Personal Microsoft accounts.

      note

      This option allows personal Microsoft accounts (such as Outlook.com and Xbox) to authenticate, in addition to organizational accounts. If your deployment should only allow organizational accounts, select Multiple Entra ID tenants instead.

    • Redirect URI: Select Web, then enter https://<your-h2ogpte-domain>/api/v1/connectors/sharepoint/callback.

  5. Select Register.

Register an app page in Microsoft Entra ID with the supported account types dropdown open

Step 2: Copy the Application (client) ID​

  1. On the app's Overview page, locate the Application (client) ID field.
  2. Select the copy icon and save the value. You enter it in the System Dashboard in Step 5.

App Overview page in Microsoft Entra ID showing the Application (client) ID field

important

Copy the Application (client) ID from the Overview tab. A different Client ID field appears under Certificates & secrets. Don't use that one.

Step 3: Create a client secret​

  1. In the app registration, go to Certificates & secrets.
  2. Select New client secret.
  3. Enter a description (for example, Enterprise h2oGPTe production).
  4. Select an expiry period. H2O recommends 24 months and a documented rotation policy.
  5. Select Add.
  6. Copy the secret Value and save it securely.
important

Microsoft Entra ID displays the secret value only once. Copy and store the value before leaving the page.

Step 4: Configure API permissions​

  1. In the app registration, go to API permissions.

  2. Select Add a permission > Microsoft Graph > Delegated permissions.

  3. Add the following permissions:

    PermissionPurpose
    Files.Read.AllRead files in all site collections the user has access to.
    Sites.Read.AllRead items in all site collections the user has access to.
    User.ReadSign in the user and read the user profile.
    offline_accessMaintain access through token refresh.

  4. Select Add permissions.

important

Don't grant admin consent at this stage. For a multi-tenant app, each customer organization grants consent separately. See Step 6.

Step 5: Configure SharePoint OAuth in Enterprise h2oGPTe​

  1. In Enterprise h2oGPTe, click

    Account Circle.

  2. Select System Dashboard.

  3. In the Configuration section, click System settings.

  4. Scroll down to the OAUTH category.

  5. Set the following values:

    SettingValue to enter
    SharePoint OAuth Client IDThe Application (client) ID from Step 2.
    SharePoint OAuth Client SecretThe client secret value from Step 3. Stored encrypted.
    SharePoint OAuth Tenant IDcommon for multi-tenant access, or your specific Microsoft Entra ID tenant ID.
    SharePoint OAuth Redirect URLThe redirect URI from Step 1. The value must match exactly.
    SharePoint OAuth ScopesThe default value covers the required Microsoft Graph scopes.

SharePoint OAuth settings in the OAUTH category of System settings

For per-setting details and configuration through the REST API or Python SDK, see Data connectors and OAuth.

Because the app is multi-tenant, each customer organization must grant admin consent before its users can authenticate. Send the customer administrator an admin consent URL in the following format:

https://login.microsoftonline.com/common/adminconsent?client_id=<your_client_id>&redirect_uri=https://<your-h2ogpte-domain>/api/v1/connectors/sharepoint/callback

The customer administrator opens the URL, signs in, reviews the requested permissions, and selects Accept. Once the administrator grants consent, all users in the organization can authenticate with SharePoint OAuth.

note

Some organizations enable user-level consent in their Microsoft Entra ID tenant, allowing users to grant consent at first login without administrator approval. Many organizations turn off user consent for security reasons.

Troubleshooting​

Client ID not configured​

Cause: The SharePoint OAuth Client ID isn't set in the System Dashboard.

Resolution: Set the SharePoint OAuth Client ID value in the OAUTH category of System settings, or set the matching environment variable on the deployment.

The login flow returns the error AADSTS90094: The grant requires admin permission.

Cause: The customer organization hasn't granted admin consent.

Resolution: Send the admin consent URL (see Step 6) to the customer's Microsoft Entra ID administrator.

Invalid redirect URI​

Cause: The redirect URI in Microsoft Entra ID doesn't match the value configured in Enterprise h2oGPTe.

Resolution: Verify that the SharePoint OAuth Redirect URL in the System Dashboard exactly matches the Redirect URI in the Microsoft Entra ID app registration. The protocol (https://), domain, and path (/api/v1/connectors/sharepoint/callback) must all match.

Token refresh fails​

Cause: The offline_access scope is missing, the client secret has expired, or the secret value is incorrect.

Resolution:

  • Confirm that offline_access appears in the API permissions for the app.
  • Check the secret expiry date in Certificates & secrets in the Azure Portal.
  • Verify that the SharePoint OAuth Client Secret value matches the one in the Azure Portal.

Users cannot see SharePoint sites​

Cause: Missing permissions, incomplete admin consent, or the user lacks access to SharePoint sites in their organization.

Resolution:

  • Confirm that Sites.Read.All and Files.Read.All appear in the API permissions.
  • Confirm that the customer organization granted admin consent.
  • Confirm that the user has access to SharePoint sites in their organization.

Best practices​

  • Rotate client secrets periodically: Schedule rotation before the expiry date to avoid service interruption.
  • Store secrets securely: Use environment-specific credentials and don't commit secret values to version control.
  • Use HTTPS for redirect URIs: Microsoft Entra ID requires HTTPS for non-localhost redirect URIs.
  • Review granted permissions regularly: Audit the API permissions and admin consents in the Azure Portal.
Feedback