Document connectors

Document connectors let AI agents read company files from SharePoint, OneDrive, OneNote and Google Drive. Agents can search, list folders and read documents. Shield360 fetches every file live from the source when an agent asks for it. Nothing is copied or indexed, and every search, listing, read and refusal is recorded on the Activity tab of the Documents page (/documents).

Each connector is one read-only admin connection. The connection itself never decides what an agent may read. You decide that per agent, on the Access tab of the Documents page, by granting the folders the agent may read (or notebooks and sections, for OneNote). A grant covers everything inside the chosen folders. A grant with no folders allows everything the connection can see. OneDrive is the exception: it never reaches beyond the drives the connector names.

Redact sensitive values is on by default for every document connector. When it’s on, the built-in detector runs inside your deployment and replaces high-severity values, such as card numbers, national ID numbers, keys and credentials, with a marker such as [REDACTED payment_card] before the agent sees the text. The agent still reads the rest of the document.

Add a document connector

Add document connectors on the Connectors page (/connectors) with Add connector, in the Documents category. A connector belongs to the current project and environment. Agents in that project and environment see it, and no other project or environment does.

Every document connector has these settings:

Field	What it’s for
Redact sensitive values	On by default. Replaces sensitive values before an agent reads a document.
Secret from the Vault (optional)	The name of a Vault entry that holds the client secret or service account key. Use it instead of pasting the secret into the connector. The entry is read from the connector’s own project and environment.

The secret is encrypted when it’s saved and is never shown again. To change it, paste a new one. Leave it empty to keep the saved one.

To check a connector, use Test connection on the Connectors page. Shield360 signs in and lists the top level of the source. When it works, the result is Connected: N top-level folders visible. When it doesn’t, the result is the error from Shield360 or the provider. The troubleshooting table in each section below lists the common ones.

Note

SharePoint, OneDrive and OneNote all sign in through a Microsoft Entra app registration. You can create one registration per connector or share one, but grant each registration only the permissions its connectors need.

SharePoint

A SharePoint connector reads the document libraries on your SharePoint sites. The top level is up to 50 sites found by a site search, each with its libraries shown as Site / Library. Agents can list folders, search within a library or folder, and read files.

What you’ll need

• Permission to create app registrations in Microsoft Entra ID.
• An administrator who can grant tenant-wide admin consent.
• The directory (tenant) ID, the application (client) ID and a client secret.

Register an app in Microsoft Entra ID

In the Microsoft Entra admin center, register a new application for a single tenant (accounts in this organizational directory only). No redirect URI is needed. Microsoft’s guide: Register an application.

Add the Sites.Read.All application permission

Follow the permission steps in SharePoint permissions below.

Grant admin consent

On the app’s API permissions page, grant admin consent for your organisation. Application permissions don’t work until an administrator consents. Microsoft’s guide: Grant admin consent.

Create a client secret

Under Certificates & secrets, create a client secret and copy its Value (not the secret ID). Microsoft only shows the value once. Choose an expiry that fits your rotation policy, and note the date: when the secret expires, the connector stops working until you paste a new one. Microsoft’s guide: Add a client secret.

Copy the tenant and client IDs

The app’s Overview page shows the Directory (tenant) ID and the Application (client) ID.

Add the connector in Shield360

On the Connectors page, choose Add connector, then SharePoint. Fill in the fields below and save.

Test and grant

Use Test connection, then open the Documents page and grant agents the libraries or folders they may read.

Field	Value
Directory (tenant) id	The app’s directory (tenant) ID.
Application (client) id	The app’s application (client) ID.
Redact sensitive values	Leave on unless agents must see the raw values.
Secret from the Vault (optional)	A Vault entry holding the client secret, instead of the Client secret field.
Client secret	The client secret’s value.

SharePoint permissions

The connector signs in with the client credentials flow (app-only, no user) and calls these Microsoft Graph endpoints:

Call	Graph endpoint
Find sites	GET /sites?search=*
List a site’s libraries	GET /sites/{site-id}/drives
List a folder	GET /drives/{drive-id}/root/children, GET /drives/{drive-id}/items/{item-id}/children
Search a library or folder	GET /drives/{drive-id}/root/search(q='…'), GET /drives/{drive-id}/items/{item-id}/search(q='…')
Read a file’s details and parent folders	GET /drives/{drive-id}/items/{item-id}
Download a file	GET /drives/{drive-id}/items/{item-id}/content

Add one Microsoft Graph application permission:

• Sites.Read.All: required to search for sites. It also covers reading the libraries and the files in them.

You don’t need Files.Read.All for SharePoint, and you don’t need any write permission. Sites.Selected isn’t supported, because the connector finds libraries through a site search across the tenant. If agents should see only some sites, grant them only those libraries on the Documents page.

Sites.Read.All lets the app read every site in the tenant. Keep the client secret in the Vault or in the connector only. Shield360 never returns it.

SharePoint troubleshooting

Message	What to do
Set the directory (tenant) id and the application (client) id.	Fill in both IDs.
Set the client secret, or name the vault entry holding it.	Paste the secret value, or name the Vault entry that holds it.
That is not a valid vault entry name.	Vault entry names use letters, digits, ., _, / and -, up to 200 characters.
Microsoft sign-in failed: HTTP 400: … or HTTP 401: …	Microsoft refused the client credentials. Check the tenant ID and client ID, and that the secret is the Value and hasn’t expired. The AADSTS code in the message names the cause. See Microsoft Entra error codes.
HTTP 403: …	The app has no consented permission for the call. Add Sites.Read.All as an application permission and grant admin consent. A new consent can take a few minutes to take effect.
Connected: 0 top-level folders visible.	The site search found no sites with libraries. Check that Sites.Read.All is an application permission, not a delegated one, and that it has admin consent.
HTTP 404: … or Microsoft Graph returned HTTP 404.	The file was moved or deleted after the agent found it.

OneDrive

A OneDrive connector reads the OneDrives of the users you name, and only theirs. The top level is one drive per named user, shown as OneDrive / user@example.com. Every grant on the Documents page stays within those drives, even a grant with no folders.

What you’ll need

• Permission to create app registrations in Microsoft Entra ID.
• An administrator who can grant tenant-wide admin consent.
• The sign-in addresses of the users whose OneDrives agents may read.
• The directory (tenant) ID, the application (client) ID and a client secret.

Register an app in Microsoft Entra ID

Register a single-tenant application as for SharePoint. No redirect URI is needed. You can reuse the SharePoint app registration, because Sites.Read.All also covers OneDrive. A separate registration with only Files.Read.All is the least-privilege choice.

Add the Files.Read.All application permission

Follow the permission steps in OneDrive permissions below.

Grant admin consent

On the app’s API permissions page, grant admin consent for your organisation. See Grant admin consent.

Create a client secret

Under Certificates & secrets, create a client secret, copy its Value, and note its expiry date.

Add the connector in Shield360

On the Connectors page, choose Add connector, then OneDrive. Fill in the fields below and save.

Test and grant

Use Test connection. You should see one top-level folder per named user. Then grant agents folders on the Documents page.

Field	Value
Directory (tenant) id	The app’s directory (tenant) ID.
Application (client) id	The app’s application (client) ID.
OneDrive users	Sign-in addresses (user principal names), comma separated, for example policies@contoso.com, hr@contoso.com. Required. Only these users’ drives are reachable.
Redact sensitive values	Leave on unless agents must see the raw values.
Secret from the Vault (optional)	A Vault entry holding the client secret, instead of the Client secret field.
Client secret	The client secret’s value.

OneDrive permissions

A OneDrive connector signs in with the client credentials flow and doesn’t search SharePoint sites. It calls these Microsoft Graph endpoints:

Call	Graph endpoint
Find each named user’s drive	GET /users/{user}/drive
List, search, read details and download	The same /drives/{drive-id}/… endpoints as SharePoint

Add one Microsoft Graph application permission:

• Files.Read.All: covers every call above.

Sites.Read.All isn’t needed for a OneDrive connector, because it never calls the /sites endpoints. Add no write permissions.

Files.Read.All lets the app read every user’s OneDrive in the tenant. Shield360 narrows this to the users named in OneDrive users, but the secret itself is that powerful, so protect it the same way as any administrator credential.

OneDrive troubleshooting

Message	What to do
Name the OneDrive users (sign-in addresses) this connection may read.	Fill in OneDrive users.
Set the directory (tenant) id and the application (client) id.	Fill in both IDs.
Set the client secret, or name the vault entry holding it.	Paste the secret value, or name the Vault entry that holds it.
Microsoft sign-in failed: HTTP 400: … or HTTP 401: …	Check the tenant ID, client ID and secret value, and the secret’s expiry. The AADSTS code names the cause.
Connected: 0 top-level folders visible.	No named user’s drive could be reached. Check the addresses are sign-in addresses (UPNs), that each user has a OneDrive (it’s created the first time the user opens it), and that Files.Read.All is an application permission with admin consent. A drive that can’t be reached is left out rather than reported.
None of this connection's OneDrives could be reached.	An agent’s request found none of the named drives. Fix it as for Connected: 0.
HTTP 404: … or Microsoft Graph returned HTTP 404.	The file was moved or deleted after the agent found it.

OneNote

A OneNote connector reads notebooks, section groups, sections and pages. Pages are read as text. Search matches page titles only, because Microsoft Graph has no OneNote content search. On the Documents page you can grant a whole notebook, a section group or a section.

Microsoft retired app-only access to OneNote on 31 March 2025, so this connector reads as one signed-in user. An administrator or a dedicated service user signs in once. Agents then see what that account can see, narrowed by your grants.

What you’ll need

• Permission to create app registrations in Microsoft Entra ID.
• The Shield360 address users open, to build the redirect URI.
• A Microsoft 365 account to sign in as, with access to the notebooks.
• The directory (tenant) ID, the application (client) ID and a client secret.

Register an app in Microsoft Entra ID

Register a single-tenant application. Add a redirect URI on the Web platform (not single-page application):

https://<your-shield360-address>/api/documents/oauth/callback

Use the address exactly as your browser shows it when you use Shield360, including any port. If people reach Shield360 at more than one address, add a redirect URI for each one. See Add a redirect URI.

Add the delegated permissions

Follow the steps in OneNote delegated sign in below, then grant admin consent on the API permissions page.

Create a client secret

Under Certificates & secrets, create a client secret, copy its Value, and note its expiry date. The connector uses the secret every time it renews the sign-in.

Add the connector in Shield360

On the Connectors page, choose Add connector, then OneNote. Fill in the fields below and save.

Sign in once from the Documents page

Open the Documents page. On the Sources tab, choose Sign in with Microsoft on the OneNote source and sign in as the account agents should read as. You have 10 minutes to complete the sign-in. When it succeeds, the source shows Reading OneNote as <account>.

Test and grant

Use Test connection on the Connectors page. It lists the account’s notebooks. Then grant agents notebooks or sections on the Documents page.

Field	Value
Directory (tenant) id	The app’s directory (tenant) ID.
Application (client) id	The app’s application (client) ID.
Redact sensitive values	Leave on unless agents must see the raw values.
Secret from the Vault (optional)	A Vault entry holding the client secret, instead of the Client secret field.
Client secret	The client secret’s value.

OneNote delegated sign in

The sign-in uses the OAuth 2.0 authorization code flow with PKCE. Shield360 requests these scopes:

offline_access User.Read Notes.Read.All

Add these Microsoft Graph delegated permissions (not application permissions):

Permission	Why
Notes.Read.All	Read the notebooks the signed-in account can open, including notebooks shared with it.
User.Read	Show which account signed in.
offline_access	Get a refresh token, so the connector keeps working after the sign-in.

The connector calls GET /me/onenote/notebooks, /me/onenote/sectionGroups/{id}/…, /me/onenote/sections/{id}/pages, /me/onenote/pages and GET /me/onenote/pages/{id}/content, and once GET /me at sign-in.

Only the refresh token is kept, encrypted. Microsoft issues a new refresh token as it’s used, and Shield360 saves each one. Only a person who can manage agent access in the organisation can start the sign-in. The callback accepts only a sign-in started by the same person, for the same connector, within 10 minutes.

Choose the account carefully, because agents can read every notebook it can, up to your grants. A dedicated service user that has been given only the notebooks agents need is the least-privilege choice. If the sign-in lapses, for example after the account’s password is reset or its sessions are revoked, choose Sign in again on the Documents page.

OneNote troubleshooting

Message	What to do
Nobody has signed in to this OneNote connection yet. Sign in on the Documents page.	Complete the one-time sign-in.
Set the tenant id and client id on the connector first.	Fill in both IDs on the connector and save, then sign in.
Microsoft declined the sign-in: …	Read Microsoft’s message. AADSTS50011 means the redirect URI doesn’t match: add the exact …/api/documents/oauth/callback address on the Web platform. A consent error means the delegated permissions need admin consent.
Microsoft would not complete the sign-in: …	Usually a wrong or expired client secret, or a redirect URI registered on a platform other than Web.
Microsoft returned no refresh token; check the app has the offline_access permission.	Add the offline_access delegated permission, grant consent, and sign in again.
The sign-in took too long or was not started here. Try again.	Start the sign-in again from the Documents page and finish it within 10 minutes, in the same browser.
This sign-in was started by someone else.	The person who chooses Sign in with Microsoft must be the person who finishes it.
The sign-in could not be verified.	Start again from the Documents page. Don’t reuse an old Microsoft sign-in link.
OneNote sign-in has lapsed; sign in again on the Documents page. (…)	The refresh token was revoked or expired, or the client secret changed or expired. Choose Sign in again.
OneNote returned HTTP 403. or HTTP 403: …	The signed-in account can’t open that notebook, or Notes.Read.All isn’t consented.

Google Drive

A Google Drive connector reads files and folders through a Google Cloud service account, with the read-only scope https://www.googleapis.com/auth/drive.readonly. The top level is what has been shared with the service account, its own drive, and the shared drives the account is a member of. Folders inside a shared drive can be browsed and granted like any other. Google Docs are read as plain text, Sheets as CSV, Slides as plain text and Drawings as SVG. Search matches file names and contents.

What you’ll need

• A Google Cloud project where you can create service accounts and keys.
• The Google Drive API enabled in that project.
• The folders agents may read, shared with the service account.
• Optional: Workspace super admin access for domain-wide delegation.

Create a service account

In the Google Cloud console, create a service account in a project you control. It needs no IAM roles on the project. Google’s guide: Create service accounts.

Enable the Google Drive API

Enable the Google Drive API in the same project. Google’s guide: Enable Google Workspace APIs.

Create a JSON key

Create a key for the service account in JSON format and download it. The file must contain client_email and private_key. If your organisation blocks key creation with the iam.disableServiceAccountKeyCreation policy, an organisation policy administrator must allow it for this project. Google’s guide: Create and delete service account keys.

Share the folders agents may read

Share each folder agents may read with the service account’s email (its client_email) as a Viewer. For a shared drive, add the service account as a member of the drive instead; the drive then appears at the top level for browsing and granting. Follow the steps in Google Drive service account below if you’d rather use domain-wide delegation.

Add the connector in Shield360

On the Connectors page, choose Add connector, then Google Drive. Paste the whole key file and save.

Test and grant

Use Test connection. The shared folders and shared drives should appear at the top level. Then grant agents folders on the Documents page.

Field	Value
Act as user (optional)	With domain-wide delegation, the Workspace user whose Drive is read, for example docs-bot@example.com. Leave it empty to read what’s shared with the service account.
Redact sensitive values	Leave on unless agents must see the raw values.
Secret from the Vault (optional)	A Vault entry holding the key JSON, instead of the Service account key (JSON) field.
Service account key (JSON)	The whole key file.

Google Drive service account

The connector signs a JWT with the key’s private_key and exchanges it at https://oauth2.googleapis.com/token (the JWT bearer grant) for a token with one scope:

https://www.googleapis.com/auth/drive.readonly

It then calls the Drive API v3: GET /drive/v3/files to list and search (with shared drive support), GET /drive/v3/files/{id} for details and parent folders, GET /drive/v3/files/{id}?alt=media to download, and GET /drive/v3/files/{id}/export for Google Docs, Sheets, Slides and Drawings.

Without delegation (recommended), the service account reads only what you’ve shared with it. That’s the least-privilege setup: to take access away, unshare the folder.

With domain-wide delegation, the service account acts as the user in Act as user (optional) and reads everything that user can read. Use it only when sharing with the service account isn’t practical, and choose a dedicated user with only the folders agents need.

1. In the Google Admin console, open the domain-wide delegation settings and add a new API client.

2. Enter the service account’s client ID (its unique numeric ID, also in the key file as client_id).

3. Enter exactly this OAuth scope, and no others:

   https://www.googleapis.com/auth/drive.readonly

4. Set Act as user (optional) on the connector to that user’s email address.

Google’s guide: Control API access with domain-wide delegation and Delegate domain-wide authority to your service account. Delegation changes can take a while to take effect.

Google Drive troubleshooting

Message	What to do
Paste the whole service account key file (JSON with client_email and private_key).	Paste the complete JSON key file, including the braces.
Paste the service account key, or name the vault entry holding it.	Paste the key, or name the Vault entry that holds it.
The service account key is not valid JSON. or The service account key has no client_email or private_key.	The key stored in the Vault entry is incomplete. Store the whole key file.
The service account's private key could not sign.	The private_key is damaged, often by lost line breaks. Create a new key and paste the file unchanged.
Google sign-in failed: HTTP 400: … or HTTP 401: …	Google refused the token request. With Act as user (optional) set, unauthorized_client means domain-wide delegation isn’t set up for this client ID with the exact drive.readonly scope. invalid_grant usually means the key was deleted, or the user doesn’t exist.
HTTP 403: … mentioning the Drive API	Enable the Google Drive API in the service account’s project, then wait a few minutes.
Connected: 0 top-level folders visible.	Nothing has been shared with the service account yet. Share a folder with its client_email.
HTTP 404: … or Google Drive returned HTTP 403.	The file isn’t shared with the service account, or with the user it acts as, or it was deleted.

Related

Connectors overview

Every connector category and the actions they share.

Detectors

What the built-in detector finds when it redacts documents.

Vault

Keep client secrets and keys in the Vault, or in your own secrets manager.

Projects

How projects and environments scope connectors.