Microsoft OneDrive Integration Guide

Overview

The Microsoft OneDrive integration allows your NINA workflows to connect with OneDrive for Business for comprehensive file and folder management. This integration enables you to upload, download, list, search, and delete files in the signed-in user's personal OneDrive or any shared drive they have access to, directly from your automation workflows.

Status

The integration currently supports comprehensive OneDrive file management operations:

Currently Supported:

• Drive Management: List the drives the user can access, get metadata for a specific drive
• Document Operations: Upload, download, list, search, delete files, and retrieve file metadata
• Bulk Operations: Upload multiple files or download multiple files in batches (up to 50 per batch)
• Folder Management: Navigate folder structures, list folder contents with filtering
• Large File Support: Resumable upload session for files larger than 4MB (up to 250MB)
• Search Capabilities: Full-text search across the user's drive or a selected shared drive

Advanced Features:

• OAuth2 Authentication: Secure authentication via Microsoft Entra ID
• Automatic Token Refresh: Seamless token refresh for uninterrupted operations
• Resource Locator: Searchable dropdown for drive selection (defaults to the user's personal OneDrive)
• OData Filtering: Advanced filtering for file listings using OData expressions
• Pagination Support: Handle large result sets with configurable limits
• Base64 Encoding: Automatic base64 encoding/decoding for file content
• Rate Limiting: Built-in delays between batch operations to prevent throttling
• Timeout Configuration: Configurable timeouts for long-running operations (300-600 seconds)

Credential Configuration

Before using the Microsoft OneDrive integration in your workflows, you need to configure OAuth2 credentials through Microsoft Entra ID.

Prerequisites

1. Microsoft Entra ID Account: You need a Microsoft Entra ID account with appropriate permissions
2. Azure App Registration: You must register an application in Microsoft Entra ID
3. API Permissions: The app must have the required Microsoft Graph API permissions

Creating an App Registration in Microsoft Entra ID

1. Sign in to Azure Portal: Navigate to portal.azure.com

2. Navigate to Microsoft Entra ID: Select Microsoft Entra ID from the left menu

3. Go to App Registrations: Click App registrations → New registration

4. Configure the Application:

   • Name: Enter a descriptive name (e.g., "NINA OneDrive Integration")
   • Supported account types: Select "Accounts in this organizational directory only"
   • Redirect URI: Select Web and add your NINA callback URL(s):
     • For POC environment: https://poc.zynap.com/api/v1/oauth2/callback
     • For Production environment: https://platform.zynap.com/api/v1/oauth2/callback
   • Click Register

5. Copy Important Values: From the Overview page, copy:

   • Application (client) ID → you will use this as clientId
   • Directory (tenant) ID → you will use this as tenantId

6. Create a Client Secret:

   • Go to Certificates & secrets → Client secrets → New client secret
   • Add a description (e.g., "NINA Integration Secret")
   • Select an expiration period
   • Click Add
   • Copy the secret value immediately (it won't be shown again) → you will use this as clientSecret

7. Configure API Permissions:

   • Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions
   • Add the following permissions:
     • Files.ReadWrite.All - Have full access to all files the user can access
     • offline_access - Maintain access to data you have given it access to
   • Click Add permissions
   • Click Grant admin consent for [Your Organization] (requires admin privileges)

Note: Unlike the SharePoint integration, OneDrive does not require the Sites.ReadWrite.All scope. Files.ReadWrite.All alone is sufficient for the signed-in user's personal OneDrive and any shared drives they have access to.

Authentication Method

The Microsoft OneDrive integration uses OAuth2 authentication:

Field	Description	Example
Client ID	Application (client) ID from Azure app registration	a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
Client Secret	Client secret value from Azure app registration	abc123~DEF456_GHI789.JKL012
Tenant ID	Directory (tenant) ID from Microsoft Entra ID	x9y8z7w6-v5u4-t3s2-r1q0-p9o8n7m6l5k4
Scope	OAuth2 scope permissions	Files.ReadWrite.All offline_access
Auth URL	Microsoft OAuth2 authorization endpoint	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
Access Token URL	Microsoft OAuth2 token endpoint	https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

Important Notes:

• Client secrets expire and must be renewed periodically in Microsoft Entra ID
• The integration automatically handles token refresh using the refresh token
• Admin consent is required for organization-wide permissions
• Ensure the redirect URI in Microsoft Entra ID matches your NINA instance callback URL
• The {tenantId} placeholder in URLs is automatically replaced with your actual tenant ID
• This integration targets OneDrive for Business. Consumer (personal Microsoft) accounts are not supported in this release — they use the common/consumers tenant endpoint and a separate consent flow.

Creating a Microsoft OneDrive Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "OneDrive Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Microsoft OneDrive"
   • Auth Type: "OAuth2" (only option available)
   • Client ID: Paste your Application (client) ID
   • Client Secret: Paste your client secret value
   • Tenant ID: Paste your Directory (tenant) ID
   • Scope: Use default or customize (Files.ReadWrite.All offline_access)
   • Auth URL: Use default or customize (with {tenantId} placeholder)
   • Access Token URL: Use default or customize (with {tenantId} placeholder)

4. Click Authorize to initiate OAuth2 flow

5. Sign in with your Microsoft account and grant permissions

6. Click Save to store the credential

Supported Resources and Operations

The Microsoft OneDrive integration supports the following resources and operations:

Drive

Operation	Description
Get	Get metadata for a specific drive. Returns the signed-in user's OneDrive when no driveId is provided
List	List all drives the signed-in user has access to (their OneDrive plus shared drives)

Document

Operation	Description
Download	Download a single document from OneDrive (base64 encoded)
Bulk Download	Download multiple documents in a single batch (max 50 files)
Upload	Upload a single document to OneDrive (with resumable upload session for large files)
Bulk Upload	Upload multiple documents in a single batch (max 50 files)
List	List files in a OneDrive folder with optional filtering
Search	Search for files in OneDrive by query
Delete	Delete a file from OneDrive
Get Metadata	Retrieve metadata for a specific file

Drive Targeting

The driveId parameter is optional on every document operation:

• Leave it empty → operations target /me/drive (the signed-in user's personal OneDrive). This is the default and covers the majority of OneDrive for Business use cases.
• Set a drive ID → operations target /drives/{driveId} (a specific shared drive the user has access to). Use this when working with team or group drives.

The drive picker dropdown lists "My OneDrive" first (representing the empty-value default) followed by every shared drive returned from the /me/drives endpoint.

Parameter Merging

The Microsoft OneDrive integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the OneDrive Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a OneDrive Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the OneDrive operation

Examples

Getting Your OneDrive

Retrieve metadata for the signed-in user's OneDrive:

Node Configuration:

{}

No parameters are required — omitting driveId returns the user's personal OneDrive metadata.

Response:

{
  "id": "b!abc123def456...",
  "driveType": "business",
  "name": "OneDrive",
  "owner": {
    "user": {
      "displayName": "Jane Smith",
      "email": "[email protected]"
    }
  },
  "quota": {
    "deleted": 0,
    "remaining": 1099511627776,
    "state": "normal",
    "total": 1099511627776,
    "used": 0
  },
  "webUrl": "https://contoso-my.sharepoint.com/personal/jane_smith_contoso_com/Documents"
}

Listing Accessible Drives

List drives the user has access to (personal OneDrive plus shared drives):

Node Configuration:

{
  "returnAll": false,
  "limit": 50,
  "timeout": 300
}

This lists up to 50 drives with a 5-minute timeout.

Uploading a Single File

Upload a file to the user's OneDrive (automatically uses resumable upload for files > 4MB):

Node Configuration:

{
  "folderPath": "/Reports/2026",
  "fileName": "monthly-report.pdf",
  "fileContent": "JVBERi0xLjcKCjEgMCBvYmoKPDwvVHlwZS9DYX...",
  "timeout": 600
}

Note: fileContent must be base64 encoded. The integration automatically decodes it before upload.

To upload to a specific shared drive instead of the user's personal OneDrive, supply driveId:

{
  "driveId": {
    "mode": "list",
    "value": "b!abc123-shared-drive-id"
  },
  "folderPath": "/Shared Reports",
  "fileName": "team-report.pdf",
  "fileContent": "JVBERi0xLjcKCjEgMCBvYmo..."
}

Bulk Uploading Files

Upload multiple files in a single operation:

Node Configuration:

{
  "folderPath": "/Archive",
  "files": [
    {
      "fileName": "report-2026-01.pdf",
      "fileContent": "JVBERi0xLjcKCjEgMCBvYmo..."
    },
    {
      "fileName": "report-2026-02.pdf",
      "fileContent": "JVBERi0xLjcKCjIgMCBvYmo..."
    },
    {
      "fileName": "report-2026-03.pdf",
      "fileContent": "JVBERi0xLjcKCjMgMCBvYmo..."
    }
  ],
  "timeout": 600
}

This uploads all 3 files with built-in rate limiting (100ms delay between requests).

Downloading a Single File

Download a file from OneDrive:

Node Configuration:

{
  "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
  "timeout": 300
}

Response:

{
  "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
  "name": "monthly-report.pdf",
  "size": 2048576,
  "webUrl": "https://contoso-my.sharepoint.com/.../monthly-report.pdf",
  "content": "JVBERi0xLjcKCjEgMCBvYmoKPDwvVHlwZS9DYX...",
  "mimeType": "application/pdf",
  "downloadUrl": "https://..."
}

The content field contains the base64-encoded file data.

Bulk Downloading Files

Download multiple files in a single operation:

Node Configuration:

{
  "itemIds": [
    "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
    "01BCDEFGHIJKLMNOPQRSTUVWXYZ0987654321",
    "01CDEFGHIJKLMNOPQRSTUVWXYZ1122334455"
  ],
  "timeout": 600
}

Response:

{
  "files": [
    {
      "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
      "name": "report1.pdf",
      "size": 1024000,
      "content": "JVBERi0x...",
      "mimeType": "application/pdf"
    },
    {
      "id": "01BCDEFGHIJKLMNOPQRSTUVWXYZ0987654321",
      "name": "report2.pdf",
      "size": 2048000,
      "content": "JVBERi0y...",
      "mimeType": "application/pdf"
    }
  ],
  "errors": [
    {
      "itemId": "01CDEFGHIJKLMNOPQRSTUVWXYZ1122334455",
      "error": "File not found"
    }
  ],
  "total": 3,
  "success": 2,
  "failed": 1
}

Listing Files in a Folder

List all files in a specific folder:

Node Configuration:

{
  "folderPath": "/Reports",
  "returnAll": false,
  "limit": 100
}

To list the root of the drive, omit folderPath or set it to /.

Listing Files with OData Filter

Use OData filtering to list only specific files:

Node Configuration:

{
  "folderPath": "/Reports",
  "filter": "startswith(name,'report') and size gt 1000000",
  "limit": 50
}

This lists files whose names start with "report" and are larger than 1MB.

Searching for Files

Search across the user's drive (or a shared drive when driveId is set):

Node Configuration:

{
  "query": "quarterly financial report",
  "limit": 25
}

Getting File Metadata

Retrieve detailed metadata for a file:

Node Configuration:

{
  "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}

Response:

{
  "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
  "name": "monthly-report.pdf",
  "size": 2048576,
  "createdDateTime": "2026-01-15T10:30:00Z",
  "lastModifiedDateTime": "2026-01-20T14:45:00Z",
  "webUrl": "https://contoso-my.sharepoint.com/...",
  "createdBy": {
    "user": {
      "displayName": "John Doe",
      "email": "[email protected]"
    }
  },
  "lastModifiedBy": {
    "user": {
      "displayName": "Jane Smith",
      "email": "[email protected]"
    }
  },
  "file": {
    "mimeType": "application/pdf",
    "hashes": {
      "quickXorHash": "abc123..."
    }
  }
}

Deleting a File

Remove a file from OneDrive:

Node Configuration:

{
  "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}

Response:

{
  "success": true,
  "message": "File deleted successfully",
  "itemId": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
}

Integration in Workflow Context

The Microsoft OneDrive integration is particularly effective for personal and team file management workflows:

Common Workflow Patterns:

1. Personal Document Archival:

   • Schedule Node → Email Node (fetch attachments) → Script Node (process) → OneDrive Node (bulkUpload) → Email Node (confirmation)

2. Automated Report Drop:

   • Report Generation Node → Script Node (format) → OneDrive Node (upload) → Teams Node (notify with webUrl)

3. Document Backup to OneDrive:

   • S3 Node (list) → S3 Node (bulkDownload) → OneDrive Node (bulkUpload) → Database Node (sync log)

4. Compliance Scanning:

   • OneDrive Node (search) → OneDrive Node (download) → Virus Scan Node → DLP Node → OneDrive Node (delete if needed) → SIEM Node (log)

5. Cross-Drive Synchronization:

   • SharePoint Node (list) → SharePoint Node (download) → OneDrive Node (upload) → Database Node (sync log)

6. User Onboarding:

   • HR Trigger Node → OneDrive Node (upload onboarding pack) → Email Node (welcome with download link)

Advanced Features

Resource Locator with Drive Dropdown

The integration provides a searchable dropdown for drive selection. The first option, "My OneDrive", maps to the user's personal drive with an empty value — operations interpret this as /me/drive:

{
  "driveId": {
    "mode": "list",
    "value": ""
  }
}

For a shared drive, select it from the dropdown or supply the drive ID directly:

{
  "driveId": {
    "mode": "id",
    "value": "b!shared-drive-id-here"
  }
}

Large File Handling

The integration automatically uses a resumable upload session for files larger than 4MB:

• Small files (< 4MB): Simple PUT request
• Large files (4MB - 250MB): Upload session with 10MB chunks
• Maximum file size: 250MB (Microsoft Graph API limit)

Automatic Token Refresh

The integration handles OAuth2 token refresh automatically:

1. Detects 401 Unauthorized responses
2. Uses refresh token to obtain new access token
3. Retries the original request with new token
4. Transparent to the workflow execution

Timeout Configuration

Different operations support configurable timeouts:

• Drive operations: Default 300 seconds (5 minutes)
• Document download: Default 300 seconds (5 minutes)
• Document upload: Default 600 seconds (10 minutes)
• Bulk operations: Default 600 seconds (10 minutes)

Rate Limiting

Bulk operations include built-in rate limiting:

• 100ms delay between individual operations in bulk upload/download
• Prevents Microsoft Graph API throttling
• Maximum batch size: 50 files per operation

OData Filtering

The list operation supports OData filter expressions:

Common filter expressions:
- startswith(name,'prefix')
- endswith(name,'.pdf')
- size gt 1000000 (size greater than 1MB)
- size lt 5000000 (size less than 5MB)
- folder ne null (folders only)
- file ne null (files only)
- createdDateTime ge 2026-01-01T00:00:00Z

Best Practices

1. Default to the User's OneDrive: Leave driveId empty unless you specifically need a shared drive — this is the most common and least error-prone path.

2. Store Drive IDs for Reuse: When you do work with shared drives, cache the drive ID rather than calling drive.list on every run.

3. Batch Operations: Use bulkUpload and bulkDownload operations when working with multiple files to reduce API calls.

4. Respect Batch Limits: Stay within the 50-file limit for bulk operations to avoid timeouts and resource exhaustion.

5. Monitor File Sizes: Be aware of the 250MB file size limit and the 4MB resumable upload threshold.

6. Use Appropriate Timeouts: Increase timeout values for large file operations or bulk operations with many files.

7. Leverage OData Filters: Use OData filtering in list operations to reduce result sets and improve performance.

8. Handle Errors Gracefully: Bulk operations return partial results with an errors array — process both successes and failures.

9. Base64 Encoding: Ensure file content is properly base64 encoded before passing to upload operations.

10. Clean Up Regularly: Use the delete operation to remove obsolete files and maintain organization.

11. Normalize Folder Paths: The integration handles path normalization, but consistent formatting improves readability.

12. Store Item IDs: After upload, store returned item IDs for future operations (download, delete, getMetadata).

Drive ID and Item ID Formats

OneDrive uses opaque Microsoft Graph identifiers for both drives and items:

Drive ID

b!{base64-like-blob}
Example: b!abc123def456GHI789jkl012MNO345pqr678

For the signed-in user's personal OneDrive, you can leave driveId empty — the integration targets /me/drive directly without needing the explicit ID.

Item ID

01{alphanumeric}
Example: 01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

Item IDs are returned by every upload, list, search, and metadata operation. Store them when you need to operate on a file later (download, delete, getMetadata).

Response Structure

Drive List Response

{
  "value": [
    {
      "id": "b!abc123...",
      "driveType": "business",
      "name": "OneDrive",
      "owner": {
        "user": {
          "displayName": "Jane Smith"
        }
      },
      "webUrl": "https://contoso-my.sharepoint.com/personal/jane_smith_contoso_com/Documents"
    }
  ],
  "@odata.nextLink": "..."
}

File List Response

{
  "value": [
    {
      "id": "01ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
      "name": "document.pdf",
      "size": 2048576,
      "createdDateTime": "2026-01-15T10:30:00Z",
      "lastModifiedDateTime": "2026-01-20T14:45:00Z",
      "webUrl": "https://...",
      "file": {
        "mimeType": "application/pdf"
      }
    }
  ],
  "@odata.nextLink": "..."
}

Bulk Operation Response

{
  "files": [
    {
      "id": "...",
      "name": "...",
      "size": 1024000
    }
  ],
  "errors": [
    {
      "fileName": "failed.pdf",
      "error": "Upload failed: File too large"
    }
  ],
  "total": 5,
  "success": 4,
  "failed": 1
}

Troubleshooting

Common Issues and Solutions

Issue	Possible Solution
OAuth2 authorization fails	Verify client ID, client secret, and tenant ID are correct; check app registration in Microsoft Entra ID
Access denied errors	Ensure Files.ReadWrite.All permission is granted with admin consent
Token expired	The integration auto-refreshes tokens; if issues persist, re-authorize the credential
Drive not found	Verify the drive ID is correct; leave driveId empty to target the user's personal OneDrive
File upload fails	Check file size (max 250MB); ensure content is base64 encoded; verify folder path exists
Batch operation timeout	Reduce batch size or increase timeout parameter; check network connectivity
Rate limiting (429 errors)	Built-in delays should prevent this; if it occurs, increase delays between workflow runs
Large file upload fails	Files > 250MB are not supported; split or compress the file
Search returns no results	Verify query syntax; check if search indexing is complete for recently uploaded files
Invalid folder path	Ensure folder path uses forward slashes; path is case-sensitive
Download content not valid base64	Content is pre-encoded; don't double-encode when using downstream
"Personal Microsoft account" sign-in fails	This integration supports OneDrive for Business only — consumer accounts are not supported in this release

Error Response Format

Microsoft Graph API returns standardized error responses:

{
  "error": {
    "code": "itemNotFound",
    "message": "The resource could not be found.",
    "innerError": {
      "request-id": "abc123-def456-ghi789",
      "date": "2026-01-20T14:45:00"
    }
  }
}

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters or request format
401	Unauthorized - Invalid or expired access token
403	Forbidden - Insufficient permissions
404	Not Found - Drive, folder, or file does not exist
409	Conflict - Resource already exists or version conflict
413	Payload Too Large - File exceeds size limits
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Microsoft service error
503	Service Unavailable - Microsoft service temporarily unavailable

Security Considerations

1. Client Secret Protection: Store client secrets securely; rotate regularly; never commit to version control.

2. Principle of Least Privilege: This integration only requires Files.ReadWrite.All — avoid adding broader scopes like Sites.ReadWrite.All unless other Microsoft integrations on the same app registration need them.

3. Token Security: Access and refresh tokens are stored encrypted in NINA's credential system.

4. Audit Logging: Enable Microsoft Entra ID audit logging to track all OneDrive access via the integration.

5. Conditional Access: Configure Microsoft Entra ID Conditional Access policies for additional security controls.

6. File Content Security: Be cautious when downloading files from external sources; implement virus scanning.

7. Data Classification: Respect data classification labels when uploading sensitive documents.

8. Personal vs Shared Drives: Be deliberate when operating on shared drives — actions touch resources visible to other team members.

9. Retention Policies: Ensure uploaded documents comply with organizational retention policies.

10. Network Security: Use HTTPS for all communications (enforced by Microsoft Graph API).

File Size Limits

• Small file upload (simple upload): < 4MB
• Large file upload (resumable upload session): 4MB - 250MB
• Maximum file size: 250MB (Microsoft Graph API limit)
• Chunk size (large uploads): 10MB per chunk
• Bulk operation limit: 50 files per batch

API Permissions Required

The integration requires the following Microsoft Graph API delegated permissions:

Permission	Description	Required For
Files.ReadWrite.All	Have full access to user files	All drive and document operations
offline_access	Maintain access to data	Token refresh functionality

Additional Resources

• Microsoft Graph API Documentation
• OneDrive REST API Reference
• Microsoft Entra ID App Registration Guide
• Microsoft Graph Permissions Reference
• OData Query Parameters
• Upload Large Files with an Upload Session
• Microsoft Graph Best Practices
• Troubleshooting Microsoft Graph

Updated: 2026-05-12