Social login
There are different flows that the third party login provider may support:
- Flow 1) Via authorisation code (one time use code) - for web and mobile apps.
- a) If you have configred the client secret on the backend:
- The frontend sends the auth code to the backend, the backend exchanges that with the provided client secret to get the access token. The access token is then used to fetch user info and log them in.
- b) If you have not provided the client secret on the backend:
- The backend uses PKCE flow to exchange the auth code with the user's access token. The access token is then used to fetch user info and log them in.
- a) If you have configred the client secret on the backend:
- Flow 2) Via OAuth / access tokens - for mobile apps.
- The access token is available on the frontend and is sent to the backend. SuperTokens then fetches user info using the access token and logs them in.
note
The same flow applies during sign up and sign in. If the user is signing up, the createdNewUser
boolean on the frontend and backend will be true
(as the result of the sign in up API call).
- Web
- Mobile
Flow 1a: Authorization code grant flow (Sign in with Google example)
Step 1) Redirecting to social / SSO provider
The first step is to fetch the URL on which the user will be authenticated. This can be done by querying the backend API exposed by SuperTokens (as shown below). The backend SDK automatically appends the right query params to the URL (like scope, client ID etc).
After we get the URL, we simply redirect the user there. In the code below, we will take an example of login with Google:
- Via NPM
- Via Script Tag
import { getAuthorisationURLWithQueryParamsAndSetState } from "supertokens-web-js/recipe/thirdparty";
async function googleSignInClicked() {
try {
const authUrl = await getAuthorisationURLWithQueryParamsAndSetState({
thirdPartyId: "google",
// This is where Google should redirect the user back after login or error.
// This URL goes on the Google's dashboard as well.
frontendRedirectURI: "http://<YOUR_WEBSITE_DOMAIN>/auth/callback/google",
});
/*
Example value of authUrl: https://accounts.google.com/o/oauth2/v2/auth/oauthchooseaccount?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&access_type=offline&include_granted_scopes=true&response_type=code&client_id=1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com&state=5a489996a28cafc83ddff&redirect_uri=https%3A%2F%2Fsupertokens.io%2Fdev%2Foauth%2Fredirect-to-app&flowName=GeneralOAuthFlow
*/
// we redirect the user to google for auth.
window.location.assign(authUrl);
} catch (err: any) {
if (err.isSuperTokensGeneralError === true) {
// this may be a custom error message sent from the API by you.
window.alert(err.message);
} else {
window.alert("Oops! Something went wrong.");
}
}
}
async function googleSignInClicked() {
try {
const authUrl = await supertokensThirdParty.getAuthorisationURLWithQueryParamsAndSetState({
thirdPartyId: "google",
// This is where Google should redirect the user back after login or error.
// This URL goes on the Google's dashboard as well.
frontendRedirectURI: "http://<YOUR_WEBSITE_DOMAIN>/auth/callback/google",
});
/*
Example value of authUrl: https://accounts.google.com/o/oauth2/v2/auth/oauthchooseaccount?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&access_type=offline&include_granted_scopes=true&response_type=code&client_id=1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com&state=5a489996a28cafc83ddff&redirect_uri=https%3A%2F%2Fsupertokens.io%2Fdev%2Foauth%2Fredirect-to-app&flowName=GeneralOAuthFlow
*/
// we redirect the user to google for auth.
window.location.assign(authUrl);
} catch (err: any) {
if (err.isSuperTokensGeneralError === true) {
// this may be a custom error message sent from the API by you.
window.alert(err.message);
} else {
window.alert("Oops! Something went wrong.");
}
}
}
Step 2) Handling the auth callback on your frontend
Once the third party provider redirects your user back to your app, you need to consume the information to sign in the user. This requires you to:
Setup a route in your app that will handle this callback. We recommend something like
http://<YOUR_WEBSITE_DOMAIN>/auth/callback/google
(for Google). Regardless of what you make this path, remember to use that same path when calling thegetAuthorisationURLWithQueryParamsAndSetState
function in the first step.On that route, call the following function on page load
- Via NPM
- Via Script Tag
import { signInAndUp } from "supertokens-web-js/recipe/thirdparty";
async function handleGoogleCallback() {
try {
const response = await signInAndUp();
if (response.status === "OK") {
console.log(response.user)
if (response.createdNewUser) {
// sign up successful
} else {
// sign in successful
}
window.location.assign("/home");
} else {
// SuperTokens requires that the third party provider
// gives an email for the user. If that's not the case, sign up / in
// will fail.
// As a hack to solve this, you can override the backend functions to create a fake email for the user.
window.alert("No email provided by social login. Please use another form of login");
window.location.assign("/auth"); // redirect back to login page
}
} catch (err: any) {
if (err.isSuperTokensGeneralError === true) {
// this may be a custom error message sent from the API by you.
window.alert(err.message);
} else {
window.alert("Oops! Something went wrong.");
}
}
}async function handleGoogleCallback() {
try {
const response = await supertokensThirdParty.signInAndUp();
if (response.status === "OK") {
console.log(response.user)
if (response.createdNewUser) {
// sign up successful
} else {
// sign in successful
}
window.location.assign("/home");
} else {
// SuperTokens requires that the third party provider
// gives an email for the user. If that's not the case, sign up / in
// will fail.
// As a hack to solve this, you can override the backend functions to create a fake email for the user.
window.alert("No email provided by social login. Please use another form of login");
window.location.assign("/auth"); // redirect back to login page
}
} catch (err: any) {
if (err.isSuperTokensGeneralError === true) {
// this may be a custom error message sent from the API by you.
window.alert(err.message);
} else {
window.alert("Oops! Something went wrong.");
}
}
}
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Special case for login with Apple
Unlike other providers, Apple will not redirect your user back to your frontend app. Instead, it will redirect the user to your backend with a FORM POST
request. This means that the URL that you configure on the Apple's dashboard should point to your backend API layer in which our middleware will handle the request and redirect the user to your frontend app. Your frontend app should then call the signInAndUp
API on that page as shown previously.
In order to tell SuperTokens which frontend route to redirect the user back to, you need to set the frontendRedirectURI
to the frontend route (just like for other providers), and also need to set the redirectURIOnProviderDashboard
to point to your backend API route (to which Apple will send a POST request).
- Via NPM
- Via Script Tag
import { getAuthorisationURLWithQueryParamsAndSetState } from "supertokens-web-js/recipe/thirdparty";
async function appleSignInClicked() {
try {
const authUrl = await getAuthorisationURLWithQueryParamsAndSetState({
thirdPartyId: "apple",
frontendRedirectURI: "http://localhost:3000/auth/callback/apple", // This is an example callback URL on your frontend. You can use another path as well.
redirectURIOnProviderDashboard: "<YOUR_API_DOMAIN>/auth/callback/apple", // This URL goes on the Apple's dashboard
});
// we redirect the user to apple for auth.
window.location.assign(authUrl);
} catch (err: any) {
if (err.isSuperTokensGeneralError === true) {
// this may be a custom error message sent from the API by you.
window.alert(err.message);
} else {
window.alert("Oops! Something went wrong.");
}
}
}
async function appleSignInClicked() {
try {
const authUrl = await supertokensThirdParty.getAuthorisationURLWithQueryParamsAndSetState({
thirdPartyId: "apple",
frontendRedirectURI: "http://localhost:3000/auth/callback/apple", // This is an example callback URL on your frontend. You can use another path as well.
redirectURIOnProviderDashboard: "<YOUR_API_DOMAIN>/auth/callback/apple", // This URL goes on the Apple's dashboard
});
/*
Example value of authUrl: https://accounts.google.com/o/oauth2/v2/auth/oauthchooseaccount?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&access_type=offline&include_granted_scopes=true&response_type=code&client_id=1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com&state=5a489996a28cafc83ddff&redirect_uri=https%3A%2F%2Fsupertokens.io%2Fdev%2Foauth%2Fredirect-to-app&flowName=GeneralOAuthFlow
*/
// we redirect the user to google for auth.
window.location.assign(authUrl);
} catch (err: any) {
if (err.isSuperTokensGeneralError === true) {
// this may be a custom error message sent from the API by you.
window.alert(err.message);
} else {
window.alert("Oops! Something went wrong.");
}
}
}
Flow 1b: Authorization code grant flow with PKCE
This is identical to flow 1a, except that you do not need to provide a client secret during backend init. This flow only works for providers which support the PKCE flow.
Flow 2: Via OAuth / Access token
caution
This flow is not applicable for web apps.
Flow 1a: Authorization code grant flow (Sign in with Apple example)
- React Native
- Android
- iOS
- Flutter
Step 1) Fetching the authorisation token on the frontend
This involves setting up the react-native-apple-authentication library in your app. Checkout their README
for steps on how to integrate their SDK into your application. The minimum scope required by SuperTokens is the one that gives the user's email (In case of Apple, that could be the user's actual email or the proxy email provided by Apple - it doesn't really matter).
Once the integration is done, you should call the appleAuth.performRequest
function for iOS and the appleAuthAndroid.signIn
function for Android. Either way, the result of the function will be a one time use auth code which you should send to your backend as shown in the next step.
Step 1) Fetching the authorisation token on the frontend
info
Coming Soon
For iOS you use the normal sign in with apple flow and then use the id token to login with SuperTokens
import UIKit
import AuthenticationServices
class ViewController: UIViewController, ASAuthorizationControllerPresentationContextProviding, ASAuthorizationControllerDelegate {
func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {
return view.window!
}
func loginWithApple() {
let authorizationRequest = ASAuthorizationAppleIDProvider().createRequest()
authorizationRequest.requestedScopes = [.email, .fullName]
let authorizationController = ASAuthorizationController(authorizationRequests: [authorizationRequest])
authorizationController.presentationContextProvider = self
authorizationController.delegate = self
authorizationController.performRequests()
}
func authorizationController(controller: ASAuthorizationController, didCompleteWithAuthorization authorization: ASAuthorization) {
guard let credential: ASAuthorizationAppleIDCredential = authorization.credential as? ASAuthorizationAppleIDCredential,
let authorizationCode = credential.authorizationCode,
let authorizationCodeString: String = String(data: authorizationCode, encoding: .utf8),
let email: String = credential.email as? String,
let nameComponents: PersonNameComponents = credential.fullname as? PersonNameComponents,
let firstName: String = nameComponents.givenName as? String,
let lastName: String = nameComponents.familyName as? String else {return}
// Send the user information and auth code to the backend. Refer to the next step.
}
}
info
Coming Soon
Step 2) Calling the signinup API to consume the authorisation token
- Single tenant setup
- Multi tenant setup
Once you have the authorisation code from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"thirdPartyId": "apple",
"clientType": "...",
"redirecURIInfo": {
"redirectURIOnProviderDashboard": "<YOUR_API_DOMAIN>/auth/callback/apple",
"redirectURIQueryParams": {
"code": "...",
"user": {
"name":{
"firstName":"...",
"lastName":"..."
},
"email":"..."
}
}
}
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - On iOS,
redirectURIOnProviderDashboard
doesn't matter and its value can be a universal link configured for your app. - On Android, the
redirectURIOnProviderDashboard
should match the one configured on the Apple developer dashboard. - The
user
object contains information provided by Apple.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Once you have the authorisation code from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/<TENANT_ID>/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"thirdPartyId": "apple",
"clientType": "...",
"redirecURIInfo": {
"redirectURIOnProviderDashboard": "<YOUR_API_DOMAIN>/auth/<TENANT_ID>/callback/apple",
"redirectURIQueryParams": {
"code": "...",
"user": {
"name":{
"firstName":"...",
"lastName":"..."
},
"email":"..."
}
}
}
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - On iOS,
redirectURIOnProviderDashboard
doesn't matter and its value can be a universal link configured for your app. - On Android, the
redirectURIOnProviderDashboard
should match the one configured on the Apple developer dashboard. - The
user
object contains information provided by Apple.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Flow 1b: Authorization code grant flow with PKCE
This is similar to flow 1a, except that you do not need to provide a client secret during backend init. This flow only works for providers which support the PKCE flow.
- React Native
- Android
- iOS
- Flutter
Step 1) Fetching the authorisation token on the frontend
See the setup step for this in flow 1a. In addition to that, you need to configure the react native auth library to also return the PKCE code verifier along with the authorization code. This can be done by setting the usePKCE
boolean to true
and also by setting the skipCodeExchange
to true
when configuring the react native auth library.
The minimum scope that is required by SuperTokens is one that gives you the user's email - in case of Google login, it is "https://www.googleapis.com/auth/userinfo.email"
.
Step 1) Fetching the authorisation token on the frontend
You can follow the official guide on how to use the PKCE flow with google sign in on Android
Step 1) Fetching the authorisation token on the frontend
You can follow the official guide on how to use the PKCE flow with google sign in on iOS
Step 2) Calling the signinup API to consume the authorisation token
- Single tenant setup
- Multi tenant setup
Once you have the authorisation code and PKCE verifier from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json' \
--data-raw '{
"thirdPartyId": "google",
"clientType": "...",
"redirectURIInfo": {
"redirectURIOnProviderDashboard": "<YOUR_API_DOMAIN>/auth/callback/google",
"redirectURIQueryParams": {
"code": "...",
},
"pkceCodeVerifier": "..."
}
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - On iOS,
redirectURIOnProviderDashboard
doesn't matter and its value can be a universal link configured for your app. - On Android, the
redirectURIOnProviderDashboard
should match the one configured on the Google cloud platform.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Once you have the authorisation code and PKCE verifier from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/<TENANT_ID>/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json' \
--data-raw '{
"thirdPartyId": "google",
"clientType": "...",
"redirectURIInfo": {
"redirectURIOnProviderDashboard": "<YOUR_API_DOMAIN>/auth/<TENANT_ID>/callback/google",
"redirectURIQueryParams": {
"code": "...",
},
"pkceCodeVerifier": "..."
}
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - On iOS,
redirectURIOnProviderDashboard
doesn't matter and its value can be a universal link configured for your app. - On Android, the
redirectURIOnProviderDashboard
should match the one configured on the Google cloud platform.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Flow 2: Via OAuth / Access token (Sign in with Google example)
- React Native
- Android
- iOS
- Flutter
Step 1) Fetching the OAuth / access tokens on the frontend
You can use the react-native-app-auth library in your app to integrate with Google and get the user's access token. The minimum scope that is required by SuperTokens is one that gives you the user's email - in case of Google login, it is "https://www.googleapis.com/auth/userinfo.email"
.
important
When setting up on the Google dashboard, you need to generate OAuth credentials for an Android application which will be used for both iOS and Android. Google does not provide a client secret in this case, so on the backend, you can give the clientSecret
config as an empty string.
Step 2) Calling the signinup API to use the OAuth tokens
- Single tenant setup
- Multi tenant setup
Once you have the access_token
or the id_token
from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"thirdPartyId": "google",
"clientType": "...",
"oAuthTokens": {
"access_token": "..."
},
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - If you have the
id_token
, you can also send that along with theaccess_token
.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Once you have the access_token
or the id_token
from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/<TENANT_ID>/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"thirdPartyId": "google",
"clientType": "...",
"oAuthTokens": {
"access_token": "..."
},
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - If you have the
id_token
, you can also send that along with theaccess_token
.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
For Android, Google recommends you to use their official Andoird library, which follows "Flow 1a" in these docs.
Essentially, the library will give you back a one time use auth code from Google which you can send to the /signinup
API (as shown in Flow 1a -> Step 2) to exchange it with an access token and the user's information.
important
On Google's dashboard, you should create a Web client to use for your Android app, otherwise Google won't return an access token to you.
Step 1) Fetching the OAuth / access tokens on the frontend
For iOS, you use the official guide for setting up Sign in with Google in your app. After the user successfully signs in, you can access the access token and id token from the Google signin result.
import UIKit
import GoogleSignIn
class ViewController: UIViewController {
func signInWithGoogle() {
let config = GIDConfiguration(clientID: "<CLIENT_ID>")
GIDSignIn.sharedInstance.signIn(with: config, presenting: self) {
user, error in
guard error == nil, let _user: GIDGoogleUser = user else {
// Sign in failed
return
}
let accessToken = _user.authentication.accessToken
let idToken = _user.authentication.idToken
// TODO: See next step
}
}
}
Step 2) Calling the signinup API to use the OAuth tokens
- Single tenant setup
- Multi tenant setup
Once you have the access_token
or the id_token
from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"thirdPartyId": "google",
"clientType": "...",
"oAuthTokens": {
"access_token": "...",
"id_token": "..."
},
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - If you have the
id_token
, you can send that along with theaccess_token
.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
Once you have the access_token
or the id_token
from the auth provider, you need to call the signinup API exposed by our backend SDK as shown below:
curl --location --request POST '<YOUR_API_DOMAIN>/auth/<TENANT_ID>/signinup' \
--header 'rid: thirdparty' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
"thirdPartyId": "google",
"clientType": "...",
"oAuthTokens": {
"access_token": "...",
"id_token": "..."
},
}'
important
- The
clientType
input is optional and is required only if you have initialised the same provider multiple times on the backend (See the "Social / SSO login for both, web and mobile apps" section below). - If you have the
id_token
, you can send that along with theaccess_token
.
The response body from the API call has a status
property in it:
status: "OK"
: User sign in / up was successful. The response also contains more information about the user, for example their user ID, and if it was a new user or existing user.status: "NO_EMAIL_GIVEN_BY_PROVIDER"
: This is returned if the social / SSO provider did not provider an email for the user. In this case, you want to ask the user to pick another method of sign in. Or, you can also override the backend functions to create a fake email for the user for this provider.status: "GENERAL_ERROR"
: This is only possible if you have overriden the backend API to send back a custom error message which should be displayed on the frontend.
note
On success, the backend will send back session tokens as part of the response headers which will be automatically handled by our frontend SDK for you.
#
Social / SSO login for both, web and mobile appsIf you have social / SSO login for your web and mobile app, then you might need to setup different client ID / secret for the same provider on the backend. For example, in case of Apple login, Apple gives you different client IDs for iOS login vs web & Android login (same client ID for web and Android).
In order to get this to work, you would need to add additional clients to the Apple.init on the backend. Each client would need to be uniquely identified and this is done using the clientType
string. For example, you can add one clientType
for web-and-android
and one for ios
.
- NodeJS
- GoLang
- Python
- Other Frameworks
Important
import { ProviderInput } from "supertokens-node/recipe/thirdparty/types";
let providers: ProviderInput[] = [
{
config: {
thirdPartyId: "apple",
clients: [{
clientType: "web-and-android",
clientId: "...",
additionalConfig: {
"keyId": "...",
"privateKey": "...",
"teamId": "...",
}
}, {
clientType: "ios",
clientId: "...",
additionalConfig: {
"keyId": "...",
"privateKey": "...",
"teamId": "...",
}
}]
}
}
]
import (
"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
)
func main() {
_ = []tpmodels.ProviderInput{
{
Config: tpmodels.ProviderConfig{
ThirdPartyId: "apple",
Clients: []tpmodels.ProviderClientConfig{
{
ClientType: "web-and-android",
ClientID: "...",
AdditionalConfig: map[string]interface{}{
"keyId": "...",
"privateKey": "...",
"teamId": "...",
},
},
{
ClientType: "ios",
ClientID: "...",
AdditionalConfig: map[string]interface{}{
"keyId": "...",
"privateKey": "...",
"teamId": "...",
},
},
},
},
},
}
}
from supertokens_python.recipe.thirdparty import Apple
providers = [
# Used for web and android login. These credentials will be used
# since is_default is True, if the frontend doesn't pass a clientID to the
# signinup API call, it will use this one.
Apple(
is_default=True,
client_id="...",
client_key_id="...",
client_private_key="...",
client_team_id="..."
),
# Used by iOS login. Notice that isDefault is not set here
Apple(
client_id="...",
client_key_id="...",
client_private_key="...",
client_team_id="..."
)
]
For the frontend, you would need to use the right clientType
as shown below:
- Web
- Mobile
- Via NPM
- Via Script Tag
We pass in the clientType
during the init call.
import SuperTokens from 'supertokens-web-js';
SuperTokens.init({
appInfo: {
apiDomain: "<YOUR_API_DOMAIN>",
apiBasePath: "/auth",
appName: "...",
},
clientType: "web-and-android",
recipeList: [/*...*/],
});
If you are using our pre built UI SDK (supertokens-auth-react) as well, you can provide the clientType
config to it as follows:
import SuperTokens from 'supertokens-auth-react';
SuperTokens.init({
appInfo: {
apiDomain: "<YOUR_API_DOMAIN>",
websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
apiBasePath: "/auth",
appName: "...",
},
clientType: "web-and-android",
recipeList: [/*...*/],
});
We pass in the clientType
during the init call.
supertokens.init({
appInfo: {
apiDomain: "<YOUR_API_DOMAIN>",
apiBasePath: "/auth",
appName: "...",
},
clientType: "web-and-android",
recipeList: [/*...*/],
});
When making calls to the APIs from your mobile app, the request body also takes a clientType
prop as seen in the above API calls.