Skip to main content

Initial setup

Authenticate using SuperTokens with ThirdParty Providers, creating a custom or prebuilt login flow.

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.

Before you start

important

These instructions assume that you already have gone through the main quickstart guide. If you have skipped that page please follow the tutorial and return here once you're done.

Steps

What type of UI are you using?

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/app-info
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.

Do you use react-router-dom?

import React from 'react';
import {
BrowserRouter,
Routes,
Route,
Link
} from "react-router-dom";

import { ThirdPartyPreBuiltUI } from 'supertokens-auth-react/recipe/thirdparty/prebuiltui';
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react/ui";
import * as reactRouterDom from "react-router-dom";

class App extends React.Component {
render() {
return (
<SuperTokensWrapper>
<BrowserRouter>
<Routes>
{/*This renders the login UI on the /auth route*/}
{getSuperTokensRoutesForReactRouterDom(reactRouterDom, [ThirdPartyPreBuiltUI])}
{/*Your app routes*/}
</Routes>
</BrowserRouter>
</SuperTokensWrapper>
);
}
}
important

If you are using useRoutes, createBrowserRouter or have routes defined in a different file, you need to adjust the code sample. Please see this issue for further details.

import React from 'react';

import { BrowserRouter, useRoutes } from "react-router-dom";
import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react/ui";
import * as reactRouterDom from "react-router-dom";

function AppRoutes() {
const authRoutes = getSuperTokensRoutesForReactRouterDom(
reactRouterDom,
[/* Add your UI recipes here e.g. EmailPasswordPrebuiltUI, PasswordlessPrebuiltUI, ThirdPartyPrebuiltUI */]
);

const routes = useRoutes([
...authRoutes.map(route => route.props),
// Include the rest of your app routes
]);

return routes;
}

function App() {
return (
<SuperTokensWrapper>
<BrowserRouter>
<AppRoutes />
</BrowserRouter>
</SuperTokensWrapper>
);
}

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.

Backend SDK Init
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/app-info
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()
]
});

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: {
// We have provided you with development keys which you can use for testing.
// IMPORTANT: Please replace them with your own OAuth keys for production use.
providers: [{
config: {
thirdPartyId: "google",
clients: [{
clientId: "1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com",
clientSecret: "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"
}]
}
}, {
config: {
thirdPartyId: "github",
clients: [{
clientId: "467101b197249757c71f",
clientSecret: "e97051221f4b6426e8fe8d51486396703012f5bd"
}]
}
}, {
config: {
thirdPartyId: "apple",
clients: [{
clientId: "4398792-io.supertokens.example.service",
additionalConfig: {
keyId: "7M48Y4RYDL",
privateKey:
"-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgu8gXs+XYkqXD6Ala9Sf/iJXzhbwcoG5dMh1OonpdJUmgCgYIKoZIzj0DAQehRANCAASfrvlFbFCYqn3I2zeknYXLwtH30JuOKestDbSfZYxZNMqhF/OzdZFTV0zc5u5s3eN+oCWbnvl0hM+9IW0UlkdA\n-----END PRIVATE KEY-----",
teamId: "YWQCXGJRJL",
}
}]
}
}],
}
}),
// ...
]
});
important

The examples use a set of development keys meant for demonstration purposes only. Please use your own OAuth credentials. Read the list of built-in providers that also includes information on how to generate your own keys. To add a provider that is not listed, you can follow the guide on setting up custom providers.

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"]
}]
}
}
]
}
})
]
});
important

Along with your custom scopes, also add scopes that ask for the user's email and its verification status. For example, with Google, this scope is "https://www.googleapis.com/auth/userinfo.email".

Next steps

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