Configure Custom OAuth/OIDC Providers

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.

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 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 and Update Your Self-Hosted Deployment.
• 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.

When registering your application with an external identity provider, add the following URL as the redirect URI in the provider's settings:

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

To change any of these, add the variable to the auth service in your docker-compose.yml:

1
auth:
2
  environment:
3
    # ... existing variables ...
4
    GOTRUE_CUSTOM_OAUTH_MAX_PROVIDERS: 5

Then recreate the Auth service for the change to take effect:

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

1
import { createClient } from '@supabase/supabase-js'
2
3
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.

1
const { data, error } = await supabase.auth.admin.customProviders.createProvider({
2
  provider_type: 'oauth2',
3
  identifier: 'custom:my-oauth-provider',
4
  name: 'My OAuth Provider',
5
  client_id: 'your-client-id',
6
  client_secret: 'your-client-secret',
7
  authorization_url: 'https://provider.example.com/oauth/authorize',
8
  token_url: 'https://provider.example.com/oauth/token',
9
  userinfo_url: 'https://provider.example.com/oauth/userinfo',
10
  scopes: ['profile', 'email'],
11
})

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.

1
const { data, error } = await supabase.auth.admin.customProviders.createProvider({
2
  provider_type: 'oidc',
3
  identifier: 'custom:my-oidc-provider',
4
  name: 'My OIDC Provider',
5
  client_id: 'your-client-id',
6
  client_secret: 'your-client-secret',
7
  issuer: 'https://auth.example.com',
8
  scopes: ['openid', 'profile', 'email'],
9
})

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:

1
curl "http://<your-domain>/auth/v1/admin/custom-providers" \
2
  -H "apikey: your-supabase-secret-key"

The response includes the provider you created. Users can now sign in with it from your app:

1
const { data, error } = await supabase.auth.signInWithOAuth({
2
  provider: 'custom:my-oidc-provider',
3
})

Example: Telegram#

The following steps walk through setting up Telegram sign-in with Supabase Auth.

Step 1: Create a Telegram bot#

1. Open @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 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:

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

1
const { data, error } = await supabase.auth.admin.customProviders.createProvider({
2
  provider_type: 'oidc',
3
  identifier: 'custom:telegram',
4
  name: 'Telegram',
5
  client_id: 'your-client-id',
6
  client_secret: 'your-client-secret',
7
  issuer: 'https://oauth.telegram.org',
8
  scopes: ['openid', 'profile'],
9
  email_optional: true,
10
})

A few notes on these fields:

• identifier: can be any value that starts with custom: and follows the identifier rules.
• 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.

Step 4: Sign in with Telegram#

With the provider configured, you can now sign in with Telegram from your app:

1
const { data, error } = await supabase.auth.signInWithOAuth({
2
  provider: 'custom:telegram',
3
})

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.

1
<!doctype html>
2
<html>
3
  <body>
4
    <h1>Supabase custom provider test</h1>
5
    <button id="loginBtn">Sign in with Telegram</button>
6
    <pre id="result"></pre>
7
8
    <script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
9
    <script>
10
      document.addEventListener('DOMContentLoaded', function () {
11
        const SUPABASE_URL = 'https://<your-domain>'
12
        const SUPABASE_PUBLISHABLE_KEY = 'your-supabase-publishable-key'
13
14
        const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY)
15
16
        document.getElementById('loginBtn').addEventListener('click', async () => {
17
          const { error } = await supabase.auth.signInWithOAuth({
18
            provider: 'custom:telegram',
19
          })
20
21
          if (error) {
22
            document.getElementById('result').textContent = JSON.stringify(error, null, 2)
23
          }
24
        })
25
26
        supabase.auth.onAuthStateChange((_event, session) => {
27
          if (session) {
28
            document.getElementById('result').textContent = JSON.stringify(session.user, null, 2)
29
          }
30
        })
31
      })
32
    </script>
33
  </body>
34
</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#

1
// List all custom providers
2
const { data, error } = await supabase.auth.admin.customProviders.listProviders()
3
4
// Filter by provider type
5
const { data, error } = await supabase.auth.admin.customProviders.listProviders({
6
  type: 'oidc',
7
})

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.

1
const { data, error } = await supabase.auth.admin.customProviders.updateProvider(
2
  'custom:my-provider',
3
  {
4
    name: 'Updated Provider Name',
5
    scopes: ['openid', 'profile', 'email'],
6
  }
7
)

Delete a provider#

1
const { data, error } =
2
  await supabase.auth.admin.customProviders.deleteProvider('custom:my-provider')

For PKCE, authorization parameters, and OIDC-specific options, see Advanced configuration.

Additional resources#

• Custom OAuth/OIDC Providers
• Configure Social Login (OAuth) Providers