Skip to main content

OneDrive Connector

The OneDrive connector is a governed, read-only integration that imports and continuously syncs content from Microsoft OneDrive into the Keeptrusts Knowledge Base. Connector-backed files surface sync health in the Knowledge Base file inspector and support agent, task, and runner bindings.

Use this page when​

  • You are setting up a OneDrive connector in Keeptrusts for the first time.
  • You need to troubleshoot Microsoft OAuth authorization or capability discovery.
  • You want to understand how continuous sync works for OneDrive files.
  • You are a platform operator configuring the shared Microsoft OAuth app for SaaS tenants.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Prerequisites​

  • Access to the Connectors page in the Keeptrusts console.
  • Confirmation from your platform operator that KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_ID and KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_SECRET are configured on the API service.
  • The console OAuth callback URI registered with the Microsoft app registration: https://<console-origin>/connectors/callback.
  • A Microsoft account with access to the OneDrive files you want to import.

Setup steps​

OneDrive connectors use the platform-managed Microsoft OAuth app. Tenant admins do not enter per-connector client_id or client_secret values in the console.

  1. Open Connectors in the Keeptrusts console.
  2. Click Add connector.
  3. Enter a connector Name.
  4. Choose OneDrive as the provider.
  5. Choose the connector Scope.
  6. Click Create connector.
  7. Open the connector detail page.
  8. Click Authorize.
  9. Complete the Microsoft consent flow — grant the requested OneDrive read scopes.
  10. Return to the connector detail page and click Refresh capabilities.

After step 10, the connector status should be active and the capability snapshot should list the accessible OneDrive scopes.

Platform operator: configure the shared Microsoft OAuth app​

  1. Register or identify the app registration in the Azure portal for Keeptrusts.
  2. Set KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_ID to the application (client) ID on the API service.
  3. Set KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_SECRET to the client secret on the API service.
  4. Add https://<console-origin>/connectors/callback to the Redirect URIs under Authentication in the app registration.
  5. Ensure the app has the Files.Read (or Files.Read.All) delegated permission granted in the Azure portal.

Continuous sync​

Once a OneDrive file is imported into the Knowledge Base, Keeptrusts tracks the source and syncs content changes automatically. The sync rail in the Knowledge Base file inspector shows:

  • healthy — the file is in sync with the OneDrive source
  • warning — a transient issue was detected; Keeptrusts will retry automatically
  • error — sync failed; check credentials and OneDrive permissions
  • paused — sync was manually paused by a user
  • unknown — sync state has not been established yet

Recovery actions available from the sync rail: Retry sync, Resync, Pause sync, Resume sync.

Continuous sync requires the OAuth token to remain valid. Microsoft OAuth tokens follow the app registration's token lifetime policy. If the token expires, the connector moves to expired status and sync stops. Re-authorize the connector to restore sync.

Troubleshooting​

ProblemWhat to check
Authorize button fails immediatelyConfirm KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_ID and KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_SECRET are set on the API service and the callback URI is registered with the Microsoft app registration
Capabilities stay empty after authorizationClick Refresh capabilities; verify the app registration has the Files.Read delegated permission and admin consent was granted if required by the tenant
Connector moves to expiredThe OAuth token expired — click Authorize again to re-authorize with Microsoft
Consent prompt asks for admin approvalSome Microsoft 365 tenants require admin consent for Files.Read.All; have your Microsoft tenant admin grant consent in the Azure portal
Sync shows error in the file inspectorCheck the error message in the sync rail; common causes include OneDrive permission changes and throttling by the Microsoft Graph API
Files are not appearing after importConfirm the connector is active and the Knowledge Base file is linked to the correct OneDrive source URL

For AI systems​

  • Canonical terms: Keeptrusts OneDrive connector, Microsoft OAuth, connector authorization, capability discovery, continuous sync, sync health.
  • Auth model: OAuth 2.0 using the platform-managed Microsoft OAuth app — tenant admins do not enter client_id or client_secret.
  • Platform operator env vars: KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_ID, KEEPTRUSTS_CONNECTOR_MICROSOFT_CLIENT_SECRET.
  • OAuth callback URI: https://<console-origin>/connectors/callback.
  • Connector statuses: pending, active, expired, revoked, error.
  • Sync states: healthy, warning, error, paused, unknown.
  • Related pages: Connectors overview, Knowledge Base, Settings and Gateway Config.

For engineers​

  • Register https://<console-origin>/connectors/callback in the Azure portal under Redirect URIs — without this, the Microsoft OAuth flow will fail.
  • Ensure the Files.Read delegated permission is granted in the app registration. Some Microsoft 365 tenants require admin consent for Files.Read.All; check with your tenant admin.
  • After setting the env vars on the API service, restart the service before testing connector creation in the console.
  • Use Refresh capabilities on the connector detail page to verify scopes after authorization.
  • Microsoft token refresh follows the app registration's session and token lifetime policy. Expired tokens require manual re-authorization by a console user.

For leaders​

  • The OneDrive connector brings Microsoft 365 document content into governed AI context while keeping access read-only.
  • The shared OAuth app model reduces per-tenant credential sprawl — one platform-level app covers all tenant connectors.
  • Continuous sync keeps Knowledge Base content current as OneDrive files change, ensuring agents work from up-to-date context.
  • Token expiry and revocation events are surfaced as connector status changes, giving operators clear visibility into credential health across the Microsoft identity platform.

Next steps​