Skip to content
Docs
Voxbi Cockpit APIs
API Guides

Set up single sign-on (SSO)

Single Sign-On (SSO) lets your users sign in to Cockpit with their existing company account (Microsoft or a generic OpenID Connect provider) instead of a separate Cockpit password.

Overview

SSO is configured per PBX on the Authentication tab of the PBX settings. Cockpit supports two providers:

  • Microsoft - Microsoft Entra ID (Azure AD). Users sign in with the Microsoft account your organization issued them. This is the "Sign in with Microsoft" button on the login page.
  • OpenID Connect - a generic OIDC provider, for organizations that use something other than Microsoft.

You can also let Cockpit create user accounts automatically the first time someone signs in, so you do not have to add each person by hand.

Enable "Sign in with Microsoft"

  1. Open PBX settings and go to the Authentication tab.
  2. Turn on SSO sign-in. The SSO settings appear below it.
  3. Set SSO type to Microsoft.
  4. Decide whether to turn on SSO provisioning (see below). If you do, add at least one identity provider email domain (for example yourcompany.com).
  5. Save.

That is all that is needed on the Cockpit side. The first time a user clicks Sign in with Microsoft, Microsoft asks them to sign in and consent, then returns them to Cockpit signed in.

What each setting does

  • SSO sign-in - the master switch. When on, the "Sign in with SSO" option appears on the login page and the rest of the settings become available.
  • Force SSO sign-in on Cockpit - when on, users must sign in through SSO, and a Cockpit password no longer works. Leave it off if you still want the password form as a fallback.
  • SSO type - which provider to use: Microsoft or OpenID Connect.
  • SSO provisioning - when on, Cockpit creates a user account and its extension automatically the first time a person signs in through SSO, and keeps them in sync on each sign-in. This applies to both SSO types (Microsoft and OpenID Connect). When off, only people who already have a Cockpit account can sign in; unknown users are turned away, and Cockpit does not create accounts, assign extensions, or change existing users based on the provider.
  • Identity provider email domains - the email domains that belong to your organization (for example yourcompany.com). They tell Cockpit which PBX a newly provisioned user belongs to, so at least one domain is required when provisioning is on. This field is shown only when provisioning is enabled.

Checklist for your Microsoft administrator

If your users cannot sign in with Microsoft, most causes are settings inside your own Microsoft Entra tenant, not in Cockpit. Ask your Microsoft administrator to check the following in the Microsoft Entra admin center. None of these need one specific value in every organization, but overly restrictive settings will block sign-in.

Enterprise applications > Cockpit > Properties

  • Enabled for users to sign-in? should be Yes. If it is No, nobody in your tenant can sign in to Cockpit.
  • Assignment required? should be No. If it is Yes, only users you have explicitly assigned to the Cockpit app can sign in, which locks out everyone else (including softphone users that share the same app).

Enterprise applications > Consent and permissions

  • User consent settings - if set to Do not allow user consent, regular users cannot grant Cockpit access to their account themselves, so their first sign-in fails. Either allow user consent, or have an administrator grant admin consent once (see below).
  • Admin consent settings - if Users can request admin consent to apps they are unable to consent to is No and user consent is also blocked, users are stuck with no way forward until an administrator grants consent for the tenant.

Users > User settings

  • Users can register applications does not need to be on, but on a very locked-down tenant where nobody has ever signed in to Cockpit yet, a non-admin's first sign-in can fail here. If users hit a consent error, use admin consent below.

Enterprise applications > Cockpit > Users and groups

  • This is where you decide who may access the Cockpit admin panel. When SSO provisioning is enabled, assign the Voxbi Cockpit Admin app role to the users (or groups) who should manage the PBX. See Controlling who can access Cockpit for the full explanation. Without this role a new user cannot be created on their first sign-in.

Conditional Access

  • A Conditional Access policy that requires MFA, a compliant or joined device, or that blocks the application can silently prevent sign-in. Make sure no policy blocks the Cockpit sign-in app.

When your organization blocks users from consenting on their own, a Microsoft administrator can consent for the whole tenant once, after which every user can sign in normally.

On the Authentication tab, with SSO type set to Microsoft, use the Grant admin consent for Cockpit button. It opens Microsoft and applies to the tenant of whoever signs in, so a Global Administrator should be the one to click it.

How users and extensions are created (Microsoft)

When a new user is provisioned from a Microsoft sign-in, Cockpit reads their profile from Microsoft:

  • First and last name come from the Microsoft profile. If those are empty, Cockpit falls back to the display name.
  • The extension is taken from the first entry of the user's business phones in Microsoft Entra ID. If no business phone is set, the user is still created but without an extension, which you can assign manually afterwards.

Controlling who can access Cockpit

Cockpit is an administration panel, so not everyone in your organization should be able to sign in to it. You decide who can, from your own Microsoft Entra tenant, using the Voxbi Cockpit Admin app role, together with the identity provider email domains configured in Cockpit.

1. Turn on SSO provisioning. On the Authentication tab, enable SSO provisioning. Everything below applies only while this is on.

2. List your email domains in Cockpit. Add every email domain your users sign in with under Identity provider email domains (for example yourcompany.com). This tells Cockpit which PBX a newly provisioned user belongs to, and only these domains are accepted when a new account is created.

3. Assign the Voxbi Cockpit Admin app role in Microsoft. In the Microsoft Entra admin center, go to Enterprise applications > Cockpit > Users and groups and assign the Voxbi Cockpit Admin role to the users, or to a group, that should manage the PBX. Assigning a group is the easiest way to manage access at scale: add or remove members of the group in Entra and Cockpit access follows automatically.

How this behaves on sign-in, with provisioning enabled:

  • A new user (no Cockpit account yet) is created automatically only if they carry the Voxbi Cockpit Admin role and their email domain is listed. Without the role they are turned away with a clear message and no account is created, so unassigned staff cannot get in.
  • An existing user keeps their Cockpit account and is granted the matching role(s) on sign-in from what Microsoft reports. Removing the role in Entra does not delete their Cockpit account or strip their role on its own, so removing a person's access is still done in Cockpit; the app role governs who can be provisioned and which role(s) they receive.

With provisioning disabled, none of the above applies: only people who already have a Cockpit account can sign in, and Cockpit does not change anything about them from Microsoft. Their name, extension and roles are left exactly as configured in Cockpit.

OpenID Connect

For a generic OpenID Connect provider (for example Active Directory Federation Services (ADFS), Okta, or Keycloak), set SSO type to OpenID Connect and fill in the identity provider details (client ID, client secret, discovery URL, and related endpoints) under Identity providers. Because OIDC providers name their claims differently, an SSO identity field mapping lets you map the provider's claims onto Cockpit user fields. Microsoft accounts use a fixed, documented schema, so no mapping is needed there.

Just as with Microsoft, a user account and its extension are only created, and kept up to date, when SSO provisioning is enabled. With provisioning off, only people who already have a Cockpit account can sign in through OpenID Connect, and Cockpit leaves their account untouched.

Controlling who can access Cockpit (OpenID Connect)

Like Microsoft, OpenID Connect can restrict Cockpit to the right people, using the VoxbiCockpit.Admin value. Because every provider models roles differently, you tell Cockpit where to find it:

  1. Emit the value from your provider. Configure your identity provider so that its token includes a claim carrying the exact value VoxbiCockpit.Admin for the people who should administer the PBX (for example a group, an app role, or a custom claim, depending on your provider).
  2. Map the claim in Cockpit. In the SSO identity field mapping, add a row mapping Roles to the name of that claim (for example roles or groups).

Then, exactly as with Microsoft: a new user is provisioned only if their token carries VoxbiCockpit.Admin (otherwise they are turned away and no account is created), and existing users are granted the Cockpit Admin role on sign-in when it is present.

See also

Parts of this form, documented on their own pages.

PBX settings The PBX is your organization's tenant in Cockpit. Every other entity is scoped to it, and this page holds its organization-wide settings. Identity providers Connect a PBX to an external authentication service so users can log in with their corporate credentials via Single Sign-On.

Updated