Skip to content
Thirdlane

Directory Services

Directory Services connect Thirdlane to the identity provider your organization already uses (Azure AD / Microsoft Entra ID, Okta, or LDAP / Active Directory) so you provision phone users from a single source of truth instead of re-creating them by hand. When staff join, change, or leave in your directory, a sync brings those changes into the PBX - saving time, reducing errors, and keeping extensions aligned with your real headcount. Three providers are supported:

  • Azure Active Directory (Microsoft Entra ID) — via OAuth2 and Microsoft Graph API
  • Okta — via OAuth2 and Okta Users API
  • LDAP / Active Directory — via standard LDAP protocol

To configure a directory service integration, navigate to Integrations > Directory Services and click Create Directory Service Integration.

Select the Directory Service Provider from the dropdown. The form will show the configuration fields appropriate for the selected provider.

Azure Active Directory (Microsoft)

Microsoft Configuration

Register the application in Azure Active Directory as described in the Microsoft documentation: https://learn.microsoft.com/en-us/power-apps/developer/data-platform/walkthrough-register-app-azure-active-directory

Requirements for setting up application registration:

  • Supported account types should be set as: “Accounts in any organizational directory (Any Azure AD directory - Multitenant)”
  • Application platform must be set as Web
  • Redirect URI must be set to https://YOUR_PBX_FQDN/service/oauth2/microsoft/callback (replace YOUR_PBX_FQDN with your real FQDN)
  • Implicit grant flows and hybrid flows should be set as: “Access tokens (used for implicit flows)” and “ID tokens (used for implicit and hybrid flows)”

A new Client secret should be created in the “Certificates & secrets” menu (note and save the value of the Client secret in notepad as this value will only be shown once).

Please make sure that you save the Client ID and Client Secret once they are provided by Microsoft — you will need them when configuring Azure Active Directory integration in Thirdlane.

The following delegated permissions must be granted (followed by the “Grant admin consent” action) from the API permissions menu:

  • offline_access
  • User.Read
  • User.Read.all
  • Directory.Read.all

Thirdlane Configuration

FieldDescription
Client IDThe Application (client) ID from your Azure app registration
Client SecretThe client secret value created in Certificates & secrets

Once saved, click the authentication icon (person) to authenticate as a user with read access to Azure AD. When authentication is completed, refresh the screen — a green indicator confirms success.

Note that there is a delay between information changes in Azure Active Directory and those changes being available for synchronization.

Okta

Okta Configuration

Create a new application integration in the Okta Admin Console:

  1. Navigate to Applications > Applications and click Create App Integration
  2. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type
  3. Set the Sign-in redirect URI to https://YOUR_PBX_FQDN/service/oauth2/okta/callback
  4. Under Assignments, choose the appropriate access policy for your users

Note your Client ID and Client Secret from the application settings page.

Thirdlane Configuration

FieldDescription
Okta DomainYour Okta organization domain (e.g., yourcompany.okta.com)
Client IDThe Client ID from your Okta application
Client SecretThe Client Secret from your Okta application

Required user profile fields in Okta for synchronization:

  • First name
  • Last name
  • Email
  • Work phone (used as the extension number)

LDAP / Active Directory

LDAP integration connects directly to any LDAP-compatible directory (OpenLDAP, Microsoft Active Directory, FreeIPA, authentik LDAP Outpost, etc.) using standard LDAP bind and search operations.

Thirdlane Configuration

Connection Settings

FieldDescription
LDAP ServerHostname or IP address of your LDAP server
PortLDAP port (default: 389 for LDAP/STARTTLS, 636 for LDAPS)
SecurityNone (unencrypted), STARTTLS (upgrade to TLS on port 389), or LDAPS (SSL on port 636)
Bind DNThe distinguished name used to authenticate to the LDAP server (e.g., cn=service,ou=svcaccts,dc=example,dc=com)
Bind PasswordPassword for the Bind DN account
Base DNThe search base for finding users (e.g., dc=example,dc=com)
Search FilterLDAP filter to identify user entries (see table below)

Attribute Mapping

These fields control which LDAP attributes are mapped to PBX extension fields. Defaults work for most standard LDAP directories:

PBX FieldDefault AttributeActive DirectoryDescription
ExtensiontelephoneNumberipPhone or customUsed as the extension number
First NamegivenNamegivenNameUser’s first name
Last NamesnsnUser’s last name
EmailmailmailUser’s email address
MobilemobilemobileUser’s mobile number
Unique IDentryUUIDobjectGUIDTracks users across syncs

The Unique ID attribute is critical for tracking users between syncs. If the attribute is not present on an entry, the system falls back to the entry’s DN (Distinguished Name).

Directory TypeRecommended Filter
OpenLDAP(objectClass=inetOrgPerson)
Active Directory(objectClass=user)
FreeIPA(objectClass=inetOrgPerson)
authentik LDAP Outpost(objectClass=inetOrgPerson)

Test Connection

After entering the LDAP settings, use the Test Connection button to verify connectivity. The test will:

  1. Connect to the LDAP server on the specified port
  2. Perform a bind with the provided credentials
  3. Execute a search with the configured filter
  4. Report the number of users found

The Test Connection button is available before saving — you can verify settings work before committing them.

What Happens After Configuration

After configuring any directory service provider, you need to perform an initial Directory Sync to import users into the PBX. Subsequent syncs can be triggered manually or run automatically on an hourly schedule.

Worked example: import users from Active Directory over LDAPS

Goal: create PBX extensions from the “Staff” people in example.com Active Directory, using each person’s ipPhone value as their extension, over an encrypted connection.

  1. Create a read-only service account in AD, e.g. cn=pbx-sync,ou=svcaccts,dc=example,dc=com, with permission only to read user objects.
  2. Start the integration. Go to Integrations > Directory Services, click Create Directory Service Integration, and select provider LDAP / Active Directory.
  3. Connection settings. LDAP Server dc01.example.com, Security LDAPS, Port 636, Bind DN cn=pbx-sync,ou=svcaccts,dc=example,dc=com, Bind Password the service account password, Base DN ou=Staff,dc=example,dc=com, Search Filter (objectClass=user).
  4. Attribute mapping. AD stores desk numbers in ipPhone, so set Extension to ipPhone (the default telephoneNumber would pull the wrong number). Leave First Name givenName, Last Name sn, Email mail, and set Unique ID to objectGUID so renames track correctly.
  5. Test before saving. Click Test Connection. It binds as the service account, runs the filter, and reports something like “Found 42 users”. If it reports 0 or an error, fix the Base DN / filter / credentials now - not after saving.
  6. Save and do the initial import. Save the integration, then run a Directory Sync. Review the preview (created / updated / skipped) before committing; each imported person becomes a User Extension numbered from their ipPhone.
  7. Keep it current. Leave the hourly sync on so joiners and leavers flow through automatically, and trigger a manual sync right after a big onboarding or offboarding rather than waiting for the schedule.

The synced extensions show a green Sync indicator in the User Extensions grid, and their name/email/mobile are maintained by the directory from then on.

Best practices

  • Test the connection before the first sync. For LDAP, use Test Connection to confirm the bind and filter return the expected number of users; for Azure/Okta, verify the green authentication indicator.
  • Scope the search filter tightly. A precise filter (or a dedicated OU/group) imports only the people who should have extensions, avoiding service accounts and disabled users.
  • Preserve the Unique ID mapping. The unique-id attribute (entryUUID / objectGUID) is how the sync tracks a person across runs; without it, renames can create duplicate users.
  • Use a dedicated, read-only service account for LDAP. Bind with an account that has only the read access it needs, and prefer STARTTLS or LDAPS so credentials aren’t sent in the clear.
  • Do a manual sync after big directory changes. Rather than waiting for the hourly job, trigger a sync right after onboarding or offboarding so the PBX reflects reality promptly.