Skip to content
SuperTokens Docs
Esc
↑↓navigate↵open⌘Jpreview
Dashboard
On this page

Set Up Social Login

Integrate Google, Apple, and other OAuth providers with ThirdParty and Session recipes, callback routes, and prebuilt or custom UI.

Add social login providers to an existing application.

Overview

This page shows you how to authenticate, using ThirdParty Providers, with SuperTokens. The tutorial creates a login flow, rendered by either the Prebuilt UI components or by your own Custom UI.

Steps

UI type

1. Initialize the frontend SDK

1.1 Add the ThirdParty recipe in your main configuration file.

import React from "react";

import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import ThirdParty, { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
  appInfo: {
    // learn more about this on https://supertokens.com/docs/references/frontend-sdks/reference#sdk-configuration
    appName: "<YOUR_APP_NAME>",
    apiDomain: "<YOUR_API_DOMAIN>",
    websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
    apiBasePath: "/auth",
    websiteBasePath: "/auth",
  },
  recipeList: [
    ThirdParty.init({
      signInAndUpFeature: {
        providers: [Github.init(), Google.init(), Facebook.init(), Apple.init()],
      },
    }),
    Session.init(),
  ],
});

1.2 Include the pre-built UI components in your application.

In order for the pre-built UI to render inside your application, you have to specify which routes show the authentication components. The React SDK uses React Router under the hood to achieve this. Based on whether you already use this package or not in your project, there are two different ways of configuring the routes.

Change the button style

On the frontend, you can provide a button component to the in-built providers defining your own UI. The component you add is clickable by default.

import SuperTokens from "supertokens-auth-react";
import ThirdParty, { Google, Github, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty";
SuperTokens.init({
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    ThirdParty.init({
      signInAndUpFeature: {
        providers: [
          Github.init({
            buttonComponent: (props: { name: string }) => <div></div>,
          }),
          Google.init({
            buttonComponent: (props: { name: string }) => <div></div>,
          }),
          Facebook.init({
            buttonComponent: (props: { name: string }) => <div></div>,
          }),
          Apple.init({
            buttonComponent: (props: { name: string }) => <div></div>,
          }),
        ],
        // ...
      },
      // ...
    }),
    // ...
  ],
});

2. Initialize the backend SDK

You have to initialize the Backend Software Development Kit (SDK) alongside the code that starts your server. The init call includes configuration details for your app. It specifies how the backend connects to the SuperTokens Core, as well as the Recipes used in your setup.

import supertokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import ThirdParty from "supertokens-node/recipe/thirdparty";

supertokens.init({
  // Replace this with the framework you are using
  framework: "express",
  supertokens: {
    // We use try.supertokens for demo purposes.
    // At the end of the tutorial we will show you how to create
    // your own SuperTokens core instance and then update your config.
    connectionURI: "https://try.supertokens.io",
    // apiKey: <YOUR_API_KEY>
  },
  appInfo: {
    // learn more about this on https://supertokens.com/docs/references/backend-sdks/reference#sdk-configuration
    appName: "<YOUR_APP_NAME>",
    apiDomain: "<YOUR_API_DOMAIN>",
    websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
    apiBasePath: "/auth",
    websiteBasePath: "/auth",
  },
  recipeList: [
    ThirdParty.init({
      /*TODO: See next step*/
    }),
    Session.init(),
  ],
});
from supertokens_python import init, InputAppInfo, SupertokensConfig
from supertokens_python.recipe import thirdparty, session

init(
    app_info=InputAppInfo(
        app_name="<YOUR_APP_NAME>",
        api_domain="<YOUR_API_DOMAIN>",
        website_domain="<YOUR_WEBSITE_DOMAIN>",
        api_base_path="/auth",
        website_base_path="/auth"
    ),
    supertokens_config=SupertokensConfig(
        # We use try.supertokens for demo purposes.
        # At the end of the tutorial we will show you how to create
        # your own SuperTokens core instance and then update your config.
        connection_uri="https://try.supertokens.io",
        # api_key: <YOUR_API_KEY>
    ),
    framework='fastapi',
    recipe_list=[
        session.init(), # initializes session features
        thirdparty.init(
           # TODO: See next step
        )
    ],
    mode='asgi' # use wsgi if you are running using gunicorn
)
import (
	"github.com/supertokens/supertokens-golang/recipe/session"
	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
	"github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
  apiBasePath := "/auth"
  websiteBasePath := "/auth"
  err := supertokens.Init(supertokens.TypeInput{
    Supertokens: &supertokens.ConnectionInfo{
          // We use try.supertokens for demo purposes.
          // At the end of the tutorial we will show you how to create
          // your own SuperTokens core instance and then update your config.
          ConnectionURI: "https://try.supertokens.io",
          // APIKey: <YOUR_API_KEY>
    },
    AppInfo: supertokens.AppInfo{
            AppName: "<YOUR_APP_NAME>",
            APIDomain: "<YOUR_API_DOMAIN>",
            WebsiteDomain: "<YOUR_WEBSITE_DOMAIN>",
            APIBasePath: &apiBasePath,
            WebsiteBasePath: &websiteBasePath,
    },
    RecipeList: []supertokens.Recipe{
			thirdparty.Init(&tpmodels.TypeInput{/*TODO: See next step*/}),
      session.Init(nil), // initializes session features
    },
  })

	if err != nil {
		panic(err.Error())
	}
}

3. Add the authentication providers

Populate the providers array with the third-party authentication providers that you want.

import SuperTokens from "supertokens-node";
import ThirdParty from "supertokens-node/recipe/thirdparty";

SuperTokens.init({
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    ThirdParty.init({
      signInAndUpFeature: {
        // Load these credentials from environment variables or a secret manager.
        providers: [
          {
            config: {
              thirdPartyId: "google",
              clients: [
                {
                  clientId: "<GOOGLE_CLIENT_ID>",
                  clientSecret: "<GOOGLE_CLIENT_SECRET>",
                },
              ],
            },
          },
          {
            config: {
              thirdPartyId: "github",
              clients: [
                {
                  clientId: "<GITHUB_CLIENT_ID>",
                  clientSecret: "<GITHUB_CLIENT_SECRET>",
                },
              ],
            },
          },
          {
            config: {
              thirdPartyId: "apple",
              clients: [
                {
                  clientId: "<APPLE_CLIENT_ID>",
                  additionalConfig: {
                    keyId: "<APPLE_KEY_ID>",
                    privateKey: "<APPLE_PRIVATE_KEY>",
                    teamId: "<APPLE_TEAM_ID>",
                  },
                },
              ],
            },
          },
        ],
      },
    }),
    // ...
  ],
});
import (
	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
)

func main() {
	// Inside supertokens.Init
	thirdparty.Init(&tpmodels.TypeInput{
		SignInAndUpFeature: tpmodels.TypeInputSignInAndUp{
			Providers: []tpmodels.ProviderInput{
				// Load these credentials from environment variables or a secret manager.
				{
					Config: tpmodels.ProviderConfig{
						ThirdPartyId: "google",
						Clients: []tpmodels.ProviderClientConfig{
							{
								ClientID: "<GOOGLE_CLIENT_ID>",
								ClientSecret: "<GOOGLE_CLIENT_SECRET>",
							},
						},
					},
				},
				{
					Config: tpmodels.ProviderConfig{
						ThirdPartyId: "github",
						Clients: []tpmodels.ProviderClientConfig{
							{
								ClientID:     "<GITHUB_CLIENT_ID>",
								ClientSecret: "<GITHUB_CLIENT_SECRET>",
							},
						},
					},
				},
				{
					Config: tpmodels.ProviderConfig{
						ThirdPartyId: "apple",
						Clients: []tpmodels.ProviderClientConfig{
							{
								ClientID: "<APPLE_CLIENT_ID>",
								AdditionalConfig: map[string]interface{}{
									"keyId":      "<APPLE_KEY_ID>",
									"privateKey": "<APPLE_PRIVATE_KEY>",
									"teamId":     "<APPLE_TEAM_ID>",
								},
							},
						},
					},
				},
			},
		},
	})
}
from supertokens_python.recipe.thirdparty.provider import ProviderInput, ProviderConfig, ProviderClientConfig
from supertokens_python.recipe import thirdparty

# Inside init
thirdparty.init(
    sign_in_and_up_feature=thirdparty.SignInAndUpFeature(providers=[
        # Load these credentials from environment variables or a secret manager.
        ProviderInput(
            config=ProviderConfig(
                third_party_id="google",
                clients=[
                    ProviderClientConfig(
                        client_id="<GOOGLE_CLIENT_ID>",
                        client_secret="<GOOGLE_CLIENT_SECRET>",
                    ),
                ],
            ),
        ),
        ProviderInput(
            config=ProviderConfig(
                third_party_id="github",
                clients=[
                    ProviderClientConfig(
                        client_id="<GITHUB_CLIENT_ID>",
                        client_secret="<GITHUB_CLIENT_SECRET>",
                    )
                ],
            ),
        ),
        ProviderInput(
            config=ProviderConfig(
                third_party_id="apple",
                clients=[
                    ProviderClientConfig(
                        client_id="<APPLE_CLIENT_ID>",
                        additional_config={
                            "keyId": "<APPLE_KEY_ID>",
                            "privateKey": "<APPLE_PRIVATE_KEY>",
                            "teamId": "<APPLE_TEAM_ID>"
                        },
                    ),
                ],
            ),
        ),
    ])
)

Set OAuth scopes

To add additional OAuth scopes when accessing your third-party provider, add them to the configuration when initializing the backend SDK.

For example, if you are using Google as your third-party provider, you can add an additional scope as follows:

import SuperTokens from "supertokens-node";
import ThirdParty from "supertokens-node/recipe/thirdparty";

SuperTokens.init({
  supertokens: {
    connectionURI: "...",
  },
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    ThirdParty.init({
      signInAndUpFeature: {
        providers: [
          {
            config: {
              thirdPartyId: "google",
              clients: [
                {
                  clientId: "TODO: GOOGLE_CLIENT_ID",
                  clientSecret: "TODO: GOOGLE_CLIENT_SECRET",
                  scope: ["scope1", "scope2"],
                },
              ],
            },
          },
        ],
      },
    }),
  ],
});
import (
	"github.com/supertokens/supertokens-golang/recipe/thirdparty"
	"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
	"github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
	supertokens.Init(supertokens.TypeInput{
		RecipeList: []supertokens.Recipe{
			thirdparty.Init(&tpmodels.TypeInput{
				SignInAndUpFeature: tpmodels.TypeInputSignInAndUp{
					Providers: []tpmodels.ProviderInput{
						{
							Config: tpmodels.ProviderConfig{
								ThirdPartyId: "google",
								Clients: []tpmodels.ProviderClientConfig{
									{
										ClientID:     "TODO: GOOGLE_CLIENT_ID",
										ClientSecret: "TODO: GOOGLE_CLIENT_SECRET",
										Scope: []string{
											"scope1", "scope2",
										},
									},
								},
							},
						},
					},
				},
			}),
		},
	})
}
from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import thirdparty
from supertokens_python.recipe.thirdparty import ProviderInput, ProviderConfig, ProviderClientConfig, SignInAndUpFeature

init(
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    framework='...',
    recipe_list=[
        thirdparty.init(

            sign_in_and_up_feature=SignInAndUpFeature(
                providers=[
                    ProviderInput(
                        config=ProviderConfig(
                            third_party_id="google",
                            clients=[
                                ProviderClientConfig(
                                    client_id="GOOGLE_CLIENT_ID",
                                    client_secret="GOOGLE_CLIENT_SECRET",
                                    scope=["scope1", "scope2"]
                                ),
                            ],
                        ),
                    ),
                ]
            )
        )
    ]
)

Next steps

Having completed the main setup, you can explore more advanced topics related to the ThirdParty recipe.

Built-in Providers

Read more about the common providers exposed by the recipe.

Custom Providers

See how you can create your own custom provider.

Custom Invite Flow

Disable public sign ups and use your own invite flow.

Hooks and Overrides

Add custom logic after the logs in or signs up.

API reference

API schema and response details