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

# Microsoft Sign-In (Entra ID)

> Create a Microsoft Entra ID app registration for KnoxCall sign-in — supported account types, the Web redirect URI, a client secret (Value, not Secret ID), User.Read, and the allowed-directory list that stops other Entra tenants signing in.

# Microsoft Sign-In (Entra ID)

Adds a **Continue with Microsoft** button to the login page, backed by an app registration you own in Microsoft Entra ID (formerly Azure AD). Read [OAuth Sign-In Methods](/integrations/setup/oauth-sign-in) first — it explains when you need your own app (self-hosted deployments do; KnoxCall Cloud does not) and which scope to save under.

<Note>
  This is the OpenID Connect / OAuth object (an **App registration**). Enterprise SAML federation with Entra — claims, group mapping, token encryption, Single Logout — is a different object and a different guide: [SAML SSO with Microsoft Entra ID](/sso/entra-id).
</Note>

**Before you start**

* Permission to create app registrations in your directory (*Application Developer* or better; *Application Administrator* if your directory restricts registration).
* The **Authorized redirect URI** from the KnoxCall card — **Settings → Integrations → OAuth Sign-In Methods → Microsoft**. Self-hosted: set `MICROSOFT_OAUTH_REDIRECT_URI` first, as described [here](/integrations/setup/oauth-sign-in#self-hosted-set-the-redirect-uri-in-the-server-environment).
* Your **Directory (tenant) ID** — you will want it for step 4.

## 1. Register the application

1. [Entra admin center](https://entra.microsoft.com) → **Identity → Applications → App registrations → New registration**.
2. **Name**: for example `KnoxCall`.
3. **Supported account types**:
   * **Accounts in this organizational directory only (single tenant)** — the safe default for a company deployment. Microsoft itself then refuses sign-ins from any other directory.
   * **Accounts in any organizational directory (multitenant)** — only if people from *other* organisations must sign in. If you pick this, the allowed-directory list in step 4 becomes essential.
4. **Redirect URI**: platform **Web**, value from the KnoxCall card:
   * KnoxCall Cloud: `https://auth.knoxcall.com/callback`
   * Self-hosted: `https://<your host>/auth/microsoft/callback` (the value of `MICROSOFT_OAUTH_REDIRECT_URI`)
5. **Register**. On the **Overview** page copy the **Application (client) ID** and the **Directory (tenant) ID**.

## 2. Create a client secret

1. The app → **Certificates & secrets → Client secrets → New client secret**.
2. Description and expiry. Entra allows at most 24 months; pick the longest your policy allows and **diary the expiry** — sign-in stops the day it lapses, with no warning from KnoxCall.
3. **Add**, then copy the **Value** column immediately. It is masked as soon as you leave the blade.

<Warning>
  Copy the **Value**, not the **Secret ID**. The Secret ID is a GUID that identifies the secret; it is not the secret. Pasting it into KnoxCall fails at sign-in with an *invalid client secret* error (`AADSTS7000215`), not at save time.
</Warning>

## 3. Check API permissions

**API permissions** should show **Microsoft Graph → User.Read (Delegated)** — it is added by default on a new registration. That is the only permission KnoxCall uses. No application permissions, and no admin consent is needed beyond `User.Read` (users consent on first sign-in; you may grant admin consent for the directory to skip that prompt).

## 4. Enter it in KnoxCall

**Settings → Integrations** → scope → **OAuth Sign-In Methods** → **Microsoft** tab:

| Field                              | Value                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------- |
| **Authorized redirect URI**        | Read-only. The value you registered in step 1.                                        |
| **Client ID**                      | The *Application (client) ID*.                                                        |
| **Client secret**                  | The secret **Value** from step 2. Leave blank on a later edit to keep the stored one. |
| **Allowed directory (tenant) IDs** | Your *Directory (tenant) ID* — see below. Comma-separated if more than one.           |

**Save.**

### Restrict sign-in to your directory

With the allowed-directory list **empty**, KnoxCall uses Microsoft's `/common` endpoint, which accepts a sign-in from **any** Entra directory — including one anybody can create for free in minutes. The account still has to present a verified email, but "any directory" is rarely what you mean.

Put your directory ID in the box. With exactly one ID, KnoxCall addresses that directory's endpoints directly, so Microsoft refuses every other directory before KnoxCall is even involved; with several, KnoxCall checks the directory claim on every sign-in and refuses the rest. Leave it empty only if you deliberately chose *multitenant* in step 1 and want that behaviour.

On a self-hosted deployment `MICROSOFT_OAUTH_ALLOWED_TENANT_IDS` is the environment form of the same list.

## 5. Verify

Open the login page in a private window and click **Continue with Microsoft**. Sign in with an account in your directory; a first-time account is linked to an existing KnoxCall account with the same verified email, or created.

## Things that bite

* **`AADSTS50011`** — the redirect URI registered on the app is not the one KnoxCall sent. Compare byte for byte, including the platform: it must be **Web**, not *SPA* or *Mobile*.
* **`AADSTS7000215`** — invalid client secret. Almost always the Secret ID was pasted instead of the Value, or the secret has expired.
* **`AADSTS50020` / "user account does not exist in tenant"** — the person's account is in a directory the app does not admit (single-tenant registration, or the allowed-directory list). That is the control working.
* **Secrets expire.** Rotate before the date: create a second secret, save it in KnoxCall, then delete the old one. There is no overlap problem — KnoxCall holds one secret and uses it from the moment you save.
* **A stored row wins over environment variables.** Deleting the row on a self-hosted host that still carries `MICROSOFT_OAUTH_CLIENT_ID` / `_SECRET` falls back to those.

## Related

* [OAuth Sign-In Methods](/integrations/setup/oauth-sign-in) — scopes, account matching, environment variables, troubleshooting
* [Google](/integrations/setup/oauth-google) · [GitHub](/integrations/setup/oauth-github)
* [SAML SSO with Microsoft Entra ID](/sso/entra-id) — federated SSO instead of social sign-in