Microsoft 365 User Directory Sync
The Microsoft 365 User Directory Sync integration automatically synchronizes your Microsoft 365 users with Vodia PBX extensions. This integration helps you maintain consistent user directories, automatically create extensions for new employees, and ensure your PBX always reflects your current Microsoft 365 organization structure.
Phone numbers in Microsoft 365 should be stored in a consistent format. The system uses business phone numbers from Microsoft 365 user profiles to populate extension cell phone contact information.
Enable automatic extension creation to streamline onboarding. New Microsoft 365 users will automatically receive PBX extensions without manual intervention. Use the "Disable Unmatched Extensions" feature to automatically deactivate extensions for users who have left your organization.
To allow users to log into their extension's web portal with their Microsoft 365 credentials, enable 'Sign in with Microsoft' within the PBX system settings.
Requirements
- Active Microsoft 365 subscription with appropriate permissions
- Azure AD administrator access for granting application consent
- Microsoft Graph API access with User.Read.All permissions
- Vodia PBX administrator access
Integration Setup
-
In the Tenant, under Advanced->CRM Integration, go to Microsoft 365 User Directory Sync:
-
Set the scope to All accounts
-
Click the "Admin Consent" button first
-
You will be redirected to Microsoft to authorize the connection
-
Log in with your Azure AD administrator credentials
-
Review and approve the requested permissions:
- Read all users' full profiles
- Maintain access to data (offline access)
noteImportant: Admin consent must be granted before obtaining OAuth tokens
-
After admin consent, click "OAuth Token"
-
Authenticate with your Microsoft 365 credentials
-
You will be automatically redirected back to Vodia PBX
-
You should see a green confirmation that the integration is active
noteImportant: You must click Save to store the retrieved tokens
- Optional: Enable "Automatic Extension Creation" checkbox for auto-sync
- Click Save to complete the setup
-
Integration Features
-
User Synchronization
- One-click sync: Import all Microsoft 365 users with a single button click
- User details: Imports display names, email addresses and phone numbers
- Smart selection: Choose which users to create extensions for
- Bulk operations: Create multiple extensions simultaneously
-
Automatic Extension Management
- Auto-creation: Automatically creates extensions for new Microsoft 365 users (when enabled)
- Conflict detection: Identifies and prevents duplicate email addresses and extension numbers
- Smart numbering: Automatically assigns next available extension numbers
- 12-hour sync: Checks for new users every 12 hours when auto-creation is enabled
-
Extension Cleanup
- Disable unmatched: One-click deactivation of extensions without corresponding M365 users
- Email matching: Compares extension emails with Microsoft 365 directory
- Safe operation: Only disables extensions, doesn't delete them
-
User Selection Interface
- Visual popup: Interactive interface for selecting users
- Conflict indicators: Real-time display of email and extension conflicts
- Bulk selection: Select all or individual users
- Auto-assign: Automatically assign sequential extension numbers
Using the Integration
-
Manual User Sync
- Click "Sync Users & Create Extensions" button
- A popup window displays all Microsoft 365 users
- Select users who need extensions
- Assign or auto-assign extension numbers
- Click "Create Extensions" to complete
-
Automatic Sync (When Enabled)
- System checks Microsoft 365 every 12 hours
- New users automatically receive extensions
- Extensions use sequential numbering
- Email notifications for conflicts (if configured)
-
Extension Cleanup
-
Click "Disable Unmatched Extensions"
-
System compares all extensions with M365 users
-
Extensions without matching M365 users are disabled
-
Review results showing disabled extensions
-
Conflict Management
The system detects three types of conflicts:
-
Email Conflicts
- Occurs when a Microsoft 365 user's email already exists on another extension
- Shown as red warning in the selection interface
- Prevents duplicate email addresses in the PBX
-
Extension Number Conflicts
- Occurs when the assigned number is already in use
- System suggests next available number automatically
- Manual override possible with conflict warning
-
Duplicate Selection Conflicts
- Prevents assigning the same extension number to multiple users
- Real-time validation during selection process
Troubleshooting
-
"Setup Required" Error
- Ensure both admin consent and OAuth token steps were completed
- Verify tokens were saved after authorization
- Check that integration shows as active
-
No Users Appearing
- Verify Microsoft 365 permissions are correctly granted
- Check network connectivity to Microsoft Graph API
- Ensure OAuth token hasn't expired
-
Auto-sync Not Working
- Confirm "Automatic Extension Creation" checkbox is enabled
- Check system logs for sync attempts every 12 hours
-
Extensions Not Created
- Review conflict warnings in the selection popup
- Ensure extension numbers are within allowed range
- Check that users have valid email addresses
-
Token Expiration
- Tokens automatically refresh, but may occasionally fail
- Click "OAuth Token" again to re-authenticate
- No data or settings will be lost
Best Practices
-
Initial Setup
- Clean up existing extensions before first sync
- Standardize email formats between M365 and PBX
- Plan extension numbering scheme in advance
-
Ongoing Management
- Run "Disable Unmatched Extensions" monthly
- Monitor auto-sync logs for conflicts
- Keep Microsoft 365 user profiles updated
Privacy and Security
- All data transmission uses secure HTTPS encryption with OAuth 2.0 authentication
- OAuth tokens are securely stored and automatically refreshed
- Integration uses Microsoft's standard application security model
- Only authorized PBX administrators can configure the integration
- User data is synchronized one-way from Microsoft 365 to Vodia PBX
- No PBX data is sent back to Microsoft 365
- Extension creation respects existing PBX security policies and permissions