Overview

Microsoft 365 Integration connects your Cloud-PBX with the Microsoft ecosystem, enabling seamless authentication, presence synchronization, calendar-based availability, and unified communications across Teams, Outlook, and your phone system.

Integration Components:

• Azure Active Directory: Single sign-on and user provisioning
• Microsoft Teams: Presence synchronization and click-to-call
• Outlook/Exchange: Calendar integration and contact sync
• Microsoft Graph API: Unified data access across services

Key Benefits:

• One-click sign-in with corporate Microsoft credentials
• Real-time presence shared between phone system and Teams
• Automatic DND based on Outlook calendar
• Company directory automatically synced
• Click-to-call from Outlook and Teams

Features

Single Sign-On (SSO) via Azure AD

Authentication Flow:

1. User clicks "Sign in with Microsoft" on Cloud-PBX
2. Redirected to Microsoft login (login.microsoftonline.com)
3. Enters corporate credentials ([email protected])
4. Multi-factor authentication if required by policy
5. Grants permissions to Cloud-PBX (first time only)
6. Redirected back to Cloud-PBX and automatically logged in

Auto-Provisioning:

• New users automatically created when they first sign in
• User attributes populated from Azure AD (name, email, department)
• Extension assigned from available pool
• Permissions based on Azure AD group membership
• Profile photo synced from Microsoft 365

Security Features:

• OAuth 2.0 secure authentication
• Conditional Access policies enforced
• Multi-factor authentication required if enabled
• Session timeout follows Azure AD settings
• Automatic token refresh (no repeated logins)
• Audit logs for all authentication events

Teams Presence Synchronization

Bi-Directional Presence Sync:

Automatic Presence Updates:

• Call starts in Cloud-PBX → Teams shows "Busy"
• Teams call starts → Cloud-PBX shows busy (calls to voicemail)
• Teams meeting active → Cloud-PBX enables DND
• User sets DND in Cloud-PBX → Teams shows "Do Not Disturb"
• User idle for 5 minutes → Both show "Away"

Presence Rules:

Priority (highest to lowest):
1. Presenting (Teams screen share) → DND
2. On a call (either system) → Busy  
3. In a meeting (Teams or calendar) → Busy
4. Do Not Disturb (manually set) → DND
5. Away/Inactive → Away
6. Default → Available

Configuration Options:

• Enable/disable presence sync per user
• Set priority when statuses conflict (Teams vs Cloud-PBX)
• Configure away timeout (default: 5 minutes)
• Override presence manually when needed
• Quiet hours: Disable sync outside work hours

Outlook Calendar Integration

Calendar-Based Availability:

Calendar Event Type → Cloud-PBX Behavior
────────────────────────────────────────
Busy Event          → DND, calls to voicemail
Out of Office       → Custom greeting, route to backup
Tentative           → Calls ring, but warn caller
Free                → Normal call routing
Working Elsewhere   → Route to mobile preferred
Focus Time          → DND, suppress notifications

Event Handling:

• Buffer Time: Enable DND 5 minutes before/after meetings
• All-Day Events: Respect "Out of Office" responses
• Recurring Events: Handle series without performance impact
• Time Zones: Automatically adjust for user's current zone
• Private Events: Only free/busy status used (details hidden)

Calendar Selection:

• Primary calendar: Default, most common
• All calendars: Monitor work, personal, shared
• Specific calendars: Choose which to sync
• Ignore all: Disable calendar integration

Pre-Meeting Reminders:

• Notification 5 minutes before scheduled calls
• Option to start call directly from reminder
• Automatic DND enabled 2 minutes before
• Meeting details displayed (subject, attendees)

Exchange Contact Sync

Contact Information Synced:

• Full name, display name, and preferred name
• Job title and department
• Email addresses (all types)
• Phone numbers (work, mobile, home, other)
• Office location and company
• Manager and direct reports
• Profile photo (high resolution)
• Last updated timestamp

Sync Configuration:

Navigate to: Settings → Integrations → Microsoft 365
Contact Sync: Enable
Sync Scope: All Users
Update Frequency: Every 15 minutes
Photo Sync: Enabled

Sync Scope: Selected Groups
Choose Groups:
  ☑ Sales Department
  ☑ Customer Support
  ☐ Engineering (excluded)

External Contacts: Enable/Disable
Shared Contact Lists: Enable
Distribution Lists: Convert to groups
Public Folders: Sync specified folders

Contact Display:

• Caller ID shows contact name and photo from Outlook
• Click contact in Cloud-PBX to open in Outlook
• Recent call history visible in Cloud-PBX contact card
• Updates reflected within 15 minutes

Click-to-Call from Outlook and Teams

Outlook Integration:

• Right-click any phone number → "Call with Cloud-PBX"
• Click phone number in contact card → Instant call
• Call button in email signature lines
• Quick call from meeting invitations (call organizer)

Installation Requirements:

• Cloud-PBX Desktop Client installed (Windows/Mac)
• Outlook COM add-in enabled
• User signed in to desktop client

Teams Integration:

• Click phone number in Teams chat → Cloud-PBX call
• Call from user profile card in Teams
• Teams directory shows Cloud-PBX availability
• Call transfer between Teams and Cloud-PBX

Browser-Based (Outlook Web):

• Install Cloud-PBX Chrome/Edge extension
• Click phone numbers in Outlook on the web
• Extension detects and highlights numbers
• One-click calling from any page

Call Logging: All calls initiated via click-to-call are automatically logged with:

• Contact name and number
• Call direction (outbound via Outlook)
• Source (Outlook email, Teams chat, contact card)
• Call duration and outcome
• Recording link (if enabled)

Setup Guide

US Region: https://admin.voco.us/auth/microsoft/callback
EU Region: https://admin.voco.eu/auth/microsoft/callback
AP Region: https://admin.voco.au/auth/microsoft/callback

Navigate to: Settings → Integrations → Microsoft 365 → Provisioning

Auto-Create Users: Enabled
Extension Pool: 2000-2999
Default Permissions: Standard User
Group Mapping: Configure below

Azure AD → Cloud-PBX
─────────────────────
displayName → Full Name
mail → Email Address
jobTitle → Job Title
department → Department
mobile → Mobile Number
manager → Reports To

Subject: New Login Method for Cloud-PBX

We've integrated Cloud-PBX with Microsoft 365!

✅ No more separate passwords - use your Microsoft login
✅ Your phone shows busy when in Teams meetings
✅ Calendar events automatically enable Do Not Disturb
✅ Click phone numbers in Outlook to call instantly

How to use:
1. Visit admin.voco.us
2. Click "Sign in with Microsoft"
3. Use your regular company credentials

Questions? Contact IT support or see our quick start guide.

Advanced Configuration

Conditional Access Policies

What It Is: Azure AD Conditional Access allows you to enforce security policies when users sign in to Cloud-PBX.

Common Policies:

• MFA Required: Force multi-factor authentication for Cloud-PBX access
• Device Compliance: Only allow managed/compliant devices
• Location-Based: Restrict access to specific countries/IP ranges
• Risk-Based: Block sign-ins from risky locations or anomalous behavior

Example Policy:

Policy Name: Cloud-PBX Access Control
Assignments:
  Users: All Users
  Cloud Apps: Cloud-PBX Integration
Conditions:
  Locations: Allowed countries only
  Device State: Require compliant device
Access Controls:
  Grant: Require MFA
  Session: Sign-in frequency = 8 hours

Configuration:

1. Azure Portal → Azure AD → Security → Conditional Access
2. Create new policy → Target Cloud-PBX app registration
3. Define conditions and access controls
4. Enable policy → Cloud-PBX honors policy on next login

Teams Phone Integration

Native Teams Integration: If your organization uses Teams Phone System, you can integrate Cloud-PBX as a Direct Routing provider.

Benefits:

• Make/receive Cloud-PBX calls within Teams interface
• Unified dial pad in Teams
• Call history visible in both platforms
• Transfer calls between Teams and Cloud-PBX seamlessly

Requirements:

• Microsoft Teams Phone license
• Teams Direct Routing configured
• SBC (Session Border Controller) or Cloud-PBX SIP trunk

Setup Overview:

1. Configure Cloud-PBX SIP trunk for Teams
2. Add SBC to Teams admin center
3. Create voice routing policies
4. Assign policies to users
5. Test inbound/outbound calls via Teams

Detailed Setup: See Teams Direct Routing Guide

Calendar Event Types and Behavior

Granular Control Over Calendar Handling:

Event Type               DND    Route Behavior
──────────────────────────────────────────────────
Standard Meeting         Yes    Voicemail
Teams Meeting            Yes    Voicemail + Teams sync
Out of Office            Yes    Custom greeting → backup
Focus Time               Yes    Silent (no voicemail notification)
Working Elsewhere        No     Route to mobile first
Tentative                No*    Ring but warn caller
Free (Default)           No     Normal routing
All-Day Event            No*    Check "Show As" status

* Configurable per user preference

Custom Rules:

• Certain meeting subjects always ring (e.g., "URGENT")
• VIP callers bypass DND during meetings
• After-hours meetings don't affect routing
• Recurring meetings: Only trigger DND during event times

Configuration Path:

Settings → Integrations → Microsoft 365 → Calendar Rules

Contact Photo Sync and Caching

Photo Resolution:

• High-res: 504x504 pixels (default for profiles)
• Thumbnail: 96x96 pixels (contact lists)
• Small: 48x48 pixels (notifications)

Cache Strategy:

• Photos cached for 7 days (reduce API load)
• Force refresh if user updates profile photo
• Fallback to initials if photo unavailable

Bandwidth Considerations: For large organizations (2000+ users):

• Enable thumbnail-only mode (save 90% bandwidth)
• Lazy-load photos (fetch when contact viewed)
• Disable photo sync for remote/bandwidth-limited users

Group-Based Permissions and Features

Map Azure AD Groups to Cloud-PBX Features:

Azure AD Group           Cloud-PBX Features
─────────────────────────────────────────────────
Executives               • International calling
                         • Private call recording
                         • Custom hold music
                         • Mobile app

Sales-Team               • CRM integration enabled
                         • Click-to-call everywhere
                         • Call recording auto-enabled

Support-Team             • Queue membership
                         • Limited outbound (local only)
                         • Screen recording

Remote-Workers           • Softphone required
                         • Mobile app required
                         • Calendar sync (time zones)

Configuration:

Settings → Integrations → Microsoft 365 → Group Mapping

Map Group: "Sales-Team" (Azure AD)
  → Features:
     ☑ Enable CRM Integration
     ☑ International Calling Allowed
     ☑ Call Recording Default On
     ☑ Mobile App Access
  → Extension Range: 2000-2999

Troubleshooting

SSO Login Issues

Problem: "AADSTS50011: The reply URL specified in the request does not match"

Solution:

• Verify redirect URI in Azure app registration exactly matches Cloud-PBX
• Common mistake: http:// vs https:// or trailing slash
• Check: Azure Portal → App Registration → Authentication → Redirect URIs

Problem: "AADSTS65001: User or administrator has not consented"

Solution:

• Admin must grant consent for organization
• Azure Portal → App Registration → API Permissions → Grant admin consent
• Or: User can consent individually (if allowed by policy)

Problem: "AADSTS700016: Application not found in directory"

Solution:

• Application (Client) ID incorrect in Cloud-PBX settings
• Verify Client ID matches Azure app registration
• Check tenant ID is correct (for multi-tenant orgs)

Presence Sync Issues

Problem: Teams status not updating when on Cloud-PBX call

Requirements Check:

• ✅ User has Teams Phone license (required for presence API)
• ✅ Presence.Read.All permission granted in Azure AD
• ✅ User signed in to both Cloud-PBX and Teams
• ✅ Teams desktop app (not web) for best results

Diagnostic Steps:

1. Check integration status: Settings → Integrations → Microsoft 365
2. Should show "Presence Sync: Active"
3. Review presence logs: Settings → System → Logs → Presence Events
4. Look for error codes (AADSTS... or Graph API errors)

Common Fix: Re-authorize integration

Settings → Integrations → Microsoft 365
→ Click "Reauthorize" button
→ Sign in with admin account
→ Grant all permissions again

Known Limitations:

• Presence update delay: 15-30 seconds typical
• Teams web app: Limited presence sync
• FreeBusy updates faster than detailed status
• Some presence states require Teams desktop

Calendar Sync Issues

Problem: Meetings not triggering Do Not Disturb

Checklist:

• ✅ Calendar integration enabled (Settings → Integrations → Microsoft 365)
• ✅ User granted Calendars.Read permission during SSO
• ✅ Event marked as "Busy" (not Free or Tentative)
• ✅ Event is on primary calendar (not shared/secondary)
• ✅ Time zone settings correct in both systems
• ✅ Calendar sync status shows "Active"

Manual Sync Test:

Settings → Integrations → Microsoft 365 → Calendar
→ Click "Sync Now" for specific user
→ Check last sync time updates
→ Review sync log for errors

Calendar Permission Re-Grant: If user initially denied calendar permission:

1. User signs out of Cloud-PBX
2. Admin: Settings → Integrations → Microsoft 365 → Reset User Consent
3. User signs in again via SSO
4. Grant Calendars.Read when prompted

All-Day Events: By default, all-day events don't trigger DND. To enable:

Settings → Integrations → Microsoft 365 → Calendar Rules
→ All-Day Events: Check "Show As" status
→ If "Out of Office", enable custom greeting

Contact Sync Issues

Problem: Contacts not appearing or incomplete

Diagnostic Steps:

1. Check sync status: Settings → Integrations → Microsoft 365 → Contacts
2. Review last sync time (should be <15 minutes ago)
3. Check error count (any failed syncs?)
4. Verify permission granted: Contacts.Read and User.ReadBasic.All

Force Full Resync:

Settings → Integrations → Microsoft 365 → Contacts
→ Click "Clear Cache and Resync"
→ Wait 2-3 minutes
→ Refresh contact list

Large Organization Performance: For 2000+ users, sync may take 10-15 minutes:

• Enable incremental sync (only changes)
• Use group-based sync (filter departments)
• Consider nightly full sync instead of real-time

Profile Photos Not Showing:

• Check permission: User.ReadBasic.All includes photos
• Large photos may take time to download (7-day cache)
• Fallback: Initials shown until photo cached
• Force refresh: Clear photo cache and resync

Click-to-Call Issues

Problem: Click-to-call not working in Outlook

Windows Requirements:

• Cloud-PBX Desktop Client installed and running
• COM add-in enabled in Outlook
• User signed in to desktop client
• Telephony provider registered in Windows

Check COM Add-in:

Outlook → File → Options → Add-ins
→ Manage: COM Add-ins → Go
→ Verify "Cloud-PBX for Outlook" is checked
→ If missing, reinstall desktop client

Mac Requirements:

• Cloud-PBX Desktop App installed
• Accessibility permissions granted: System Preferences → Security & Privacy → Privacy → Accessibility → Add Cloud-PBX app
• Restart Outlook after installation

Browser (Outlook Web):

• Install Cloud-PBX Chrome or Edge extension
• Extension should detect and highlight phone numbers
• Click green phone icon next to numbers
• Check extension has permissions: Right-click extension icon → Manage

Number Format Issues: Click-to-call detects these formats:

+1-555-123-4567
(555) 123-4567
555-123-4567
555.123.4567
5551234567
+44 20 1234 5678 (international)

If number not detected, it may be in unsupported format.

Security Best Practices

Least Privilege Access

Recommended Permissions (minimum required):

• User.Read: Read signed-in user profile only
• User.ReadBasic.All: Read all users' basic info (directory)
• Calendars.Read: Read user calendars
• Presence.Read: Read user's own presence
• Presence.Read.All: Read all presence (for Teams sync)

Avoid Granting (unless specifically needed):

• Mail.Read: Email content access (not needed for integration)
• Files.Read: OneDrive/SharePoint access
• Directory.ReadWrite.All: Write access to directory
• Calendars.ReadWrite: Calendar modification

Principle: Request only the permissions absolutely necessary for features you enable.

Token Security

Token Lifecycle:

• Access tokens: Valid 1 hour
• Refresh tokens: Valid 90 days
• Tokens auto-refresh without user interaction
• Expired refresh tokens require re-authorization

Token Storage:

• Encrypted at rest (AES-256)
• Stored in secure credential vault
• Never logged or exposed in UI
• Automatically deleted on user sign-out

Revocation: User or admin can revoke access:

1. Cloud-PBX: Settings → Integrations → Disconnect
2. Microsoft: Account Settings → Apps → Remove Cloud-PBX
3. Azure AD Admin: App Registrations → Delete app (org-wide)

Audit and Compliance

Audit Logging: All integration events logged:

• SSO authentication attempts (success/failure)
• Permission grants and revocations
• Calendar sync events
• Presence updates
• Contact sync operations
• API errors and rate limits

Log Retention:

• Authentication logs: 1 year
• Sync activity logs: 90 days
• Error logs: 180 days
• Audit exports available: CSV or JSON

Access Audit Logs:

Settings → System → Audit Logs → Filter
→ Category: Microsoft 365 Integration
→ Date Range: Last 30 days
→ Event Type: All / Authentication / Sync / Errors
→ Export to CSV

Compliance Features:

• GDPR data subject requests: Export user's integration data
• Right to erasure: Delete user's synced data
• Data processing agreement available (Enterprise)
• SOC 2 Type II compliant

Performance Optimization

Large Organization Best Practices

For 2000+ Users:

Contact Sync:

• Use group-based sync (filter departments)
• Incremental sync only (not full resync every time)
• Disable photo sync or use thumbnails only
• Schedule full resync nightly (off-peak hours)

Presence Sync:

• Enable for active users only (not entire org)
• Use webhooks instead of polling (more efficient)
• Cache presence for 1 minute (reduce API calls)

Calendar Sync:

• Real-time for executives and sales
• 15-minute polling for general users
• Disable for users who don't need it

API Rate Limits: Microsoft Graph throttling limits:

• 2000 requests per second per app
• 10,000 requests per 10 minutes per user

Mitigation:

• Batch API calls (up to 20 requests per batch)
• Implement exponential backoff on 429 errors
• Use delta queries (only fetch changes, not full data)
• Cache aggressively where possible

Monitoring Integration Health

Key Metrics to Monitor:

• Authentication success rate (should be >99%)
• Average token refresh time (<500ms)
• Contact sync duration (<5 minutes for full sync)
• Calendar sync lag (should be <2 minutes)
• API error rate (<1% of requests)
• Presence update delay (<30 seconds)

Set Up Alerts:

Settings → Integrations → Microsoft 365 → Health Monitoring

Alert When:
  ☑ Authentication failure rate > 5%
  ☑ Sync fails 3 times consecutively
  ☑ API error rate > 5%
  ☑ Last successful sync > 30 minutes ago
  ☑ Token refresh fails

Notification Method: Email IT team

Dashboard: Create a monitoring dashboard showing:

• Integration status (green/yellow/red)
• Last successful sync times
• Error count (last 24 hours)
• Active users via SSO
• API usage vs. limits

Frequently Asked Questions

Q: Do users need Microsoft 365 licenses? A: Yes, each user must have a valid Microsoft 365 license that includes Azure AD (most business/enterprise plans include this). Basic authentication features work with all plans, but Teams presence sync requires Teams Phone license.

Q: Can we use multiple Azure AD tenants? A: Yes, Enterprise plans support multi-tenant configurations. Each tenant requires separate app registration and configuration.

Q: What happens if Microsoft Graph API is down? A: Cloud-PBX continues to function normally. SSO may fallback to password login. Cached contact and presence data used until API recovers. No call functionality is affected.

Q: Can users have different email domains? A: Yes, Azure AD supports multiple verified domains. Users with any verified domain can use SSO.

Q: How do we handle guest users? A: Guest users (external Azure AD) can authenticate via SSO if your Azure AD allows guest access. They appear as external users in Cloud-PBX and may have limited permissions.

Q: Can we customize the SSO login button? A: Yes, branding customization available: Settings → Integrations → Microsoft 365 → Branding

• Button text: "Sign in with [Company Name]"
• Button color: Match corporate branding
• Logo: Display company logo on login page

Q: Does this work with on-premises Active Directory? A: Requires Azure AD (cloud). If you use on-premises AD, you must sync to Azure AD using Azure AD Connect first.

Q: Can we force MFA for Cloud-PBX only? A: Yes, use Azure AD Conditional Access to target Cloud-PBX app specifically. Force MFA for Cloud-PBX without affecting other apps.

Q: What's the user experience for first-time login? A: User clicks "Sign in with Microsoft" → Microsoft login → Grant permissions screen (lists what Cloud-PBX can access) → User clicks Accept → Redirected to Cloud-PBX. Subsequent logins skip permission screen.

Getting Help

Resources:

• Video Tutorial: Complete setup walkthrough (20 minutes)
• Azure AD Checklist: Printable setup guide
• Permission Guide: Detailed explanation of each API permission
• Troubleshooting Flowchart: Diagnose common issues

Next Steps