Skip to main content

​
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 first — it explains when you need your own app (self-hosted deployments do; KnoxCall Cloud does not) and which scope to save under.
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.
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.
  • Your Directory (tenant) ID — you will want it for step 4.

​
1. Register the application

  1. Entra admin center → 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.
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.

​
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: 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.