Skip to main content
Paid Feature

This is a paid feature.

You can click on the Enable Paid Features button on our dashboard, and follow the steps from there on. Once enabled, this feature is free on the provided development environment.

Multiple frontend domains with separate backends

You can use the following guide if you have a single Authorization Service that is used by multiple applications. In turn, each app has separate frontend and backend instances that are served from different domains. Using the actual OAuth 2.0 terminology, each application can be considered a Client while the backends are also Resource Servers.

info

Note that, if the frontends and backends are in different sub domains, you don't need to use OAuth and can instead use session sharing across sub domains.

Multiple Frontend Domains with separate Backends

The authentication flow will work in the following way:

  1. The User accesses the frontend app
    • The application frontend calls a login endpoint on the backend application.
    • The backend application generates an authorization URL to the Authorization Service and redirects the user to it.
    • The Authorization Service backend redirects the user to the login UI
  2. The User completes the login attempt
    • The Authorization Service backend redirects the user to a callback URL that includes the Authorization Code.
  3. The User accesses the callback URL
    • The Authentication Code gets sent to the application backend
    • The backend exchanges the Authentication Code for an OAuth2 Access Token
    • The backend saves the received token in a server session and sends it back to the frontend as a cookie.

The frontend can now use the new cookie to access protected resources from the backend.

info

This guide assumes that you already have setup and configured SuperTokens in your Authorization Service.

For more information on how to do that please check our quickstart guides.

1. Enable the OAuth2 features from the Dashboard#

You will first have to enable the OAuth2 features from the SuperTokens.com Dashboard.

  1. Open the SuperTokens.com Dashboard
  2. Click on the Enabled Paid Features button
  3. Click on Managed Service
  4. Check the OAuth 2.0 option
  5. Click Save

Now you should be able to use the OAuth2 recipes in your applications.

2. Create the OAuth2 Clients#

For each of your applications you will have to create a separate OAuth2 client. This can be done by directly calling the SuperTokens Core API.

# You will have to run this for each one of your applications
# Adjust the client_name and redirect_uri based on that
curl -X POST /recipe/oauth2/admin/clients \
  -H "Content-Type: application/json" \
  -H "api-key: " \
  -d '{
      "clientName": "<YOUR_CLIENT_NAME>",
      "responseTypes": ["code", "id_token"],
      "grantTypes": ["authorization_code", "refresh_token"],
      "scope": "offline_access <custom_scope_1> <custom_scope_2>",
      "redirectUri": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"]
    }'
  • clientName - A human-readable name of the client that will be used for identification.
  • responseTypes - Specifies the types of responses your client expects from the Authorization Server. Most of the time, you would need the following two to be present:
  • grantTypes - The grant types that the Client will use.
  • redirectUri - A list of URIs to which the Authorization Server will send the user-agent (browser) after completing the authorization step. These can be deep links to mobile or desktop apps as well, but they must be exact URLs, without wildcards.
  • scope - A space separated string of scopes that the Client will request access to.

If the creation was successful, the API will return a response that looks like this:


{
    "clientName": "<YOUR_CLIENT_NAME>",
    "clientId": "<CLIENT_ID>",
    "clientSecret": "<CLIENT_SECRET>",
    "callbackUrls": ["https://<YOUR_APPLICATION_DOMAIN>/oauth/callback"],
}


Based on the client creation process we can also infer two additional values that we will need later on:

  • authorizeUrl corresponds to <YOUR_API_DOMAIN>/auth/oauth/auth
  • tokenFetchUrl corresponds to <YOUR_API_DOMAIN>/auth/oauth/token
caution

You will have to save this response because we do not persist it internally for security reasons. In the next steps we will use the values to complete several configurations.

Change the default token lifespan#

By default, the tokens used in the authorization flow will have the following lifespans:

If you want to change the default values you need to specify additional properties in the Client creation request body. Use string values that signify time duration in milliecoseconds, seconds, minutes or hours (e.g. "2000ms", "60s", "30m", "1h"). There are no limits on the duration of each token.

  • OAuth2 Access Token - Set the authorizationCodeGrantAccessTokenLifespan property.
  • OAuth2 ID Token - Set the authorizationCodeGrantIdTokenLifespan property.
  • OAuth2 Refresh Token - Set both the authorizationCodeGrantRefreshTokenLifespan and the refreshTokenGrantRefreshTokenLifespan properties to the same value.

Disable Refresh Token Rotation#

By default, a refresh token is one time use. This means, once a refresh token is used to get a new access token, it cannot be used again. If your use case cannot accomodate the process of changing the OAuth2 Refresh Token for a new one, you can make it so that this behavior does not apply for your implementation.

In order to achieve this behavior just set the enableRefreshTokenRotation property to false in the Client creation request body.

3. Set Up your Authorization Service#

Configure the Authorization Service Backend#

In your Authorization Service you will need to initialize the OAuth2Provider recipe. The recipe will expose the endpoints needed for enabling the OAuth 2.0 flow.

Update the supertokens.init call to include the OAuth2Provider recipe.

Add the import statement for the recipe and update the list of recipes with the new initialization step.

import supertokens from "supertokens-node";
import OAuth2Provider from "supertokens-node/recipe/oauth2provider";

supertokens.init({
    supertokens: {
        connectionURI: "...",
        apiKey: "...",
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "...",
    },
    recipeList: [
        OAuth2Provider.init(),
    ]
});

Configure the Authorization Service Frontend#

Initialize the OAuth2Provider recipe on the frontend of your Authorization Service.

info

If you want to use your own custom UI check our separate guide that explains all the steps that you have to take into account.

Add the import statement for the new recipe and update the list of recipe to also include the new initialization.

import OAuth2Provider from "supertokens-auth-react/recipe/oauth2provider";
import SuperTokens from "supertokens-auth-react";

SuperTokens.init({
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "...",
    },
    recipeList: [
        OAuth2Provider.init()
    ]
});

Include the pre built UI in the rendering tree.#

Do you use react-router-dom?
YesNo

4. Set Up Session Handling in Each Application#

In each of your individual applications you will have to setup up logic for handling the OAuth 2.0 authentication flow. We recommend using a generic OICD or OAuth2 library in order to do this.

You can use the passport-oauth2 library. Just follow the instructions on the library's page and setup your application backend. The configuration parameters can be determined based on the response that we received on step 2, when we created the OAuth2 Client.

  • authorizationURL corresponds to authorizeUrl
  • tokenURL corresponds to tokenFetchUrl
  • clientID corresponds to clientId
  • clientSecret corresponds to clientSecret
  • callbackURL corresponds to a value from callbackUrls
  • scope corresponds to scope

Make sure that you expose an endpoint that will call passport.authenticate('oauth2'). This way the user will end up accessing the actual login page served by the Authorization Service.

info

If you want to use the OAuth2 Refresh Tokens make sure to include the offline_access scope during the initialization step.

5. Update the login flow in your frontend applications#

In your frontend applications you will have to add a login action that will direct the user to the authentication page.

The user should first be redirected to the backend authentication endpoint that was defined during the previous step. There the backend will generate a safe authorization URL using the OAuth2 library and then redirect the user there. After the user has logged in from the Authorization Service they will be redirected to the backend callback URL. Then the authentication session will be created and the backend will send it to the user agent as a cookie.

6. Test the new authentication flow#

With everything set up, you can now test your login flow. Just use the setup that you have created in the previous step to check if the authentication flow completes without any issues.

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI