Skip to main content

Connecting Microsoft apps to Zeta Alpha

Step-by-Step Instructions​

1. Sign in to Microsoft Entra​

Sign in to https://entra.microsoft.com/.

2. Click on Applications​

Click on Applications

3. Click on App registrations​

Go to the Invite users page by clicking the blue button in the top right corner.

Click on App registrations

4. Click on New registration​

Click on New registration

5. Enter the name of the application​

For example "Zeta Alpha Connector" Enter the name of the application

6. Click on Register​

Click on Register

7. Click on API permissions​

Click on API permissions

8. Click on Add a permission​

Click on Add a permission

9. Click on Microsoft Graph​

Click on Microsoft Graph

10. Click on Application permissions​

Click on Application permissions

11. Enter the permission name​

Enter the permission name

See the complete list of permissions at step 14.

12. Click on Expand or collapse group​

Click on Expand or collapse group

13. Click on the checkbox if not selected​

Click on the checkbox if not selected

14. Click on Add permissions​

Click on Add permissions

15. Add all required permissions by repeating steps 8-14 for each​

In Zeta Alpha, we practice the principle of least privilege, unfortunately Microsoft Graph API minimum permissions scopes are excessive for only reading data. The following permissions are required for the Zeta Alpha applications in order to read data from Sharepoint, OneDrive and Teams:

ChannelMessage.Read.All
ChannelSettings.Read.All
Chat.Read.All
Team.ReadBasic.All
TeamMember.Read.All
User.Read.All
Files.Read.All
Sites.Read.All

Even though this permissions are broader for only reading data, Zeta Alpha will only read data that is explicitly allowed by the connector configuration.

To also crawl OneNote notebooks, one further permission is required — see Optional: OneNote notebooks below.

Alternative: Add selected sites only​

If you want to limit the access to selected SharePoint sites only, then the only permission to add is

Sites.Selected

Then, after creating the application, you need to grant access to the specific SharePoint sites that you want Zeta Alpha to crawl. Please refer to step 19 Grant access to specific sites below.

Optional: OneNote notebooks (SharePoint connector only)​

To crawl OneNote notebooks with the SharePoint connector, add one more Microsoft Graph application permission:

Notes.Read.All

Add it by repeating steps 8-14, and the admin consent in step 17 covers it along with the others.

Notes.Read.All is tenant-wide. OneNote has no equivalent of SharePoint's Sites.Selected, so the permission cannot be narrowed to individual sites in Azure AD. If you use Sites.Selected to limit the application's reach, restrict the OneNote crawl in the connector configuration instead — as with every other setting, Zeta Alpha will only read data that is explicitly allowed by the connector configuration.

This is the only extra permission OneNote needs. The access rights of a notebook's pages are read through the Files.Read.All / Sites.Read.All access the connector already has, since a page's permissions come from the document library item that stores its notebook.

16. Required for incremental permission sync (SharePoint connector only)​

To enable incremental permission detection (detecting when document permissions change without re-crawling all documents), add the Sites.Read.All permission for the SharePoint application:

16.1. Click on Add a permission​

Click on Add a permission

16.2. Select SharePoint (not Microsoft Graph)​

Select Sharepoint

16.3. Select Application permissions​

Select Application permission

16.4. Select Sites.Read.All and click Add permissions​

Select Site.Read.All and click Add permissions

Note: Incremental permission detection is not available when using client secret authentication (app-only tokens). Use certificate-based authentication (recommended) or ROPC for full incremental support.

For incremental permission sync with Sites.Selected, add the SharePoint Sites.Selected permission instead.

Click on Grant admin consent for MSFT

18. Click on Yes​

Click on Yes

19. (Required only for "Sites.Selected" permissions) Grant Read permissions to the specific sites​

This step is required only if you selected the "Sites.Selected" permission in step 15, otherwise skip to step 20.

Identify the Site ID of the SharePoint site you want to grant access to.

You can find the Site ID in the SharePoint admin center or by using the Microsoft Graph Explorer. Common queries to get the Site ID and WebUrl are:

  • Get All sites:
GET https://graph.microsoft.com/v1.0/sites/microsoft.graph.getAllSites()
  • Get root site:
GET https://graph.microsoft.com/v1.0/sites/root
  • Get Sites at root level:
GET https://graph.microsoft.com/v1.0/sites/root/sites
  • Get user's OneDrive WebUrl:
GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}/drive/root/site
  • Get Site by WebUrl:
GET https://graph.microsoft.com/v1.0/sites/{hostname}:/sites/{site-path}

SiteId should look like this:

contoso.sharepoint.com,12345678-90ab-cdef-1234-567890abcdef,abcdef12-3456-7890-abcd-ef1234567890

Also take note of the WebUrl of the site, you will need it to configure the connector later.

Once you have the Site ID, use the following command in Microsoft Graph Explorer or any HTTP client to grant read permissions to the application:

POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Content-Type: application/json
{
  "roles": ["read"],
  "grantedToV2": {
    "application": {
      "id": "{Connector applicationID}",
      "displayName": "{Connector Name}"
    }
  }
}

Replace {siteId} with the actual Site ID of the SharePoint site, {Connector applicationID} with the Application (client) ID (step 23), and {Connector Name} with the name from step 5.

20. Click on Certificates & secrets​

Click on Certificates & secrets

21. Choose your authentication method​

You can authenticate using either a certificate (recommended) or a client secret (simpler but limited). Choose one of the two options below.

Recommendation: Certificate-based authentication is strongly preferred for the SharePoint connector because it supports incremental permission detection (detecting permission changes without re-crawling). Client secret authentication uses app-only tokens that are not supported by the SharePoint getchanges REST API, requiring a slower full access rights crawl instead.

Certificate-based authentication is considered more secure and does not have an expiration time. It also enables all connector features including incremental permission sync.

Generate a self-signed certificate (if you don't already have one):

openssl req -x509 -newkey rsa:2048 -keyout sp_key.pem -out sp_cert.pem -days 365 -nodes \
  -subj "/CN=SharePoint App-Only Auth/O=Self-Signed"

This creates two files:

  • sp_key.pem — the private key (keep this secret, provide it to Zeta Alpha)
  • sp_cert.pem — the public certificate (upload to Azure AD)

Upload the certificate to Azure AD:

  1. On the Certificates & secrets page, click the Certificates tab
  2. Click Upload certificate Upload certificate
  3. Select the sp_cert.pem file and click Add

Option B: Client Secret (limited)​

Note: Client secret authentication does not support incremental permission detection. The connector will perform a full access rights crawl on every update cycle, which is slower and uses more API requests.

21b. Click on New client secret​

Click on New client secret

22b. Type the name of the secret​

For example "Zeta Alpha Secret" Type the name of the secret

23b. Select the maximum expiration date and click on Add​

Select the maximum expiration date and click on Add

24b. Click on the Copy to clipboard button​

Click on the Copy to clipboard button

22. Click on Overview​

Click on Overview

23. Copy the values of Application (client) ID and Directory (tenant) ID​

Copy the values of Application (client) ID and Directory (tenant) ID

24. Send info to Zeta Alpha​

The following values need to be sent to the Zeta Alpha platform

If using a certificate (Option A, recommended):

  • Certificate private key (sp_key.pem)
  • Certificate public key (sp_cert.pem)
  • Application (client) ID
  • Directory (tenant) ID

If using a client secret (Option B):

  • Client Secret
  • Application (client) ID
  • Directory (tenant) ID

In case Zeta Alpha is managing your Sharepoint connector, please also send the list of SharePoint Site URLs (WebUrl) that you want to crawl, and state whether the OneNote notebooks on those sites should be crawled as well, so the connector is configured for it.

Delegated (per-user) access (SharePoint connector)​

The steps above set up application access: the connector reads with app-only permissions and sees everything the app is granted across the tenant. Delegated access is the alternative. The connector crawls as a specific user and sees only what that user can see. Use it when access should follow a person's own SharePoint permissions instead of a tenant-wide grant.

It reuses the same app registration flow, with three differences: a redirect URI, delegated permissions instead of application ones, and a client secret (the certificate option does not apply).

Register the application​

Follow steps 1 to 6 above to create a new App registration (for example "Zeta Alpha Delegated Connector"). A single-tenant registration is fine.

Add a redirect URI​

In the registration, go to Authentication, click Add a platform, choose Web, and add the redirect URI Zeta Alpha provides for your environment. This is the exact URL Microsoft returns the user to after they sign in. Save.

Add delegated API permissions​

Go to API permissions, then Add a permission, and add the following as Delegated permissions (not Application permissions). For the first four choose Microsoft Graph, then Delegated permissions; for AllSites.Read choose SharePoint, then Delegated permissions.

APIPermissionWhy
Microsoft GraphSites.Read.Allread the sites the user can see, plus their metadata
Microsoft GraphFiles.Read.Allread file content and drive listings
Microsoft GraphUser.Readidentify who authorized
Microsoft Graphoffline_accessissue the refresh token that makes unattended crawls possible
SharePointAllSites.Readincremental permission sync uses the SharePoint REST API, a separate resource

Click Grant admin consent for <tenant> and confirm (steps 17 to 18 above). One admin approval covers every user who authorizes afterward. Grant it even when the permissions show "Admin consent required: No": if your tenant disallows user consent (a common default), sign-in fails without it.

Create a client secret​

Create a client secret (steps 21b to 24b above) and copy its Value. Delegated authorization-code authentication uses a client secret.

Send info to Zeta Alpha​

  • Application (client) ID
  • Directory (tenant) ID
  • Client secret

Each user who should be crawled then authorizes once through an interactive Microsoft sign-in against this app. That sign-in produces the per-user refresh token the connector redeems for access tokens at crawl time. The signing-in user's SharePoint permissions define what their crawl can reach.

What's next?​

If applicable, set up the Zeta Alpha Teams and SharePoint connectors!