Skip to main content

Microsoft OneDrive

Microsoft OneDrive is a cloud file storage and synchronization service that's part of Microsoft 365. This connector enables AI assistants to browse, search, upload, download, share, and manage files and folders in a user's OneDrive through the Microsoft Graph API.

Authentication Types​

Microsoft OneDrive supports OAuth 2.0 authentication via the Microsoft identity platform:

  • OAuth - Standard OAuth 2.0 authorization flow with PKCE
    • Pros: Secure delegated access, per-user file access, automatic token refresh
    • Cons: Requires Azure app registration, user consent needed
    • Best for: Production applications, file management, document sharing

Setting up OAuth​

1. Register an Application in Azure Portal​

  1. Go to Azure Portal

  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

  3. In the left sidebar, click App registrations

  4. Click New registration

  5. Fill in the application details:

    • Name: Choose a descriptive name (e.g., "Webrix OneDrive Integration")
    • Supported account types: Select the appropriate option:
      • "Accounts in this organizational directory only" for single-tenant apps
      • "Accounts in any organizational directory" for multi-tenant apps
      • "Accounts in any organizational directory and personal Microsoft accounts" for the widest support
    • Redirect URI: Select "Web" and enter:
      • For SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
      • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback

  6. Click Register

2. Configure API Permissions​

  1. In your app registration, click API permissions in the left sidebar

  2. Click Add a permission

  3. Select Microsoft Graph

  4. Choose Delegated permissions

  5. Add the following permissions based on your needs:

    Essential permissions:

    • User.Read - Sign in and read user profile
    • Files.Read - Read user files
    • offline_access - Maintain access to data (enables refresh tokens)

    For reading all files (including shared):

    • Files.Read.All - Read all files that the user can access

    For uploading, editing, and managing files:

    • Files.ReadWrite - Read and write user files
    • Files.ReadWrite.All - Read and write all files the user can access (required for sharing permissions management)

  6. Click Add permissions

  7. Important: Click Grant admin consent for [Your Organization] if you have admin rights.

tip

Files.Read.All and Files.ReadWrite.All provide access to files shared with the user from other users' OneDrives as well, not just the user's own files.

3. Create Client Secret​

  1. In your app registration, click Certificates & secrets in the left sidebar

  2. Under Client secrets, click New client secret

  3. Add a description (e.g., "OneDrive Connector Secret")

  4. Choose an expiration period (recommended: 12 months or 24 months)

  5. Click Add

  6. Important: Copy the secret Value immediately - it will only be shown once!

warning

Store the client secret securely. If you lose it, you'll need to create a new one.

4. Get Your Credentials​

You'll need these values to configure the connector:

  1. Application (client) ID: Found on the app registration Overview page
  2. Client Secret: The value you copied in the previous step

5. Configure in Webrix​

  1. In Webrix, paste the Client ID and Client Secret

  2. Select the scopes you need:

    • At minimum: User.Read, Files.Read, offline_access
    • For uploading/editing: Add Files.ReadWrite
    • For sharing and full access: Add Files.ReadWrite.All

  3. Click Save Changes

  4. Click Connect to authorize the integration

Available Scopes​

Read Operations​

  • User.Read - Required for authentication; reads user profile information
  • Files.Read - Read-only access to the user's own files
  • Files.Read.All - Read-only access to all files the user can access (including shared files)

Write Operations​

  • Files.ReadWrite - Read and write access to the user's own files
  • Files.ReadWrite.All - Read and write access to all files the user can access (required for sharing/permissions management)

Essential​

  • offline_access - Enables refresh tokens to maintain long-term access without re-authentication

Common Use Cases​

Browse and Search Files​

  • List files and folders in the root directory or any subfolder
  • Search for files by name or content across the entire OneDrive
  • View recently accessed files
  • Get detailed metadata for any file or folder (size, type, dates, URLs)

Upload and Manage Files​

  • Upload new files to any location in OneDrive
  • Update existing file contents
  • Create folders to organize files
  • Copy files to new locations with optional renaming
  • Move or rename files and folders
  • Delete files and folders (moved to recycle bin)

File Versioning​

  • List all versions of a file
  • Restore a previous version of a file

Share Files​

  • Create sharing links (view, edit, or embed) with optional password and expiration
  • Share files directly with specific users via email invitation
  • View existing permissions on files and folders
  • Revoke access by removing permissions

Drive Information​

  • View storage quota and usage information
  • List files that others have shared with you
  • Get pre-authenticated download URLs for files

Working with Paths and IDs​

OneDrive items can be referenced by path or ID:

  • Path: Relative to the root, e.g., /Documents/Projects/report.pdf
  • ID: A unique identifier assigned by OneDrive, e.g., 01BYE5RZ6QN3ZWBTUFOFD3GSPGF6MVBK46

Most tools accept either format. Use paths for convenience when you know the file location, and IDs for reliability when working with items that may be moved or renamed.

Troubleshooting​

Insufficient Privileges Error​

Cause: The application doesn't have the required file permissions.

Solution:

  1. Verify that you've added the necessary Files.* permissions in the Azure portal
  2. Grant admin consent if required
  3. For sharing operations, ensure Files.ReadWrite.All is added

Cannot Upload Files​

Cause: Missing Files.ReadWrite permission or the file exceeds the size limit.

Solution:

  1. Ensure the app has the Files.ReadWrite or Files.ReadWrite.All permission
  2. The simple upload API supports files up to 4MB; larger files require upload sessions
  3. Check that the user has available storage quota
  4. Verify the destination path exists

File Not Found​

Cause: The file path or ID is incorrect, or the file has been deleted/moved.

Solution:

  1. Use the Search Files tool to locate the file
  2. Verify the path doesn't have typos (paths are case-insensitive)
  3. Check if the file was recently moved or deleted
  4. Use List Folder Contents to browse the expected location

Cause: External sharing may be disabled in your tenant, or the link type is restricted.

Solution:

  1. Check OneDrive admin settings for external sharing policies
  2. Try using "organization" scope instead of "anonymous"
  3. Verify the link hasn't expired
  4. Contact your administrator if anonymous links are required but disabled

Access Token Has Expired​

Cause: The OAuth access token has expired (typically after 1 hour).

Solution:

  • Ensure offline_access scope is included to enable automatic token refresh
  • The connector should automatically refresh tokens using the refresh token

Storage Quota Exceeded​

Cause: The user's OneDrive storage is full.

Solution:

  1. Use Get Drive Info to check current storage usage
  2. Delete unnecessary files or empty the recycle bin
  3. Contact your administrator to increase the storage quota

Best Practices​

Permissions​

  • Principle of Least Privilege: Start with Files.Read and add write permissions only when needed
  • Use Files.ReadWrite for user-owned files only; use Files.ReadWrite.All only if you need to manage shared files or permissions

File Operations​

  • Use Search Files for finding files rather than recursively listing folders
  • Use Get File Download URL to get temporary download links rather than streaming content through the API
  • Check file size before attempting simple uploads (4MB limit)
  • Use item IDs instead of paths for operations on files that may be moved

Rate Limits​

  • Microsoft Graph has throttling limits; implement retry logic for 429 responses
  • Use $select to request only needed metadata fields when listing files
  • Avoid deep recursive folder traversals; use search instead

Security​

  • Never expose client secrets in client-side code or version control
  • Store tokens securely and rotate client secrets regularly
  • Sharing links with "anonymous" scope should be used sparingly
  • Set expiration dates on sharing links when possible
  • Audit application access and sharing permissions periodically

API Reference​

This connector uses Microsoft Graph API v1.0 to interact with OneDrive. The base URL is https://graph.microsoft.com/v1.0.

Key endpoints used:

  • /me/drive - Drive information
  • /me/drive/root/children - Root folder contents
  • /me/drive/items/{id} - Item operations
  • /me/drive/root/search(q='...') - File search
  • /me/drive/items/{id}/createLink - Sharing links
  • /me/drive/items/{id}/invite - Share with users
  • /me/drive/items/{id}/versions - Version history

For more information, see the Microsoft Graph OneDrive API documentation.

Limitations​

  • File Upload Size: Simple upload is limited to 4MB. Larger files require upload sessions (not yet supported)
  • File Content: The connector cannot directly read file contents (text, images, etc.); use download URLs to access content
  • Batch Operations: Bulk operations are executed sequentially; no batch API support currently
  • Rate Limiting: Microsoft Graph API has throttling limits; the connector does not currently implement retry logic for 429 responses
  • OneDrive for Business vs Personal: Some features may differ between OneDrive for Business and personal OneDrive accounts

Additional Resources​