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

# OAuth Sign-In Methods

> Let people sign in to KnoxCall with Google, Microsoft or GitHub using your own OAuth apps — the one redirect URI all three share, the scopes requested, which scope to save under, and the environment variables a self-hosted deployment uses.

# 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](/integrations/setup/oauth-google) · [Microsoft Entra ID](/integrations/setup/oauth-microsoft) · [GitHub](/integrations/setup/oauth-github)

<Note>
  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)](/sso/overview).
</Note>

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

| Deployment                      | Save under                             | Why                                                                                                                                                                                                                                                             |
| ------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Self-hosted, one workspace      | **This tenant** or **Global defaults** | With exactly one workspace holding a provider's app, KnoxCall uses it for every sign-in on that provider regardless of host. Global defaults works too and is the clearer choice when the operator is the admin.                                                |
| Self-hosted, several workspaces | **Global defaults**                    | One platform-wide app per provider.                                                                                                                                                                                                                             |
| KnoxCall Cloud                  | —                                      | Sign-in already works with KnoxCall's apps. A workspace-scoped app is not supported at sign-in on the hosted service today: the provider redirects to the shared callback host, which is not a workspace host, so a per-workspace app cannot be selected there. |

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

| Deployment     | Redirect URI                                                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KnoxCall Cloud | `https://auth.knoxcall.com/callback` — one URI shared by all three providers; KnoxCall tells them apart from the sign-in state.                          |
| Self-hosted    | Whatever you set in the server environment, per provider (below). Until you set it, the card shows the Cloud value, which will not work for your domain. |

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

```bash theme={"dark"}
GOOGLE_OAUTH_REDIRECT_URI=https://knox.example.com/auth/google/callback
MICROSOFT_OAUTH_REDIRECT_URI=https://knox.example.com/auth/microsoft/callback
GITHUB_OAUTH_REDIRECT_URI=https://knox.example.com/auth/github/callback
```

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:

| Provider  | Scopes                                  |
| --------- | --------------------------------------- |
| Google    | `openid`, `email`, `profile`            |
| Microsoft | Microsoft Graph `User.Read` (delegated) |
| GitHub    | `read:user`, `user:email`               |

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](/security/oauth2-flow).)

## 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](/integrations/setup/oauth-microsoft#restrict-sign-in-to-your-directory) 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.

| Provider  | Client ID                   | Client secret                   | Redirect URI                   |
| --------- | --------------------------- | ------------------------------- | ------------------------------ |
| Google    | `GOOGLE_OAUTH_CLIENT_ID`    | `GOOGLE_OAUTH_CLIENT_SECRET`    | `GOOGLE_OAUTH_REDIRECT_URI`    |
| Microsoft | `MICROSOFT_OAUTH_CLIENT_ID` | `MICROSOFT_OAUTH_CLIENT_SECRET` | `MICROSOFT_OAUTH_REDIRECT_URI` |
| GitHub    | `GITHUB_OAUTH_CLIENT_ID`    | `GITHUB_OAUTH_CLIENT_SECRET`    | `GITHUB_OAUTH_REDIRECT_URI`    |

`MICROSOFT_OAUTH_ALLOWED_TENANT_IDS` is the environment form of Microsoft's allowed-directory list.

## Troubleshooting

| What you see                                                                                          | What it means                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The login page has no button for the provider                                                         | No configured, enabled app was found for it. Check the scope you saved under, and that the row is enabled.                                                      |
| `/login?error=oauth_not_configured&provider=…`                                                        | Same as above, reached by URL.                                                                                                                                  |
| `redirect_uri_mismatch` (Google), `AADSTS50011` (Microsoft), "The redirect\_uri MUST match…" (GitHub) | The URI registered on the provider differs from the one in the card. Compare them byte for byte.                                                                |
| `/login?error=unverified_email`                                                                       | The provider reported an unverified address. Verify it at the provider and try again.                                                                           |
| `/login?error=oauth_failed`                                                                           | The code-for-token exchange failed — usually a wrong client secret (Microsoft: the *Secret ID* was pasted instead of the *Value*) or a secret that has expired. |

## Related

* [Single Sign-On (SAML)](/sso/overview) — enterprise federation with domain verification
* [Team collaboration](/account/team-collaboration) — inviting people and roles