Skip to main content

​
OAuth Sign-In Methods

The OAuth Sign-In Methods card on Settings → Integrations holds up to three OAuth apps — one per provider — and the login page shows a Continue with … button for each one that is configured and enabled. This page covers what is common to all three; each provider has its own walkthrough: Google · Microsoft Entra ID · GitHub
This is social / OAuth sign-in, where the provider proves an email address and KnoxCall matches it to an account. For federated enterprise SSO — SAML 2.0 with your identity provider, domain verification and Single Logout — see Single Sign-On (SAML).

​
Do you need your own apps?

  • KnoxCall Cloud already has Google, Microsoft and GitHub wired to KnoxCall’s own OAuth apps. You do not need to configure anything for the buttons to work.
  • Self-hosted deployments must bring their own apps: KnoxCall’s production apps only accept redirect URIs on knoxcall.com, so a deployment on knox.example.com cannot reuse them.
Which scope to save under:

​
The redirect URI

Every provider asks for an authorized redirect URI (Google), redirect URI (Microsoft) or authorization callback URL (GitHub). The value must match what KnoxCall sends byte for byte — a trailing slash, a different scheme or a different path is a mismatch. The card shows the exact value for your deployment in the Authorized redirect URI box. It is the server’s answer, not something derived from the page you are looking at:

​
Self-hosted: set the redirect URI in the server environment

On a self-hosted deployment the shared /callback path is not routed, so point each provider straight at its handler on your own host and register the same value with the provider:
Restart the API after changing them. The card reads the live values, so it shows what you set. If a provider reports a mismatch, compare the two strings character by character — that is the entire diagnosis in almost every case.

​
What KnoxCall asks the provider for

KnoxCall requests the minimum needed to identify the person and read a verified email address: Sign-in is pure sign-in: the token from the provider is spent on one profile lookup and not stored. There is no offline access and no refresh token, and users are not asked to re-consent on every login. (Token injection for your upstream APIs is a different feature — see OAuth 2.0 secrets.)

​
How accounts are matched

  1. A returning user (same provider, same provider user id) signs straight in.
  2. Otherwise KnoxCall looks for an existing account with the same email address and links the provider to it — but only if the provider reports the address as verified. An unverified address is refused (error=unverified_email), because linking on an unverified address would let someone attach their provider identity to your account.
  3. Otherwise a new account is created from the verified email.
Email matching is case-insensitive. A person who signed up with a password can therefore add “Continue with Google” simply by signing in with the same address.

​
Configuring a provider

  1. Settings → Integrations → pick the scope → OAuth Sign-In Methods → Configure (or Edit).
  2. Choose the provider tab. A dot on each tab shows whether it is already configured.
  3. Copy the Authorized redirect URI into the provider’s app (see the provider guide for exactly where).
  4. Paste the provider’s Client ID and Client secret and Save. Microsoft has one more field, the allowed directory IDs — read that guide before leaving it blank.
  5. Open the login page in a private window and use the new button.
Disconnect on a provider tab removes the app; people who only ever signed in with that provider will need another sign-in method (a magic link or a passkey still works for them).

​
Environment variables (self-hosted)

The client credentials can also come from the environment. A stored row wins; the variables are the fallback when no row exists. MICROSOFT_OAUTH_ALLOWED_TENANT_IDS is the environment form of Microsoft’s allowed-directory list.

​
Troubleshooting