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: a Pro or 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.
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.
1. Create the application
- Entra admin centre → Enterprise applications → New application → Create your own application.
- 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: fetchhttps://acme.knoxcall.com/sso/acme/entra/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. It leaves Sign on URL and Relay State empty, because SAML metadata has no element for either: set the Sign on URL from the table below, and leave Relay State blank. The document is served while the connection is still in Draft or Testing, so this works before KnoxCall has any of Entra’s values; only a Disabled connection has none.
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 values for a connection whose handle is
entra, which is the handle the setup wizard gives a new Entra ID connection: /sso/<workspace>/<handle>/{metadata,acs,login,slo}. Step 2 of the wizard shows your connection’s own values, each with a copy button, and so does the connection’s Certificates tab. A workspace set up before the wizard may have a default connection instead, whose values are the /saml/<workspace>/… alias — https://acme.knoxcall.com/saml/acme/acs and its three siblings. 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
objectidsource 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/emailaddressclaim, 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. Entra fills it fromuser.mailby default, anduser.mailis empty for an account with no mailbox — common in a test tenant, and for any user without an Exchange licence. If your user principal names are real addresses at a domain you have proven, change the claim’s source touser.userprincipalname. A sign-in with no address is refused with the reasonemail_missing. - Keep the default
.../claims/displaynameclaim. KnoxCall reads it, and the address claim, without any configuration.
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 IDemits object GUIDs; a directory synced from Active Directory can emitsAMAccountNameinstead. 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/groupsto 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.
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
First, choose what Entra signs. KnoxCall accepts a signature on the response or on the assertion, so Entra’s default, Sign SAML assertion, signs people in. Signing both is recommended. If you turn on token encryption (step 7), the response must be signed — Sign SAML response or Sign SAML response and assertion — because an encrypted assertion is accepted only inside a signed response. On the Single sign-on blade, section 3 (SAML Certificates) → Edit → Signing Option → Sign SAML response and assertion → Save. With encryption on and the default left in place, every sign-in is refused withsaml_failed, and the workspace audit log records the reason as an assertion rejected with Invalid document signature.
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:<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.
Save. Saving needs a re-authentication in the last five minutes; that is expected. One re-authentication then covers every SSO save you make from the same signed-in session for fifteen minutes after it, so adding a certificate, claiming a domain and starting a test do not each ask again. Another browser or device asks for its own.
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 before you activate. Leave the connection in Testing and use its Test tab: it sends a real sign-in through Entra, runs every check a login runs — signature, audience, timing, and the domain and account rules — and shows you the result and the NameID Entra sent, without signing anyone in. Sign-in also needs at least one domain proven for single sign-on; the test tells you if the address Entra sent is not covered. When the test passes, set the connection to Active and try one real account: openhttps://acme.knoxcall.com/sso/acme/entra/login, sign in, and check the person lands in the workspace with the role you expected. If a real sign-in fails, the login page shows only a short code, on purpose; the reason is in the workspace’s audit log, as a login refused entry on the connection — 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, with one condition: set Signing Option to Sign SAML response or Sign SAML response and assertion first (step 5), because an encrypted assertion is accepted only inside a signed response. The assertion inside the encryption does not need a signature of its own.- 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. - Save it as a
.cerfile. - Enterprise application → Token encryption → Import Certificate → Activate.
8. Single Logout (optional)
Entra sends aLogoutRequest 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 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:- In Entra, create the new signing certificate but leave the current one active.
- Add the new certificate to the KnoxCall connection. Pasting a certificate adds it — both verify while both are active and neither has expired.
- Make the new certificate active in Entra.
- Retire the old certificate in KnoxCall.
The app launcher tile
With the Sign on URL from step 2 set, clicking KnoxCall in My Apps sends the person to that URL, so it is an ordinary SP-initiated sign-in and works with IdP-initiated sign-in switched off. Leave Sign on URL blank and the tile POSTs an unsolicited assertion instead — an IdP-initiated sign-in, which is off unless you turn it on. With it off the person is bounced back to the login page withsaml_idp_initiated_disabled. See IdP-initiated sign-in for how to switch it on and what it costs.