> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO with Microsoft Entra ID

> Connect Microsoft Entra ID (Azure AD) to KnoxCall over SAML 2.0 — enterprise application, claims, group claims, token encryption and Single Logout, with the exact values to paste.

# 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](/sso/domains) — 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**.

<Warning>
  **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](/sso/overview) for the whole story.
</Warning>

## 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**:

| Entra field                                    | Value                                          |
| ---------------------------------------------- | ---------------------------------------------- |
| **Identifier (Entity ID)**                     | `https://acme.knoxcall.com/saml/acme/metadata` |
| **Reply URL (Assertion Consumer Service URL)** | `https://acme.knoxcall.com/saml/acme/acs`      |
| **Sign on URL**                                | `https://acme.knoxcall.com/saml/acme/login`    |
| **Logout Url**                                 | `https://acme.knoxcall.com/saml/acme/slo`      |

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](/sso/overview#more-than-one-identity-provider).

<Note>
  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](#5-take-the-entra-values-back-to-knoxcall), and it is a snapshot for the same reason.
</Note>

## 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](/sso/overview#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](/sso/overview#roles-what-an-assertion-may-and-may-not-do)).

## 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:

```http theme={"dark"}
POST /admin/saml/connections/<id>/metadata
{ "url": "https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml" }
```

```http theme={"dark"}
POST /admin/saml/connections/<id>/metadata
{ "xml": "<EntityDescriptor …>" }
```

One or the other, never both — *"Send either { xml } — the document itself — or { url }, 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](/sso/overview#importing-your-idps-metadata). 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:

| KnoxCall field                                     | Where it is                            | Entra value                                                                     |
| -------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
| **IdP sign-in URL**                                | Connection tab                         | Login URL (`https://login.microsoftonline.com/<tenant-id>/saml2`)               |
| **IdP entity ID (optional)**                       | Connection tab                         | Microsoft Entra Identifier (`https://sts.windows.net/<tenant-id>/`)             |
| **Only admit specific domains**                    | Connection tab                         | leave it off to admit every domain you have proven; tick it to narrow to a list |
| **Create accounts automatically on first sign-in** | Connection tab                         | on, unless you invite everyone by hand                                          |
| **Default role**                                   | Attributes & groups tab                | `member` or `readonly`                                                          |
| **IdP signing certificate**                        | Certificates tab → *Add a certificate* | the Base64 certificate you downloaded (with or without the BEGIN/END lines)     |

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](/sso/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](/sso/overview#idp-initiated-sign-in) for how to switch it on and what it costs.