Skip to main content

​
Overview

Third-party providers (OAuth 2.0 and OpenID Connect providers) are configured at the tenant level in SuperTokens Core. This allows for flexible multi-tenant setups where different tenants can have different social login options.

​
Supported Providers

SuperTokens supports any OAuth 2.0 or OpenID Connect compliant provider, including:
  • Google - OAuth 2.0
  • Facebook - OAuth 2.0
  • GitHub - OAuth 2.0
  • Apple - OAuth 2.0 with Sign in with Apple
  • Microsoft - OAuth 2.0 / OIDC
  • LinkedIn - OAuth 2.0
  • Twitter - OAuth 2.0
  • Custom Providers - Any OAuth 2.0 / OIDC provider

​
Configuration Structure

Providers are configured through the tenant configuration. Each provider configuration includes:

​
Provider Properties

​
thirdPartyId
string
required
Unique identifier for the provider (e.g., “google”, “facebook”, “github”)
​
clients
array
required
Array of client configurations for the provider

​
Provider Configuration via Tenant API

Providers are managed through the Multi-tenancy API. You can configure providers when creating or updating a tenant.

​
Example: Configuring Google Provider

curl -X PUT https://your-domain.com/recipe/multitenancy/tenant \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "customer1",
    "thirdPartyEnabled": true,
    "thirdPartyProviders": [
      {
        "thirdPartyId": "google",
        "clients": [
          {
            "clientId": "your-google-client-id",
            "clientSecret": "your-google-client-secret",
            "scope": ["email", "profile"]
          }
        ]
      }
    ]
  }'

​
Example: Multiple Providers

curl -X PUT https://your-domain.com/recipe/multitenancy/tenant \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "customer1",
    "thirdPartyEnabled": true,
    "thirdPartyProviders": [
      {
        "thirdPartyId": "google",
        "clients": [
          {
            "clientId": "google-client-id",
            "clientSecret": "google-client-secret"
          }
        ]
      },
      {
        "thirdPartyId": "github",
        "clients": [
          {
            "clientId": "github-client-id",
            "clientSecret": "github-client-secret",
            "scope": ["user:email"]
          }
        ]
      },
      {
        "thirdPartyId": "facebook",
        "clients": [
          {
            "clientId": "facebook-app-id",
            "clientSecret": "facebook-app-secret",
            "scope": ["email", "public_profile"]
          }
        ]
      }
    ]
  }'

​
Provider-Specific Configuration

​
Google

{
  "thirdPartyId": "google",
  "clients": [
    {
      "clientId": "your-client-id.apps.googleusercontent.com",
      "clientSecret": "your-client-secret",
      "scope": ["email", "profile", "openid"]
    }
  ]
}
Required Scopes: email, profile, openid Email Verification: Google emails are typically verified by default

​
Facebook

{
  "thirdPartyId": "facebook",
  "clients": [
    {
      "clientId": "your-facebook-app-id",
      "clientSecret": "your-facebook-app-secret",
      "scope": ["email", "public_profile"]
    }
  ]
}
Required Scopes: email, public_profile Email Verification: Facebook emails may not be verified

​
GitHub

{
  "thirdPartyId": "github",
  "clients": [
    {
      "clientId": "your-github-client-id",
      "clientSecret": "your-github-client-secret",
      "scope": ["user:email"]
    }
  ]
}
Required Scopes: user:email Email Verification: GitHub emails are verified if the user has verified them on GitHub

​
Apple

{
  "thirdPartyId": "apple",
  "clients": [
    {
      "clientId": "your-apple-service-id",
      "clientSecret": {
        "keyId": "your-key-id",
        "teamId": "your-team-id",
        "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
      },
      "scope": ["email", "name"]
    }
  ]
}
Required Scopes: email, name Special Configuration: Apple requires a private key for client secret generation

​
Enabling/Disabling Third-Party Login

You can enable or disable third-party login for a specific tenant: 
curl -X PUT https://your-domain.com/recipe/multitenancy/tenant \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "customer1",
    "thirdPartyEnabled": false
  }'
When thirdPartyEnabled is set to false, all third-party sign-in attempts for that tenant will fail with a BadPermissionException.

​
Checking Provider Configuration

Retrieve the current tenant configuration to see enabled providers: 
curl -X GET https://your-domain.com/recipe/multitenancy/tenant?tenantId=customer1 \
  -H "api-key: your-api-key"

​
Multi-Tenant Provider Strategy

​
Strategy 1: Shared Providers

Use the same OAuth app for all tenants: 
// Tenant A and Tenant B both use the same Google OAuth app
{
  "thirdPartyId": "google",
  "clients": [
    {
      "clientId": "shared-client-id",
      "clientSecret": "shared-client-secret"
    }
  ]
}
Pros: Simple setup, single OAuth app to manage Cons: All users appear to come from the same OAuth app

​
Strategy 2: Tenant-Specific Providers

Use different OAuth apps per tenant: 
// Tenant A
{
  "thirdPartyId": "google",
  "clients": [
    {
      "clientId": "tenant-a-client-id",
      "clientSecret": "tenant-a-client-secret"
    }
  ]
}

// Tenant B
{
  "thirdPartyId": "google",
  "clients": [
    {
      "clientId": "tenant-b-client-id",
      "clientSecret": "tenant-b-client-secret"
    }
  ]
}
Pros: Better branding, tenant isolation Cons: More OAuth apps to manage

​
Security Considerations

Store Client Secrets SecurelyClient secrets are sensitive credentials. Ensure they are:
  • Never committed to version control
  • Stored in environment variables or secrets management systems
  • Rotated periodically
  • Restricted to authorized personnel only

​
Best Practices

  1. Use HTTPS Only: Always configure OAuth redirect URLs with HTTPS
  2. Validate Redirect URIs: Restrict OAuth redirect URIs to known domains
  3. Minimal Scopes: Request only the OAuth scopes you need
  4. Monitor Usage: Track which providers are being used and by whom
  5. Regular Audits: Periodically review and update provider configurations

​
Common Provider Issues

​
Issue: Provider Not Found

Cause: The provider is not configured for the tenant Solution: Verify the provider is added to the tenant’s thirdPartyProviders array

​
Issue: Invalid Client Credentials

Cause: Incorrect clientId or clientSecret Solution: Verify credentials match those in the provider’s developer console

​
Issue: Scope Errors

Cause: Missing required scopes Solution: Ensure all required scopes for the provider are included

​
Issue: Permission Denied

Cause: thirdPartyEnabled is set to false for the tenant Solution: Enable third-party login in the tenant configuration

Sign In/Up

Authenticate users with configured providers

Tenant Management

Manage tenant configurations

​
Source Code Reference

Tenant validation: View source

Build docs developers (and LLMs) love

Get started for freeTalk to us