SharePoint Integration

LibreChat provides enterprise-grade integration with SharePoint Online and OneDrive for Business, enabling users to seamlessly browse, select, and attach files from their Microsoft 365 environment directly within conversations.

Overview

The SharePoint integration allows users to:

• Browse SharePoint document libraries and OneDrive files
• Select multiple files at once (up to 10 by default)
• View real-time download progress
• Attach files from SharePoint to conversations
• Maintain enterprise security with proper access controls

Prerequisites

Before configuring SharePoint integration, ensure you have:

1. Azure Entra ID Authentication configured and working
2. Token Reuse enabled (OPENID_REUSE_TOKENS=true)
3. An exposed API scope for LibreChat, such as api://<client-id>/access_as_user
4. Admin access to your Azure tenant for app permissions
5. HTTPS enabled (required for production environments)

Azure App Registration Setup

Step 1: Configure API Permissions

1. Navigate to your app registration in the Azure Portal
2. Go to API permissions in the left menu
3. Click Add a permission

Step 2: Expose and Grant a LibreChat API Scope

The on-behalf-of flow needs the initial OpenID access token to target your LibreChat app API, not Microsoft Graph. Expose an API scope so Azure can issue a token with LibreChat as the audience.

1. Go to Expose an API in the left menu
2. Set the Application ID URI to api://<client-id> if it is not already configured
3. Click Add a scope
4. Name the scope access_as_user
5. Save the scope, then copy the full scope value:

api://<client-id>/access_as_user

Then grant that scope to the app registration:

1. Go back to API permissions
2. Click Add a permission
3. Select APIs my organization uses
4. Search for and select your LibreChat app registration
5. Choose Delegated permissions
6. Select access_as_user
7. Click Add permissions

Use the full api://<client-id>/access_as_user scope value in OPENID_SCOPE later in this guide.

Step 3: Add SharePoint Permissions

For the file picker interface:

1. Select SharePoint from the API list
2. Choose Delegated permissions
3. Search for and select:
   • AllSites.Read - Read items in all site collections
4. Click Add permissions

Step 4: Add Microsoft Graph Permissions

For file downloads:

1. Click Add a permission again
2. Select Microsoft Graph
3. Choose Delegated permissions
4. Search for and select:
   • Files.Read.All - Read all files that user can access
5. Click Add permissions

Step 5: Grant Admin Consent

1. After adding the permissions, you'll see them listed
2. Click Grant admin consent for [Your Organization]
3. Confirm the consent in the popup

Your permissions should look like this:

Environment Configuration

Add the following environment variables to your .env file:

# OpenID token reuse and OBO-compatible audience
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=openid profile email offline_access api://<client-id>/access_as_user
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
 
# Enable SharePoint file picker
ENABLE_SHAREPOINT_FILEPICKER=true
 
# Your SharePoint tenant base URL
# Format: https://[your-tenant-name].sharepoint.com
SHAREPOINT_BASE_URL=https://contoso.sharepoint.com
 
# SharePoint scope for the file picker
# Replace 'contoso' with your actual tenant name
SHAREPOINT_PICKER_SHAREPOINT_SCOPE=https://contoso.sharepoint.com/AllSites.Read
 
# Microsoft Graph scope for file downloads
SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read.All

How It Works

Authentication Flow

1. User authenticates via Azure Entra ID
2. When accessing SharePoint picker, LibreChat exchanges the user's token for SharePoint access
3. Tokens are cached for optimal performance (typically 50 minutes)
4. Separate scopes ensure principle of least privilege

File Selection Process

1. User clicks "From SharePoint" in the attachment menu
2. SharePoint Online file picker opens in an embedded iframe
3. User browses and selects files using familiar SharePoint interface
4. Selected files are queued for download

Download Process

1. Files are downloaded in batches (up to 3 concurrent downloads)
2. Progress indicator shows current file and percentage complete
3. Downloaded files are attached to the conversation
4. Failed downloads are retried automatically

User Experience

Accessing SharePoint Files

When properly configured, users will see a new option in the file attachment menu:

1. Click the attachment icon in the message input
2. Select "From SharePoint" from the menu
3. The SharePoint file picker will open
4. Browse and select files as needed
5. Click "Select" to begin downloading

Features Available

• Multiple file selection: Select up to 10 files at once
• Familiar interface: Uses native SharePoint file picker
• Progress tracking: See real-time download progress
• Error handling: Clear messages for any issues
• Localization: Supports multiple languages

Security Considerations

Access Control

• Only files the user has permission to access in SharePoint are available
• Respects all SharePoint permissions and policies
• No elevated access or bypassing of security controls

Token Security

• Uses secure on-behalf-of flow for token exchange
• Tokens are short-lived and automatically refreshed
• No long-term storage of SharePoint credentials

Scope Isolation

• SharePoint scope limited to read operations only
• Graph API scope restricted to file read access
• Cannot modify or delete files through LibreChat

Troubleshooting

Common Issues

"From SharePoint" option not appearing

Cause: Feature not properly enabled or authentication issues

Solutions:

1. Verify ENABLE_SHAREPOINT_FILEPICKER=true in .env
2. Confirm OPENID_REUSE_TOKENS=true is set
3. Check that user is authenticated via Azure Entra ID
4. Restart LibreChat after configuration changes

File picker fails to open

Cause: Missing or incorrect permissions

Solutions:

1. Verify SharePoint permissions are granted in Azure
2. Ensure admin consent was provided
3. Check that SHAREPOINT_BASE_URL matches your tenant exactly
4. Confirm SHAREPOINT_PICKER_SHAREPOINT_SCOPE uses the full tenant URL, such as https://contoso.sharepoint.com/AllSites.Read
5. Confirm HTTPS is enabled in production

File picker opens to a blank white page

Cause: Azure may be rejecting the on-behalf-of exchange because the OpenID access token has the wrong audience, or because the userinfo token exchange is not enabled.

Solutions:

1. Confirm your Azure app registration has an exposed API scope, such as api://<client-id>/access_as_user
2. Add that full scope to OPENID_SCOPE
3. Set OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
4. Restart LibreChat and sign in again so Azure issues fresh OpenID tokens

Downloads fail or timeout

Cause: Graph API permissions or network issues

Solutions:

1. Verify Files.Read.All permission is granted
2. Check network connectivity to SharePoint
3. Ensure tokens haven't expired (re-authenticate if needed)
4. Check browser console for specific error messages

Debug Mode

For troubleshooting, enable debug logging:

DEBUG_LOGGING=true
DEBUG_CONSOLE=true

This will provide detailed logs about:

• Token exchange processes
• API calls to SharePoint and Graph
• Download progress and errors
• Authentication flows

Performance Optimization

Token Caching

• Tokens are cached to reduce authentication overhead
• Cache duration matches token lifetime (typically 50 minutes)
• Automatic refresh before expiration

Concurrent Downloads

• Up to 3 files download simultaneously
• Prevents overwhelming the browser or server
• Optimizes for both speed and stability

File Size Considerations

• Large files may take time to download
• Progress indicator helps manage user expectations
• Consider your file upload limits in LibreChat configuration

Best Practices

For Administrators

1. Regular Permission Audits: Review app permissions periodically
2. Monitor Usage: Track SharePoint integration usage in logs
3. Update Documentation: Keep internal docs updated with your tenant specifics
4. Test Thoroughly: Verify functionality after any Azure AD changes

For End Users

1. File Organization: Well-organized SharePoint libraries improve user experience
2. File Sizes: Be mindful of large files that may slow conversations
3. Permissions: Ensure you have access to files before sharing
4. Patient Downloads: Allow time for multiple or large files

Advanced Configuration

Custom Scopes

For organizations with specific requirements, you can customize scopes:

# Example: Limiting to specific site collections
SHAREPOINT_PICKER_SHAREPOINT_SCOPE=https://contoso.sharepoint.com/sites/Engineering/AllSites.Read
 
# Example: Using more restrictive Graph permissions
SHAREPOINT_PICKER_GRAPH_SCOPE=Files.Read

Integration with Information Barriers

If your organization uses Information Barriers:

• SharePoint integration respects all barrier policies
• Users only see content they're allowed to access
• No additional configuration required

Related Documentation

• Azure Entra Authentication
• OpenID Token Reuse
• Microsoft Graph API Integration
• File Upload Configuration