Skip to content

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.

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

  1. 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/callback

    Platform services → Auth → Providers shows it, and so does GET /v1/orgs/{org}/projects/{project}/auth/providers (callback_url).

  2. 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, oidc and custom:<slug>) also take url, the issuer or base URL; OIDC providers read their keys from its discovery document.

  3. Add your app’s callback routes to the redirect URLs (Platform services → Auth → URL configuration), for example https://app.example.com/**. A redirectTo that is not on the list is replaced by the site URL.

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

  • 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_linking on, a signed-in user adds a provider with linkIdentity({ provider }) using S256 PKCE and removes one with unlinkIdentity(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":

app/link-provider.ts
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:

native/link-provider.ts
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.

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.

CheckBehaviour
stateRandom, 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.
PKCEThe 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 tokensVerified against the provider’s JWKS (cached) with issuer, audience and the configured nonce checks for this sign-in.
RedirectsOnly 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 limitsThe sign-in limit per client IP covers /authorize and /callback.