supabase/apps/docs/pages/guides/auth.mdx

import Layout from '~/layouts/DefaultGuideLayout'
import NewContent from '~/pages/new/auth.mdx'
import { useRouter } from 'next/router'

export const meta = {
  id: 'auth',
  title: 'Auth',
  description: 'Use Supabase to Authenticate and Authorize your users.',
  sidebar_label: 'Overview',
}

## Overview

There are two parts to every Auth system:

- **Authentication:** should this person be allowed in? If yes, who are they?
- **Authorization:** once they are in, what are they allowed to do?

Supabase Auth is designed to work either as a standalone product, or deeply integrated with the other Supabase products.
Postgres is at the heart of everything we do, and the Auth system follows this principle. We leverage Postgres' built-in Auth functionality wherever possible.

Here's a quick, 2 minute tour of the Auth features built-in to Supabase:

<div className="video-container">
  <iframe
    src="https://www.youtube-nocookie.com/embed/6ow_jW4epf8"
    frameBorder="1"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
    allowFullScreen
  ></iframe>
</div>

## Authentication

You can authenticate your users in several ways:

- Email & password.
- Magic links (one-click logins).
- Social providers.
- Phone logins.

### Providers

We provide a suite of Providers and login methods, as well as [Auth helpers](/docs/guides/auth/auth-helpers/).

<div className="container" style={{ padding: 0 }}>
  <AuthProviders />
</div>

### Configure third-party providers

You can enable third-party providers with the click of a button by navigating to Authentication > Settings > Auth Providers and inputting your `Client ID` and `Secret` for each.

![OAuth Logins.](/docs/img/supabase-oauth-logins.png)

### Redirect URLs and wildcards

When using third-party providers, the [Supabase client library](/docs/reference/javascript/auth-signinwithoauth#sign-in-using-a-third-party-provider-with-redirect) redirects the user to the provider. When the third-party provider successfully authenticates the user, the provider redirects the user to the Supabase Auth callback URL where they are further redirected to the URL specified in the `redirectTo` parameter. This parameter defaults to the [`SITE_URL`](/docs/reference/auth/config#site_url). You can modify the `SITE_URL` or [add additional redirect URLs](https://app.supabase.com/project/_/auth/settings).

You can use wildcard match patterns to support preview URLs from providers like Netlify and Vercel. See the [full list of supported patterns](https://pkg.go.dev/github.com/gobwas/glob#Compile). Use [this tool](https://www.digitalocean.com/community/tools/glob?comments=true&glob=http%3A%2F%2Flocalhost%3A3000%2F%2A%2A&matches=false&tests=http%3A%2F%2Flocalhost%3A3000&tests=http%3A%2F%2Flocalhost%3A3000%2F&tests=http%3A%2F%2Flocalhost%3A3000%2F%3Ftest%3Dtest&tests=http%3A%2F%2Flocalhost%3A3000%2Ftest-test%3Ftest%3Dtest&tests=http%3A%2F%2Flocalhost%3A3000%2Ftest%2Ftest%3Ftest%3Dtest) to test your patterns.

> ⚠️ WARNING: While the "globstar" (`**`) is useful for local development and preview URLs, we recommend setting the exact redirect URL path for your site URL in production.

#### Netlify preview URLs

For deployments with Netlify, set the `SITE_URL` to your official site URL. Add the following additional redirect URLs for local development and deployment previews:

- `http://localhost:3000/**`
- `https://**--my_org.netlify.app/**`

#### Vercel preview URLs

For deployments with Vercel, set the `SITE_URL` to your official site URL. Add the following additional redirect URLs for local development and deployment previews:

- `http://localhost:3000/**`
- `https://*-username.vercel.app/**`

Vercel provides an environment variable for the URL of the deployment called `NEXT_PUBLIC_VERCEL_URL`. See the [Vercel docs](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables) for more details. You can use this variable to dynamically redirect depending on the environment:

```js
const getURL = () => {
  let url =
    process?.env?.NEXT_PUBLIC_SITE_URL ?? // Set this to your site URL in production env.
    process?.env?.NEXT_PUBLIC_VERCEL_URL ?? // Automatically set by Vercel.
    'http://localhost:3000/';
  // Make sure to include `https://` when not localhost.
  url = url.includes('http') ? url : `https://${url}`;
  // Make sure to including trailing `/`.
  url = url.charAt(url.length - 1) === '/' ? url : `${url}/`;
  return url;
};

const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github'
  options: {
    redirectTo: getURL()
  }
}
```

#### Mobile deep linking URIs

For mobile applications you can use deep linking URIs. For example for your `SITE_URL` you can specify something like `com.supabase://login-callback/` and for additional redirect URLs something like `com.supabase.staging://login-callback/` if needed.

## Authorization

When you need granular authorization rules, nothing beats PostgreSQL's Row Level Security (RLS).

Policies are PostgreSQL's rule engine. They are incredibly powerful and flexible, allowing you to write complex SQL rules which fit your unique business needs.

Get started with our [Row Level Security Guides](/docs/guides/auth/row-level-security).

### Row Level Security

Authentication only gets you so far. When you need granular authorization rules, nothing beats PostgreSQL's [Row Level Security (RLS)](https://www.postgresql.org/docs/current/ddl-rowsecurity.html). Supabase makes it simple to turn RLS on and off.

<video width="99%" muted playsInline controls="true">
  <source src="/docs/videos/rls-zoom2.mp4" type="video/mp4" muted playsInline />
</video>

### Policies

[Policies](https://www.postgresql.org/docs/current/sql-createpolicy.html) are PostgreSQL's rule engine. They are incredibly powerful and flexible, allowing you to write complex SQL rules which fit your unique business needs.

<video width="99%" muted playsInline controls="true">
  <source src="/docs/videos/policies-zoom2.mp4" type="video/mp4" muted playsInline />
</video>

With policies, your database becomes the rules engine. Instead of repetitively filtering your queries, like this ...

```js
const loggedInUserId = 'd0714948'
let { data, error } = await supabase
  .from('users')
  .select('user_id, name')
  .eq('user_id', loggedInUserId)

// console.log(data)
// => { id: 'd0714948', name: 'Jane' }
```

... you can simply define a rule on your database table, `auth.uid() = user_id`, and your request will return the rows which pass the rule, even when you remove the filter from your middleware:

```js
let { data, error } = await supabase.from('users').select('user_id, name')

// console.log(data)
// Still => { id: 'd0714948', name: 'Jane' }
```

### How It Works

1. A user signs up. Supabase creates a new user in the `auth.users` table.
2. Supabase returns a new JWT, which contains the user's `UUID`.
3. Every request to your database also sends the JWT.
4. Postgres inspects the JWT to determine the user making the request.
5. The user's UID can be used in policies to restrict access to rows.

Supabase provides a special function in Postgres, `auth.uid()`, which extracts the user's UID from the JWT. This is especially useful when creating policies.

## User Management

Supabase provides multiple endpoints to authenticate and manage your users:

- [Sign up](/docs/reference/javascript/auth-signup)
- [Sign in with password](/docs/reference/javascript/auth-signinwithpassword)
- [Sign in with passwordless / one-time password (OTP)](/docs/reference/javascript/auth-signinwithotp)
- [Sign in with OAuth](/docs/reference/javascript/auth-signinwithoauth)
- [Sign out](/docs/reference/javascript/auth-signout)

When users sign up, Supabase assigns them a unique ID. You can reference this ID anywhere in your database. For example, you might create a `profiles` table referencing `id` in the `auth.users` table using a `user_id` field.

<video width="99%" muted playsInline controls="true">
  <source src="/docs/videos/auth-zoom2.mp4" type="video/mp4" muted playsInline />
</video>

export const Page = ({ children }) => {
  const router = useRouter()
  if (process.env.NEXT_PUBLIC_NEW_DOCS === 'true' && !router.asPath.includes('overview')) {
    return NewContent()
  }
  return <Layout meta={meta} children={children} />
}

export default Page