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, as a delegated permission rather than an application one. See Optional: OneNote notebooks below.

To also ingest SharePoint lists, a permission on the Office 365 SharePoint Online API is required as well, see SharePoint API permissions at step 16.

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)​

OneNote is the one Microsoft 365 service in this guide that does not accept application permissions. Microsoft's OneNote API reference states it directly ("the Microsoft Graph OneNote API doesn't support app-only authentication"), so the permissions above, which the application uses on its own behalf, cannot reach notebooks. OneNote content is read on behalf of a user instead.

Crawling OneNote therefore takes two things:

1. The delegated Notes.Read.All permission. Repeat steps 8-14 on the same application, but at step 10 choose Delegated permissions instead of Application permissions, and add:

Notes.Read.All

The admin consent in step 17 covers it along with the others, and it must be granted: the username/password sign-in the connector uses cannot prompt a user for consent. The permission is only read access to OneNote content.

2. A crawl account. Configure the content source with the username and password of an account that can open the notebooks (the public_access_credentials option of the SharePoint connector). The account must not have multi-factor authentication enabled. Beware that adding the Application permission Notes.Read.All and keeping certificate or client-secret credentials does not work: Azure AD consents that permission and issues tokens for it, but OneNote refuses them, and the crawl fails with 40001 The request does not contain a valid authentication token.

Delegated access is bounded by the account rather than by the tenant: Notes.Read.All reads the notebooks that account can open, so granting it access only to the intended sites keeps the OneNote crawl narrow, including alongside Sites.Selected. Restrict it further in the connector configuration, since as with every other setting, Zeta Alpha will only read data that is explicitly allowed by the connector configuration. One consequence: notebooks in another user's OneDrive are readable only if shared with the crawl account.

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. SharePoint API permissions (SharePoint connector only)​

Two SharePoint connector features read from the SharePoint REST API rather than Microsoft Graph, and take their authorization from the Office 365 SharePoint Online API permissions of the application, not the Graph permissions above. Which one to add depends on the features you use:

  • Incremental permission sync (detecting document permission changes without re-crawling all documents): Sites.Read.All.
  • SharePoint list ingestion: Sites.FullControl.All. Reading list access rights requires SharePoint's Enumerate Permissions right, which only Full Control includes; with a lower grant the read of a list's permissions is refused, and its items are ingested with only the content source's allow_access_rights. Sites.FullControl.All also covers incremental permission sync, so it is the only SharePoint permission a list-ingesting application needs.

Add the applicable permission:

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 the permission (Sites.Read.All, or Sites.FullControl.All for lists) and click Add permissions​

Select the permission and click Add permissions

Note: Both features need certificate-based authentication (recommended) or username/password credentials. SharePoint REST does not accept app-only tokens proven with a client secret: with a client secret, incremental permission sync is skipped, and list ingestion fails with 401 Unsupported app only token on every item.

With Sites.Selected instead of tenant-wide permissions, add the SharePoint Sites.Selected permission here, and pick the role granted in step 19 accordingly: read suffices for incremental permission sync, list ingestion needs fullcontrol.

For a connector using username/password credentials, list ingestion instead requires the Delegated SharePoint permission AllSites.FullControl (added like the delegated OneNote permission above, and admin-consented) and Full Control for the crawl account itself on every site in scope (site Owners group or site collection administrator). Effective rights are the intersection of the two, so a Members or Visitors account is not sufficient.

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.

The read role suffices for crawling files. To ingest SharePoint lists from the site, grant "roles": ["fullcontrol"] instead: reading list access rights requires SharePoint's Enumerate Permissions right, which the lower roles do not include (see step 16). The grant still bounds the application to the listed sites.

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. A certificate is also a hard requirement for SharePoint list ingestion: the REST endpoints serving list item access rights reject client-secret tokens entirely.

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 and the SharePoint lists 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!