The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs(self-hosted): add custom oauth providers guide (#49971)
Inder Singh8dc9206f569e
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex a578dd53fa5..c0791140edc 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -3159,6 +3159,10 @@ export const self_hosting: NavMenuConstant = {{ name: 'Configure S3 Storage', url: '/guides/self-hosting/self-hosted-s3' },{ name: 'Enable MCP server', url: '/guides/self-hosting/enable-mcp' },{ name: 'Configure Social Login (OAuth)', url: '/guides/self-hosting/self-hosted-oauth' },+ {+ name: 'Configure Custom OAuth/OIDC',+ url: '/guides/self-hosting/self-hosted-custom-oauth-providers',+ },{ name: 'Configure Phone Login & MFA', url: '/guides/self-hosting/self-hosted-phone-mfa' },{ name: 'Add Custom Email Templates', url: '/guides/self-hosting/custom-email-templates' },{ name: 'Configure Auth Hooks', url: '/guides/self-hosting/self-hosted-auth-hooks' },diff --git a/apps/docs/content/guides/self-hosting/self-hosted-custom-oauth-providers.mdx b/apps/docs/content/guides/self-hosting/self-hosted-custom-oauth-providers.mdxnew file mode 100644index 00000000000..2fe23d6be8e--- /dev/null+++ b/apps/docs/content/guides/self-hosting/self-hosted-custom-oauth-providers.mdx@@ -0,0 +1,473 @@+---+title: 'Configure Custom OAuth/OIDC Providers'+description: 'Set up any OAuth 2.0 or OIDC-compatible identity provider for self-hosted Supabase.'+subtitle: 'Set up any OAuth 2.0 or OIDC-compatible identity provider for self-hosted Supabase.'+---++This guide explains how to add a custom OAuth 2.0 or OpenID Connect (OIDC) identity provider to a self-hosted Supabase instance and how to manage it through the Auth admin API. To learn how custom providers work and which advanced options they support, see [Custom OAuth/OIDC Providers](/docs/guides/auth/custom-oauth-providers).++There are two provider types:++- **OAuth 2.0**: for generic OAuth 2.0 providers where you supply the authorization, token, and userinfo endpoints manually.+- **OIDC**: for providers that support [OpenID Connect](https://openid.net/connect/) discovery. You supply only the issuer URL and endpoints are resolved automatically.++## Provider identifiers++Every custom provider identifier must start with the `custom:` prefix. Identifiers are 2-50 characters, lowercase alphanumeric with hyphens and colons allowed. Examples:++- `custom:my-provider`+- `custom:github-enterprise`++## Before you begin++You need:++- A working self-hosted Supabase instance on release `0.8.1` or later, which ships Supabase Auth `v2.196.0`. See [Self-Hosting with Docker](/docs/guides/self-hosting/docker) and [Update Your Self-Hosted Deployment](/docs/guides/self-hosting/updating).+- Your project's secret key, `SUPABASE_SECRET_KEY`, from your `.env` file.+- `API_EXTERNAL_URL` set to the publicly reachable URL of your Auth service, ending in `/auth/v1`, for example `https://<your-domain>/auth/v1`. The Auth service derives the OAuth callback URL for custom providers from this value.++<Admonition type="danger">++Most OAuth providers reject `http://` callback URLs other than `localhost`, so your instance needs HTTPS. See [Configure Reverse Proxy and HTTPS](/docs/guides/self-hosting/self-hosted-proxy-https) for setup instructions.++</Admonition>++When registering your application with an external identity provider, add the following URL as the redirect URI in the provider's settings:++```+https://<your-domain>/auth/v1/callback+```++## Optional Auth configuration++Custom providers are enabled by default in the Auth service, so no changes to `docker-compose.yml` are required. The following environment variables adjust the defaults:++| Variable | Description |+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |+| `GOTRUE_CUSTOM_OAUTH_ENABLED` | Set to `"false"` to disable custom OAuth/OIDC providers. Defaults to `true`. |+| `GOTRUE_CUSTOM_OAUTH_MAX_PROVIDERS` | Maximum number of custom OAuth/OIDC providers allowed. Defaults to `0`, which means unlimited. |+| `GOTRUE_CUSTOM_OAUTH_EXTERNAL_URL` | Base URL used to build the callback URL for custom providers. Defaults to the value of `API_EXTERNAL_URL`. |++To change any of these, add the variable to the `auth` service in your `docker-compose.yml`:++```yaml name=docker-compose.yml+auth:+ environment:+ # ... existing variables ...+ GOTRUE_CUSTOM_OAUTH_MAX_PROVIDERS: 5+```++Then recreate the Auth service for the change to take effect:++```sh+sh run.sh recreate auth+```++## Create a provider++Use the Auth admin API to create providers. You need your project's secret key for authentication.++<Admonition type="danger">++The JavaScript examples use a [supabase-js](/docs/reference/javascript/start) client created with the secret key (`SUPABASE_SECRET_KEY`), which must only run in trusted server-side environments.++</Admonition>++```js+import { createClient } from '@supabase/supabase-js'++const supabase = createClient('http://<your-domain>', 'your-supabase-secret-key')+```++The Auth service fetches and validates the provider's endpoints when you create the provider, so the request fails if the issuer or endpoint URLs can't be reached.++### OAuth 2.0 provider++Use an OAuth 2.0 provider when your identity provider does not support OpenID Connect discovery. You must supply the authorization, token, and userinfo endpoint URLs explicitly.++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="create-provider"+>+<TabPanel id="js" label="JavaScript">++```js+const { data, error } = await supabase.auth.admin.customProviders.createProvider({+ provider_type: 'oauth2',+ identifier: 'custom:my-oauth-provider',+ name: 'My OAuth Provider',+ client_id: 'your-client-id',+ client_secret: 'your-client-secret',+ authorization_url: 'https://provider.example.com/oauth/authorize',+ token_url: 'https://provider.example.com/oauth/token',+ userinfo_url: 'https://provider.example.com/oauth/userinfo',+ scopes: ['profile', 'email'],+})+```++</TabPanel>++<TabPanel id="curl" label="cURL">++```sh+curl -X POST "http://<your-domain>/auth/v1/admin/custom-providers" \+ -H "apikey: your-supabase-secret-key" \+ -H "Content-Type: application/json" \+ -d '{+ "provider_type": "oauth2",+ "identifier": "custom:my-oauth-provider",+ "name": "My OAuth Provider",+ "client_id": "your-client-id",+ "client_secret": "your-client-secret",+ "authorization_url": "https://provider.example.com/oauth/authorize",+ "token_url": "https://provider.example.com/oauth/token",+ "userinfo_url": "https://provider.example.com/oauth/userinfo",+ "scopes": ["profile", "email"]+ }'+```++</TabPanel>++</Tabs>++### OIDC provider++Use an OIDC provider when your identity provider supports OpenID Connect. Supply the `issuer` URL and the discovery document, JWKS, and endpoints are resolved automatically.++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="create-provider"+>+<TabPanel id="js" label="JavaScript">++```js+const { data, error } = await supabase.auth.admin.customProviders.createProvider({+ provider_type: 'oidc',+ identifier: 'custom:my-oidc-provider',+ name: 'My OIDC Provider',+ client_id: 'your-client-id',+ client_secret: 'your-client-secret',+ issuer: 'https://auth.example.com',+ scopes: ['openid', 'profile', 'email'],+})+```++</TabPanel>++<TabPanel id="curl" label="cURL">++```sh+curl -X POST "http://<your-domain>/auth/v1/admin/custom-providers" \+ -H "apikey: your-supabase-secret-key" \+ -H "Content-Type: application/json" \+ -d '{+ "provider_type": "oidc",+ "identifier": "custom:my-oidc-provider",+ "name": "My OIDC Provider",+ "client_id": "your-client-id",+ "client_secret": "your-client-secret",+ "issuer": "https://auth.example.com",+ "scopes": ["openid", "profile", "email"]+ }'+```++</TabPanel>++</Tabs>++OIDC providers have the following automatic behavior:++- The discovery document is fetched from `{issuer}/.well-known/openid-configuration`, or from `discovery_url` when it is set.+- The `openid` scope is always included. It is automatically added if missing from the `scopes` array.+- ID tokens are verified against the provider's JWKS, which is fetched from the discovery document's `jwks_uri`.++### Verify the provider++List the configured providers to confirm the new provider was saved:++```sh+curl "http://<your-domain>/auth/v1/admin/custom-providers" \+ -H "apikey: your-supabase-secret-key"+```++The response includes the provider you created. Users can now sign in with it from your app:++```js+const { data, error } = await supabase.auth.signInWithOAuth({+ provider: 'custom:my-oidc-provider',+})+```++## Example: Telegram++The following steps walk through setting up Telegram sign-in with Supabase Auth.++<Admonition type="note">++Telegram sign-in fails on Supabase Auth versions before `v2.196.0` because of an [unsupported signing algorithm issue](https://github.com/supabase/auth/issues/2534).++</Admonition>++### Step 1: Create a Telegram bot++1. Open [@BotFather](https://t.me/BotFather) on Telegram and send the command `/newbot`.+2. Follow the prompts to choose a name and username for your bot.++### Step 2: Register the redirect URL++1. Open the [@BotFather mini app](https://t.me/botfather?startapp) on Telegram and select the bot you created in the previous step.+2. Select **Login Widget** to open the page where you configure redirect URIs.+3. If you don't see OIDC settings, click on "Switch to OpenID Connect Login."+4. Click **Add a Redirect URI** and enter your self-hosted Supabase callback URL:++ ```+ https://<your-domain>/auth/v1/callback+ ```++This screen also shows your Client ID and Client Secret. You use them to create the provider in the next step.++### Step 3: Create the Telegram provider++Copy the Client ID and Client Secret from the **Login Widget** screen, then use them to create a custom Telegram OAuth provider:++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="create-provider"+>+<TabPanel id="js" label="JavaScript">++```js+const { data, error } = await supabase.auth.admin.customProviders.createProvider({+ provider_type: 'oidc',+ identifier: 'custom:telegram',+ name: 'Telegram',+ client_id: 'your-client-id',+ client_secret: 'your-client-secret',+ issuer: 'https://oauth.telegram.org',+ scopes: ['openid', 'profile'],+ email_optional: true,+})+```++</TabPanel>++<TabPanel id="curl" label="cURL">++```sh+curl -X POST "http://<your-domain>/auth/v1/admin/custom-providers" \+ -H "apikey: your-supabase-secret-key" \+ -H "Content-Type: application/json" \+ -d '{+ "provider_type": "oidc",+ "identifier": "custom:telegram",+ "name": "Telegram",+ "client_id": "your-client-id",+ "client_secret": "your-client-secret",+ "issuer": "https://oauth.telegram.org",+ "scopes": ["openid", "profile"],+ "email_optional": true+ }'+```++</TabPanel>++</Tabs>++A few notes on these fields:++- `identifier`: can be any value that starts with `custom:` and follows the [identifier rules](#provider-identifiers).+- `name`: can be any value you want.+- `email_optional`: must be `true` because Telegram doesn't return an email address.++The `profile` scope returns the user's name and picture. To also receive the phone number, add the `phone` scope. For the full list of available scopes, see the [Telegram Login docs](https://core.telegram.org/bots/telegram-login#available-scopes).++### Step 4: Sign in with Telegram++With the provider configured, you can now sign in with Telegram from your app:++```js+const { data, error } = await supabase.auth.signInWithOAuth({+ provider: 'custom:telegram',+})+```++### Step 5: Test the sign-in flow++Only the Supabase callback URL needs to be public and served over HTTPS, because that is where the identity provider redirects. The test page itself is a static HTML file that can run anywhere your browser can reach, including your local machine.++1. Save the code below to `index.html`.+2. Set `SITE_URL` in your self-hosted Supabase `.env` file to the URL where the page runs, for example `http://localhost:3000`, and recreate the Auth service with `sh run.sh recreate auth`. To allow more than one URL, add the others to `ADDITIONAL_REDIRECT_URLS`.+3. Start a simple HTTP server via `python -m http.server 3000` to serve `index.html`.+4. Open your browser and go to `http://localhost:3000`.++```html+<!doctype html>+<html>+ <body>+ <h1>Supabase custom provider test</h1>+ <button id="loginBtn">Sign in with Telegram</button>+ <pre id="result"></pre>++ <script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ const SUPABASE_URL = 'https://<your-domain>'+ const SUPABASE_PUBLISHABLE_KEY = 'your-supabase-publishable-key'++ const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY)++ document.getElementById('loginBtn').addEventListener('click', async () => {+ const { error } = await supabase.auth.signInWithOAuth({+ provider: 'custom:telegram',+ })++ if (error) {+ document.getElementById('result').textContent = JSON.stringify(error, null, 2)+ }+ })++ supabase.auth.onAuthStateChange((_event, session) => {+ if (session) {+ document.getElementById('result').textContent = JSON.stringify(session.user, null, 2)+ }+ })+ })+ </script>+ </body>+</html>+```++Clicking the button sends the browser to your Auth service, which redirects to Telegram. After you confirm the sign-in in the Telegram app, Telegram sends the browser back to `https://<your-domain>/auth/v1/callback`. The Auth service completes the exchange and redirects to `SITE_URL`, where `supabase-js` picks up the session and the page prints the signed-in user.++Telegram doesn't return an email address, so `email` is empty in the user object. The profile claims that Telegram returns, `name`, `given_name`, `family_name`, and `picture`, are in `user_metadata` together with the ID token claims, and `app_metadata.provider` is `custom:telegram`. The `sub` claim is the stable identifier that Auth uses to match the user on later sign-ins.++To test a different custom provider, change the `provider` value to its identifier.++## Manage providers++Use the admin API to list, update, and delete custom providers. Self-hosted Studio doesn't include a UI for them. The examples use `custom:my-provider` as the identifier. Replace it with the identifier of your provider.++### List providers++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="provider-management"+>+<TabPanel id="js" label="JavaScript">++```js+// List all custom providers+const { data, error } = await supabase.auth.admin.customProviders.listProviders()++// Filter by provider type+const { data, error } = await supabase.auth.admin.customProviders.listProviders({+ type: 'oidc',+})+```++</TabPanel>++<TabPanel id="curl" label="cURL">++```sh+# List all custom providers+curl "http://<your-domain>/auth/v1/admin/custom-providers" \+ -H "apikey: your-supabase-secret-key"++# Filter by provider type+curl "http://<your-domain>/auth/v1/admin/custom-providers?type=oidc" \+ -H "apikey: your-supabase-secret-key"+```++</TabPanel>++</Tabs>++### Update a provider++Send only the fields you want to change. Fields you leave out keep their current values, so you can rotate a client secret by sending `client_secret` alone. The `provider_type` and `identifier` fields are fixed when the provider is created and can't be updated.++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="provider-management"+>+<TabPanel id="js" label="JavaScript">++```js+const { data, error } = await supabase.auth.admin.customProviders.updateProvider(+ 'custom:my-provider',+ {+ name: 'Updated Provider Name',+ scopes: ['openid', 'profile', 'email'],+ }+)+```++</TabPanel>++<TabPanel id="curl" label="cURL">++```sh+curl -X PUT "http://<your-domain>/auth/v1/admin/custom-providers/custom:my-provider" \+ -H "apikey: your-supabase-secret-key" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Updated Provider Name",+ "scopes": ["openid", "profile", "email"]+ }'+```++</TabPanel>++</Tabs>++### Delete a provider++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="provider-management"+>+<TabPanel id="js" label="JavaScript">++```js+const { data, error } =+ await supabase.auth.admin.customProviders.deleteProvider('custom:my-provider')+```++</TabPanel>++<TabPanel id="curl" label="cURL">++```sh+curl -X DELETE "http://<your-domain>/auth/v1/admin/custom-providers/custom:my-provider" \+ -H "apikey: your-supabase-secret-key"+```++</TabPanel>++</Tabs>++For PKCE, authorization parameters, and OIDC-specific options, see [Advanced configuration](/docs/guides/auth/custom-oauth-providers#advanced-configuration).++## Additional resources++- [Custom OAuth/OIDC Providers](/docs/guides/auth/custom-oauth-providers)+- [Configure Social Login (OAuth) Providers](/docs/guides/self-hosting/self-hosted-oauth)diff --git a/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx b/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdxindex 210e04635cf..7a04eed2184 100644--- a/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx+++ b/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx@@ -1,5 +1,5 @@----title: 'Configure social login (OAuth) providers'+title: 'Configure Social Login (OAuth) Providers'description: 'Set up social login (OAuth/OIDC) providers for self-hosted Supabase with Docker.'subtitle: 'Set up social login (OAuth/OIDC) providers for self-hosted Supabase with Docker.'---diff --git a/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdx b/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdxindex 071b14df568..e4f6949d8f1 100644--- a/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdx+++ b/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdx@@ -1,5 +1,5 @@----title: 'Configure Phone sign-in & MFA'+title: 'Configure Phone Sign-in & MFA'description: 'Set up phone sign-in SMS providers, OTP settings, and multi-factor authentication for self-hosted Supabase with Docker.'subtitle: 'Set up phone sign-in SMS providers, OTP settings, and multi-factor authentication for self-hosted Supabase with Docker.'---