Platform
Social and OIDC sign-in
Tested with:supabase-js 2 · @supabase/auth-js 2.117
Your users can sign in with an account they already have. The routes are Supabase Auth’s, so
supabase.auth.signInWithOAuth, signInWithIdToken, linkIdentity and unlinkIdentity use your project endpoint.
Manual browser linking requires the PKCE configuration below.
Providers
Section titled “Providers”Apple, Microsoft (Azure, with a tenant URL), Bitbucket, Discord, Facebook, Figma, Fly.io, GitHub (and GitHub Enterprise),
GitLab (and self-managed GitLab), Google, Kakao, Keycloak, LinkedIn (OIDC), Notion, Slack (OIDC), Spotify, Twitch,
Twitter (OAuth 2.0), X, WorkOS, Zoom, a generic OpenID Connect provider (oidc) and up to ten more OIDC providers of your
own (custom:<slug>, for example custom:okta).
Turn a provider on
Section titled “Turn a provider on”-
Create an OAuth app at the provider and register your project’s callback URL:
callback URL https://<ref>.us-east.databasezy.com:8443/auth/v1/callbackPlatform services → Auth → Providers shows it, and so does
GET /v1/orgs/{org}/projects/{project}/auth/providers(callback_url). -
Paste the client ID and secret into the provider’s settings, or use the API:
shell zb api PUT /v1/orgs/{org}/projects/<project-id>/auth/providers/github -d '{"enabled": true,"client_id": "Iv1.0123456789abcdef","secret": "<client secret>","scopes": ["read:org"]}'The secret is write-only: it is sealed and stored in your project’s region, and the API only shows a fingerprint. Self-hosted providers (GitHub Enterprise, GitLab, Keycloak, a tenant-specific Microsoft directory,
oidcandcustom:<slug>) also takeurl, the issuer or base URL; OIDC providers read their keys from its discovery document. -
Add your app’s callback routes to the redirect URLs (Platform services → Auth → URL configuration), for example
https://app.example.com/**. AredirectTothat is not on the list is replaced by the site URL. -
Sign in from your app:
app/login.ts await supabase.auth.signInWithOAuth({provider: "github",options: { redirectTo: "https://app.example.com/auth/callback" },});
With flowType: "pkce" (the @supabase/ssr default) your callback route receives ?code=... and exchanges it with
exchangeCodeForSession(code); see server-side auth. Native apps that already hold a
Google or Apple ID token call signInWithIdToken instead.
Linking identities
Section titled “Linking identities”- Automatic: a sign-in whose provider vouches for the email (a verified email) joins the existing user with that email. An account that was never confirmed loses its password and other identities first, so nobody can pre-register someone else’s address and wait for them.
- Manual: with
manual_linkingon, a signed-in user adds a provider withlinkIdentity({ provider })using S256 PKCE and removes one withunlinkIdentity(identity); the last identity cannot be removed. The original local session must still be active when linking completes. SAML users and delegated OAuth-client sessions cannot manually link. - An authenticated anonymous user keeps their id and can stop being anonymous when the linked provider supplies a verified email. An anonymous project key by itself cannot link an identity.
Configure PKCE before starting a browser link. @supabase/ssr already uses it by default; a browser client created
directly with supabase-js needs flowType: "pkce":
import { createClient } from "@supabase/supabase-js";
const supabase = createClient(projectUrl, publishableKey, { auth: { flowType: "pkce" },});
// Use the client that holds the user's current signed-in session.const { error } = await supabase.auth.linkIdentity({ provider: "github", options: { redirectTo: "https://app.example.com/auth/callback" },});The callback exchanges its code with exchangeCodeForSession(code) using the verifier retained by the initiating
client; see server-side auth. The identity is attached only after that exchange succeeds.
Implicit and plain-PKCE manual links are refused. Ordinary provider sign-in keeps its existing flow options.
Native Google or Apple clients that already hold a verified provider ID token can link it directly with the signed-in client instead of opening a browser:
const { data, error } = await supabase.auth.linkIdentity({ provider: "google", token: providerIdToken, nonce: originalNonce,});This returns a fresh session for the same local user and does not carry over a previous MFA assurance level. Native ID-token sign-in and linking do not require a browser cookie.
Browser redirects
Section titled “Browser redirects”Start and finish the provider flow in the same browser context. The project auth endpoint establishes a short-lived browser cookie before redirecting to the provider, and requires it on the callback, including Apple’s form POST. Use the exact project callback URL shown in the provider settings, including its hostname and port. An app callback or native deep link is the final destination; it does not replace the provider’s registered project callback.
If a JSON authorization response or skipBrowserRedirect returns a url, navigate to that URL as returned. It can
point to a one-use project browser-start route before reaching the provider. Do not extract an upstream URL, open
the callback in a different browser or copy the flow between devices. A missing cookie, expired flow or too many
pending browser flows requires restarting sign-in; blocking the cookie does not enable a cookie-free fallback.
The project auth cookie is separate from the app’s session and PKCE cookies used by @supabase/ssr. A native app can
use an external browser for the whole provider flow without sharing that browser’s cookie jar with its HTTP client.
What is checked
Section titled “What is checked”| Check | Behaviour |
|---|---|
state | Random, stored server-side as a SHA-256 digest, single use, 10 minutes, and bound to the initiating project/browser. A mismatching browser cannot consume the legitimate flow. |
| PKCE | The app’s code_challenge binds the code exchange (at most 5 minutes, single use, also bounded by the original flow expiry). Manual linking requires S256 and commits the identity only at successful redemption. Providers that accept PKCE also get one from us. |
| ID tokens | Verified against the provider’s JWKS (cached) with issuer, audience and the configured nonce checks for this sign-in. |
| Redirects | Only the site URL and the allow-listed redirect URLs (Supabase’s glob rules); errors go back there as OAuth error fields with a sanitized description. |
| Rate limits | The sign-in limit per client IP covers /authorize and /callback. |