Configure Social Login (OAuth) Providers

This guide covers the server-side configuration required to enable social login providers on a self-hosted Zuvo instance running with Docker Compose. This applies to all OAuth and OIDC-based providers, including third-party identity providers like Keycloak.

Before you begin

You need:

• A working self-hosted Zuvo installation. See Self-Hosting with Docker.
• API_EXTERNAL_URL set to the publicly reachable URL of your Zuvo instance (e.g., https://<your-domain>/auth/v1).

Your OAuth callback URL should look like the following:

https://<your-domain>/auth/v1/callback

You will have to register this URL with each OAuth provider.

OAuth request flow

When a user signs in with an OAuth provider, the following flow occurs:

1. Your app calls supabase.auth.signInWithOAuth() and the browser redirects to the Auth service
2. The API gateway routes the request to the Auth container (/auth/v1/authorize)
3. Auth redirects the user to the OAuth provider (e.g., Google) for consent
4. The provider redirects back to https://<your-domain>/auth/v1/callback
5. Auth exchanges the authorization code for tokens and redirects the user to your SITE_URL or an allowed redirect URL

Auth environment variables

The Auth service (GoTrue) uses the prefix GOTRUE_EXTERNAL_ followed by a provider name for all OAuth configuration. For example, when using Google:

• GOTRUE_EXTERNAL_GOOGLE_ENABLED
• GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID
• GOTRUE_EXTERNAL_GOOGLE_SECRET
• GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI

Step-by-step configuration

The default .env.example and docker-compose.yml include commented-out placeholders for Google, GitHub, and Azure.

Step 1: Register your app with the provider

1. Go to the OAuth provider's developer console and create an application.
2. Set the authorized redirect URL, e.g., https://<your-domain>/auth/v1/callback
3. Copy the client ID and client secret into your .env file.

Step 2: Configure environment variables

Uncomment the lines for your provider in .env and add your client ID and secret, e.g., for Google:

GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_SECRET=your-client-secret

Step 3: Enable the matching lines in Docker Compose configuration

Uncomment the corresponding GOTRUE_EXTERNAL_ lines in the auth service's environment:

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}
    GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
    GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}
    GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/callback

Step 4: Restart the auth service

sh run.sh recreate auth

Step 5: Verify the configuration

Check that the provider is enabled:

curl -H 'apikey: your-anon-key' https://<your-domain>/auth/v1/settings

The response should include your provider under external:

{
  "external": {
    "google": true
  }
}

Provider-specific setup

GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_SECRET=your-google-client-secret

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}
    GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
    GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}
    GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/callback

GITHUB_ENABLED=true
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_GITHUB_ENABLED: ${GITHUB_ENABLED}
    GOTRUE_EXTERNAL_GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID}
    GOTRUE_EXTERNAL_GITHUB_SECRET: ${GITHUB_SECRET}
    GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI: ${API_EXTERNAL_URL}/callback

AZURE_ENABLED=true
AZURE_CLIENT_ID=your-azure-application-client-id
AZURE_SECRET=your-azure-client-secret
## Optional: restrict to a specific tenant (defaults to 'common')
# AZURE_URL=https://login.microsoftonline.com/your-tenant-id

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_AZURE_ENABLED: ${AZURE_ENABLED}
    GOTRUE_EXTERNAL_AZURE_CLIENT_ID: ${AZURE_CLIENT_ID}
    GOTRUE_EXTERNAL_AZURE_SECRET: ${AZURE_SECRET}
    GOTRUE_EXTERNAL_AZURE_REDIRECT_URI: ${API_EXTERNAL_URL}/callback
    ## Optional: uncomment for tenant-specific Azure login
    # GOTRUE_EXTERNAL_AZURE_URL: ${AZURE_URL}

APPLE_ENABLED=true
APPLE_CLIENT_ID=com.example.your-services-id
APPLE_SECRET=your-generated-jwt-client-secret

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_APPLE_ENABLED: ${APPLE_ENABLED}
    GOTRUE_EXTERNAL_APPLE_CLIENT_ID: ${APPLE_CLIENT_ID}
    GOTRUE_EXTERNAL_APPLE_SECRET: ${APPLE_SECRET}
    GOTRUE_EXTERNAL_APPLE_REDIRECT_URI: ${API_EXTERNAL_URL}/callback

KEYCLOAK_ENABLED=true
KEYCLOAK_CLIENT_ID=supabase
KEYCLOAK_SECRET=your-keycloak-client-secret
## Required: your Keycloak realm URL
KEYCLOAK_URL=https://keycloak.example.com/realms/myrealm

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_KEYCLOAK_ENABLED: ${KEYCLOAK_ENABLED}
    GOTRUE_EXTERNAL_KEYCLOAK_CLIENT_ID: ${KEYCLOAK_CLIENT_ID}
    GOTRUE_EXTERNAL_KEYCLOAK_SECRET: ${KEYCLOAK_SECRET}
    GOTRUE_EXTERNAL_KEYCLOAK_REDIRECT_URI: ${API_EXTERNAL_URL}/callback
    GOTRUE_EXTERNAL_KEYCLOAK_URL: ${KEYCLOAK_URL}

Other supported providers

Zuvo Auth supports the following OAuth providers:

For each provider, you need at minimum ENABLED, CLIENT_ID, SECRET, and REDIRECT_URI in .env and docker-compose.yml.

Test the login flow

You can test OAuth with the following minimal HTML page:

• Save the code below to index.html
• Start python -m http.server 3000 in the same directory
• Make sure SITE_URL is set to http://localhost:3000 in your self-hosted Zuvo .env configuration
• Open your browser and go to http://localhost:3000

<!doctype html>
<html>
  <body>
    <h1>Zuvo OAuth Test</h1>
    <button id="loginBtn">Sign in with Google</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_ANON_KEY = 'your-anon-key'

        const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

        const button = document.getElementById('loginBtn')

        button.addEventListener('click', async () => {
          const { error } = await supabase.auth.signInWithOAuth({
            provider: 'google',
          })

          if (error) {
            document.getElementById('result').textContent = JSON.stringify(error, null, 2)
          }
        })

        supabase.auth.getSession().then(({ data }) => {
          if (data.session) {
            document.getElementById('result').textContent =
              'Logged in as: ' + data.session.user.email
          }
        })
      })
    </script>
  </body>
</html>

For detailed client-side integration, see Social Login.

Troubleshooting

"Provider not enabled" or provider seen as false in settings

• Check that GOTRUE_EXTERNAL_*_ENABLED is set to true in docker-compose.yml
• Verify the .env variable is not empty, e.g., check with sh run.sh printenv auth | grep GOOGLE

Variables added to the environment but provider still not working

Configuration variables from .env are not automatically available inside the container unless there's a matching passthrough definition in docker-compose.yml. Check, e.g., for:

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}

Run sh run.sh printenv auth | grep GOTRUE_EXTERNAL to verify the variables are reaching the container.

Site URL or redirect URL errors after login

After a successful OAuth login, the Auth service redirects to SITE_URL or a URL from ADDITIONAL_REDIRECT_URLS. Ensure:

• SITE_URL in .env is set to your application's URL
• If your app uses a different redirect URL, add it to ADDITIONAL_REDIRECT_URLS (comma-separated)

Nonce check failure on mobile (Google Sign In)

When using Google Sign In on mobile with ID tokens, nonce verification may fail because mobile SDKs don't always support the nonce flow that the Auth service expects.

To enable it, uncomment the following line in docker-compose.yml:

auth:
  environment:
    # ... existing variables ...
    GOTRUE_EXTERNAL_SKIP_NONCE_CHECK: 'true'

Auth service fails to start

Check the auth container logs:

docker compose logs auth

Common causes:

• Missing required environment variable (e.g., CLIENT_ID or SECRET is empty)
• Invalid API_EXTERNAL_URL (must be a valid URL - including protocol and ending with /auth/v1)

Environment variable reference

All OAuth-related environment variables for the auth service in docker-compose.yml:

Additional resources

• Redirect URLs
• Auth server on GitHub (check README and example.env)