Skip to main content

​
SAML SSO with Microsoft Entra ID

This is the full path for Entra ID (formerly Azure AD): create the enterprise application, exchange metadata, map claims, and — optionally — switch on token encryption and Single Logout. Before you start
  • KnoxCall: an Enterprise plan, the owner or admin role, and at least one domain verified for single sign-on — a domain you verified for sending mail is a different proof and does not admit a login.
  • Entra: permission to create and manage enterprise applications (Application Administrator or better). Token encryption additionally needs Entra ID P1 or P2.
Configured KnoxCall before 8 September 2026? Re-upload our SP metadata (or re-import the metadata URL) before you go further. KnoxCall now signs AuthnRequests, publishes an encryption key, and publishes a Single Logout endpoint — an Entra app built from the older document will not offer Token encryption at all, may reject our signed requests, and has no SLO URL for us. See the call-out on the overview page for the whole story.

​
App registration or enterprise application?

Both objects exist for every app, and only one of them does SAML.
  • An App registration defines an application and its API permissions. It is the OpenID Connect / OAuth object. SAML is not configured here.
  • An Enterprise application is the instance of an app in your tenant — assignments, conditional access, claims, and Single sign-on → SAML.
For KnoxCall you create a non-gallery enterprise application. Creating it also creates the underlying registration; you never need to open it.

​
1. Create the application

  1. Entra admin centre → Enterprise applications → New application → Create your own application.
  2. Name it (for example KnoxCall), choose Integrate any other application you don’t find in the gallery (Non-gallery), and create.

​
2. Give Entra the KnoxCall URLs

Open the app → Single sign-on → SAML. The fastest route is Upload metadata file: fetch https://acme.knoxcall.com/saml/acme/metadata (replace acme with your workspace slug — it is public, so a browser will do) and upload the XML. Entra fills in the identifier, reply URL and logout URL from the document. To type them instead, edit Basic SAML Configuration: The same values are in the dashboard under Settings → Single sign-on, ready to copy. These are the default connection’s values — the connection every workspace starts with, and the one the /saml/<workspace>/… alias resolves to. If Entra ID is a second identity provider for this workspace, it gets its own connection with its own handle, and its values are /sso/<workspace>/<handle>/{metadata,acs,login,slo} — for a handle of entra, https://acme.knoxcall.com/sso/acme/entra/metadata and its three siblings. Open that connection under Settings → Single sign-on and its Certificates tab lists all five, each with a copy button. See more than one identity provider.
Uploading metadata is a snapshot. Entra does not re-read the document later, so whenever KnoxCall’s SP metadata changes you re-upload it. That is the entire reason for the call-out at the top of this page. The exchange in the other direction — KnoxCall reading Entra’s metadata — is step 5, and it is a snapshot for the same reason.

​
3. Configure claims

Select Edit in the Attributes & Claims section, then:
  • The NameID — make it a stable identifier. Open the Name identifier value and choose the objectid source attribute, which Microsoft describes as “The object ID of the user in Microsoft Entra ID”. It does not change when the person is renamed. Entra’s default is the user principal name, which usually does — and a NameID that changes on a rename gives the renamed person a second KnoxCall account. Why this matters, and why KnoxCall does not merge the two afterwards: choosing the NameID.
  • The address — keep the .../claims/emailaddress claim, and check that its source attribute holds a real address at a domain you have verified for everyone who will sign in. With a stable NameID, this claim is the only place KnoxCall finds the person’s address, so a person whose source attribute is empty cannot be admitted.
  • Keep the default .../claims/displayname claim. KnoxCall reads it, and the address claim, without any configuration.
Then check what Entra actually sends. KnoxCall’s sign-in request names the email-address NameID format, and Microsoft documents that Entra “honors the format in the request” when a request names one; it does not document which value accompanies that format once the source is objectid. So once step 5 is done, run a sign-in from the connection’s Test tab in KnoxCall and read the NameID in the verdict. A GUID means you are done. An address means Entra is still sending one — the connection will keep showing its NameID notice, and it will be right to. KnoxCall reads nothing else from the assertion. There is no role claim to send: an IdP-asserted login may only ever confer member or readonly (see roles).

​
4. Group claims (optional)

Only needed if you want group membership to decide whether a new person lands as member or readonly. In Attributes & Claims → Add a group claim:
  • Choose Groups assigned to the application. Not “All groups” — Entra truncates large group claims, and the assigned set is the one that describes this app.
  • Source attribute: Group ID emits object GUIDs; a directory synced from Active Directory can emit sAMAccountName instead. Whatever you choose is what you map in KnoxCall — if Entra sends GUIDs, the KnoxCall group map keys are those GUIDs.
  • Customize the name of the group claim → emit groups as role claims changes the claim name from http://schemas.microsoft.com/ws/2008/06/identity/claims/groups to the role URN. KnoxCall reads the groups URN out of the box; if you emit as roles, name the role claim as the connection’s group attribute or the map will never match.
Map groups to roles on the KnoxCall connection. The bound is absolute — a group mapped to anything but member or readonly is refused at save time: “Group 'Engineering' maps to 'owner'; an IdP group may only map to member or readonly — an IdP-asserted login may never mint an administrator (elevate members on the team page).“

​
5. Take the Entra values back to KnoxCall

There are two routes: import Entra’s federation metadata, or type the three values by hand. The import is the one that cannot be mis-transcribed.

​
Import the federation metadata

Entra publishes the entity ID, the sign-on endpoints, the logout endpoint and the signing certificates in one document. On the Single sign-on blade, section 3 (SAML Certificates) carries both forms of it: App Federation Metadata Url, and Federation Metadata XML as a download. Hand either one to KnoxCall:
One or the other, never both — “Send either — the document itself — or , where to fetch it from — but not both.” The <id> is the connection’s id, which is in the address bar when you have the connection open. The call previews by default; nothing is written until you send it again with "apply": true — what the preview reports, what an import never touches, and every refusal it can answer with are on the overview. Two Entra-specific notes:
  • An Entra export made before you switched Single Logout on has no SingleLogoutService; the import leaves your stored SLO URL alone rather than reading the absence as “turn it off”.
  • KnoxCall stores the URL you imported from, but nothing re-reads it on a schedule. When Entra rolls its signing certificate, run the import again — or paste the new certificate — which is the add-first rotation at the bottom of this page.

​
Or type the three values

Still on the Single sign-on blade:
  • SAML Certificates → download Certificate (Base64).
  • Set up KnoxCall → copy the Login URL and the Microsoft Entra Identifier.
In KnoxCall, Settings → Single sign-on → your connection: Save. Saving needs a re-authentication in the last five minutes; that is expected.

​
6. Assign users, then test

Users and groups → assign the people or groups who should have KnoxCall. Entra refuses sign-in to anyone unassigned, before KnoxCall ever sees a request. Test with one account: open https://acme.knoxcall.com/saml/acme/login, sign in, and check the person lands in the workspace with the role you expected. If it fails, the message on the login page names the cause — see troubleshooting.

​
7. Token encryption (optional)

Entra can encrypt the assertion to KnoxCall’s public key. KnoxCall accepts encrypted and plain assertions alike, so this is your call, not ours.
  1. Fetch KnoxCall’s SP metadata and take the certificate from the use="encryption" KeyDescriptor. It is the same certificate as the signing one, published twice on purpose — Entra reads the encryption descriptor and nothing else when offering this feature.
  2. Save it as a .cer file.
  3. Enterprise application → Token encryption → Import Certificate → Activate.
If Token encryption is missing from the app’s menu, either your Entra edition does not include it or the app was configured from SP metadata that predates our encryption key — re-upload the metadata.

​
8. Single Logout (optional)

Entra sends a LogoutRequest to the Logout Url you set in step 2. Nothing else is needed for the IdP-initiated direction. For the other direction — a person signing out of KnoxCall also signing out of Entra — set the connection’s IdP single-logout URL to https://login.microsoftonline.com/<tenant-id>/saml2 (the same endpoint Entra publishes for logout in its federation metadata). It must be https, and KnoxCall refuses anything else at save time — the refusal names the field and says why, because a LogoutRequest carries the person’s email address as the NameID and the browser is redirected to that URL.

​
Rotating the Entra certificate

Entra certificates expire, and Entra will email the address in Notification Email Addresses before they do. Rotate add-first:
  1. In Entra, create the new signing certificate but leave the current one active.
  2. Add the new certificate to the KnoxCall connection. Pasting a certificate adds it — both verify while both are active.
  3. Make the new certificate active in Entra.
  4. Retire the old certificate in KnoxCall.
Retiring the only active certificate is refused: “This is the connection’s only active IdP certificate. Add the new certificate first, then retire this one.”

​
The app launcher tile

Clicking KnoxCall in the Microsoft app launcher is an IdP-initiated sign-in, and it is off unless you turn it on. With it off the person is bounced back to the login page with saml_idp_initiated_disabled. See IdP-initiated sign-in for how to switch it on and what it costs.