Microsoft 365 Setup

Overview

This guide walks you through connecting your Microsoft 365 / Entra ID (formerly Azure AD) tenant to VeloPBX. The integration is registered as a Single-Tenant application in Microsoft Entra ID and authorized via OAuth 2.0.

Setup time: ~12 minutes. Tenant admin only.

By the end of this guide, your VeloPBX tenant will be able to:

• Sync users from Microsoft 365 — auto-create PBX extensions for all (or selected) Entra ID users
• Sync personal contacts — pull each user’s Outlook contacts into the PBX directory
• Sync calendar events — calls during meetings can hold or route to a backup
• Sync shared mailboxes and groups — for distribution-list call routing
• Single Sign-On (SSO) — users sign into the VeloPBX Web Portal and PortSIP ONE app with their Microsoft 365 credentials

Microsoft Teams Direct Routing is a related but separate setup. It uses the same Entra ID app but adds SBC configuration, base + subdomain DNS, and a wildcard SSL certificate. See the Teams Direct Routing notes at the bottom of this guide.

Prerequisites

Before you start, make sure you have:

• A Microsoft 365 / Entra ID tenant with admin access to Microsoft Entra ID → App registrations
• A regular Microsoft 365 user account that will be the integration owner (ideally a service account, not a personal admin)
• Tenant Admin Full Access in VeloPBX
• Browser access to both the Microsoft Entra admin center and your VeloPBX Web Portal at the same time

National cloud: If your Microsoft 365 tenant runs on Azure China rather than Azure Global (the default), make a note of it now — VeloPBX has a separate national_cloud=CHINA configuration option. Most tenants run on Global.

Step 1 — Sign into Microsoft Entra ID

Open the Microsoft Entra admin center at https://entra.microsoft.com/ and sign in with a Microsoft 365 administrator account.

If you only have access to the older Azure portal at https://portal.azure.com/, that works too. Navigate to Microsoft Entra ID there.

Step 2 — Create a new App registration

1. In the left navigation, expand Identity → Applications and click App registrations.
2. Click + New registration at the top.
3. Fill in the form:

• Name: VeloPBX Integration (or any name your team will recognize)
• Supported account types: select Accounts in this organizational directory only (Single tenant)
• Redirect URI: leave blank for now — you’ll add this in Step 5 after VeloPBX shows you the exact URL

1. Click Register.

Microsoft Entra ID creates the app and shows you the Overview page.

Why single tenant? VeloPBX integrates with one M365 tenant per VeloPBX tenant. Multi-tenant mode would let any Microsoft user authorize the app — undesirable for an internal CRM/PBX integration.

Step 3 — Copy the Application (client) ID and Directory (tenant) ID

On the Overview page of your newly registered app, copy these two values to a secure location:

Important: These two IDs are the only values you’ll paste into VeloPBX. Treat the Application ID like a username (not secret) and the Directory ID like an organization fingerprint (not secret either, but useful for verification).

Step 4 — Open the integration page in VeloPBX

In a new browser tab, sign into the VeloPBX Web Portal as a tenant administrator at:

https://pbx.fortis-tele.com:8887

In the left navigation, click Advanced, then Microsoft 365 Integration.

Note: If you don’t see the Microsoft 365 Integration menu item, your tenant doesn’t have the M365 feature enabled. Tenant admins with View Only can see the page but cannot configure. Ask your VeloPBX system administrator to enable it under Tenants → your tenant → Feature Management → Microsoft 365.

Step 5 — Copy the Redirect URI(s) from VeloPBX

VeloPBX displays one or two Redirect URI values:

• Without SBC: one Redirect URI is shown — typically https://:8887/api/auth/callback/ms365
• With SBC configured: two Redirect URIs are shown — one for the PBX direct path and one routed through the SBC

Copy the URI(s) to your clipboard. You’ll paste them back into Microsoft Entra ID in the next step.

Step 6 — Add the Redirect URI(s) in Microsoft Entra ID

1. Go back to your Entra ID browser tab.
2. In your app’s left navigation, click Authentication.
3. Under Platform configurations, click Add a platform → Web.
4. In the Redirect URIs field, paste the first Redirect URI from VeloPBX.
5. Click Configure.
6. If VeloPBX showed two URIs, you’ll come back to this Authentication page after Step 8 to add the second one. Don’t try to add both at once — Entra ID has finicky validation.
7. Click Save at the top.

Important: The Redirect URI must match VeloPBX’s value exactly — protocol (https://), host, port, and path (/api/auth/callback/ms365). No trailing slash.

Step 7 — Paste the IDs into VeloPBX

1. Switch back to your VeloPBX tab.
2. Paste the Application (client) ID from Step 3 into the corresponding field.
3. Paste the Directory (tenant) ID as well.
4. Set National cloud — keep GLOBAL unless you’re on Azure China.
5. Click Save. VeloPBX stores the IDs but the connection is not active yet.

Step 8 — Authorize and complete OAuth

1. In VeloPBX, click the Authorize button (or “Complete the authorization” link).
2. A new browser tab opens with Microsoft’s sign-in screen.
3. Sign in with the Microsoft 365 user that should own the integration (typically a service account dedicated to PBX integrations, not a personal admin).
4. Microsoft prompts you to consent to the permissions VeloPBX is requesting (read users, read contacts, read calendar events, etc.).
5. Click Accept.
6. Microsoft redirects back to VeloPBX. The integration becomes active immediately.

If VeloPBX displayed two Redirect URIs in Step 5, repeat Step 6 now to add the second URI — but be aware that authorization will fail without the second URI in place when you go through SBC routing.

Step 9 — Configure user synchronization

After authorization succeeds, VeloPBX exposes a User Sync tab with the following toggles. Recommended defaults shown:

Important: When sync_type is set to INCLUDE, only the users you list in selected_users are synced. When set to EXCLUDE, all users except those listed are synced. ALL ignores the selection list.

Save your settings. The first sync runs immediately; subsequent syncs honor sync_time.

Step 10 — Configure Single Sign-On (optional but recommended)

1. In VeloPBX, click the Sign In tab.
2. Under Sign in as Administrator, toggle enabled On if you want admins to use M365 SSO. Add the admin Principal Names to selected_users.
3. Under Sign in as Standard User, toggle enabled On for end-user SSO. Set sync_type (ALL for all M365 users, INCLUDE/EXCLUDE for selective).
4. Click Save.

After saving, a Microsoft icon appears on the login pages of:

• The VeloPBX Web Portal
• The PortSIP ONE desktop and mobile apps

Users click the Microsoft icon and sign in with their M365 credentials — the PBX recognizes them via the Entra ID Principal Name match.

Settings reference

Once connected, all settings can be edited any time on Advanced → Microsoft 365 Integration at https://pbx.fortis-tele.com:8887. Changes take effect on the next sync cycle — to force a sync immediately, click Sync now on the User Sync tab.

Verify it works

1. User sync: open the Users & Extensions page in VeloPBX. New extensions should appear matching your M365 user list, starting at the starting_extension_number you set.
2. Personal contacts: sign into PortSIP ONE as one of the synced users. Open the contacts panel — you should see entries from that user’s Outlook contacts.
3. Events / calendar awareness: create a test calendar event in Outlook for the next 5 minutes. When the event starts, place a test call to that user’s extension — VeloPBX should respect the busy state per your call-routing rules.
4. SSO: sign out of VeloPBX. On the Web Portal sign-in page, click the Microsoft icon. You should be redirected to Microsoft, sign in with your M365 credentials, and land back in the VeloPBX dashboard.

Troubleshooting

“AADSTS50011: Reply URL mismatch”

The Redirect URI in your Entra ID app doesn’t match what VeloPBX sends. Common causes:

• Trailing slash mismatch (/callback/ms365/ vs /callback/ms365)
• HTTPS vs HTTP
• Wrong port (Entra ID typically defaults to no port; VeloPBX uses :8887)
• Different host (e.g. SBC vs PBX URL)

Fix the Redirect URI in Entra ID → your app → Authentication and try Step 8 again.

“AADSTS650053: Insufficient privileges”

The user signing in during Step 8 doesn’t have permission to consent on behalf of the organization. Either:

• Sign in as a user with Cloud Application Administrator or higher, or
• Have a Global Admin pre-grant admin consent in Entra ID → your app → API permissions → Grant admin consent

Users aren’t syncing

• Confirm the users.enabled toggle is On.
• Check users.sync_type — if INCLUDE, only listed users sync.
• Click Sync now to bypass the schedule.
• Verify the integration owner (the user who authorized in Step 8) still has User.Read.All permission in their Entra ID role.

Calendar events don’t drive call routing

• Verify the user has events.enabled and is in selected_users (or sync_type=ALL).
• Confirm the user’s Outlook calendar is the default calendar — VeloPBX reads only the primary calendar.
• Verify your tenant’s call-routing rule is set to honor presence/calendar state.

“Invalid client secret” — don’t see this error

Microsoft 365 integration uses public client OAuth (no client secret required). If you see “client_secret missing” or similar, you’ve configured an extra “secret” in Entra ID that VeloPBX doesn’t expect. Remove it from the Certificates & secrets tab and re-authorize.

National cloud confusion

If your tenant lives on Azure China but you set national_cloud=GLOBAL, authorization fails with “tenant not found” or “endpoint not reachable.” Set national_cloud=CHINA in VeloPBX and re-authorize.

Teams Direct Routing

Teams Direct Routing lets your M365 users dial PSTN numbers from inside Microsoft Teams, with VeloPBX handling the call routing and recording. It uses the same Entra ID app you registered above, but the additional setup involves:

• A base domain (e.g. pbx.acme.com) that resolves to your VeloPBX SBC
• Subdomain mapping per tenant (e.g. tenant1.pbx.acme.com, tenant2.pbx.acme.com)
• A wildcard SSL certificate for *.pbx.acme.com from a public CA
• A PowerShell session (Microsoft Teams module) to register the SBC as a PSTN gateway

Direct Routing is a separate (heavier) setup beyond the scope of this guide. For the full walkthrough see Microsoft’s Configure a Session Border Controller for multiple tenants and contact a routing engineer — we typically pair on Direct Routing setup live since the DNS + SSL + PowerShell sequence is unforgiving.

FAQ

Do I need an E5 / Phone System license? For user sync, contacts, calendar, SSO — no. Standard Business / E1 / E3 / E5 all work. Only Teams Direct Routing requires a Phone System license (E5 includes it; E1/E3 need the Phone System add-on).

Can multiple VeloPBX tenants connect to the same M365 tenant? Yes — each VeloPBX tenant creates its own Entra ID app registration. Sync runs independently per VeloPBX tenant.

What permissions does VeloPBX request? The minimum for the configured features:

• User.Read.All — read all M365 users in the directory (for user sync)
• Contacts.Read — read users’ personal contacts
• Calendars.Read — read calendar events
• Group.Read.All — read groups (only when groups are configured)
• offline_access — refresh tokens for unattended sync

What happens if the integration owner leaves the company? Their refresh token becomes invalid when their M365 account is deactivated. Sync stops and SSO breaks. Fix: have a different active admin re-authorize from Step 8.

Can I rotate the Application ID? The Application (client) ID is permanent — it’s the app’s identity. To “rotate,” create a brand new Entra ID app registration and re-paste the new Application + Directory IDs into VeloPBX. The old app can then be deleted in Entra ID.

Need help?

If you get stuck (especially on Reply URL mismatches or admin-consent issues), talk to a routing engineer — we can pair on the Entra ID flow live and have your first synced extension running within 24 hours.