Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Which UI do you use?
Custom UI
Pre built UI

Protecting frontend routes

CAUTION

This information only applies to scenarios in which you are using SuperTokens Session Access Tokens.

If you are implementing Unified Login you will have to manually check authentication state based the OAuth2/OIDC library that you are using. Please explore the dedicated documentation to find out more.

Requiring a session to access a route #

You can wrap your components with the <SessionAuth> react component. This will ensure that your component renders only if the user is logged in. If they are not logged in, the user will be redirected to the login page.

import React from "react";
import {
    BrowserRouter,
    Routes,
    Route,
} from "react-router-dom";
import { SuperTokensWrapper } from "supertokens-auth-react";
import { SessionAuth } from "supertokens-auth-react/recipe/session";
import MyDashboardComponent from "./dashboard";

class App extends React.Component {
    render() {
        return (
            <SuperTokensWrapper>
                <BrowserRouter>
                    <Routes>
                        <Route path="/dashboard" element={
                            <SessionAuth>
                                {/*Components that require to be protected by authentication*/}
                                <MyDashboardComponent />
                            </SessionAuth>
                        } />
                    </Routes>
                </BrowserRouter>
            </SuperTokensWrapper>
        );
    }
}

Optional session on a route #

You can provide the requireAuth={false} prop when using <SessionAuth> as shown below:

import React from "react";
import {
    BrowserRouter,
    Routes,
    Route,
} from "react-router-dom";
import { SuperTokensWrapper } from "supertokens-auth-react";
import Session, { SessionAuth } from "supertokens-auth-react/recipe/session";

class App extends React.Component {
    render() {
        return (
            <SuperTokensWrapper>
                <BrowserRouter>
                    <Routes>
                        <Route path="/dashboard" element={
                            <SessionAuth requireAuth={false}>
                                <MyDashboardComponent />
                            </SessionAuth>
                        } />
                    </Routes>
                </BrowserRouter>
            </SuperTokensWrapper>
        );
    }
}

function MyDashboardComponent(props: any) {
    let sessionContext = Session.useSessionContext();

    if (sessionContext.loading) {
        return null;
    }

    if (sessionContext.doesSessionExist) {
        // TODO:
    } else {
        // TODO:
    }

    return null;
}

Verifying the claims of a session #

Sometimes, you may also want to check if there are certain claims in the session before granting access to a route. For example, you may want to check that the session has the admin role claim for certain APIs, or that the user has completed 2FA.

This can be done using our session claims validator feature. Let's take an example of using the user roles claim to check if the session has the admin claim:

import React from "react";
import { SessionAuth } from 'supertokens-auth-react/recipe/session';
import { AccessDeniedScreen } from 'supertokens-auth-react/recipe/session/prebuiltui';
import { UserRoleClaim, /*PermissionClaim*/ } from 'supertokens-auth-react/recipe/userroles';

const AdminRoute = (props: React.PropsWithChildren<any>) => {
    return (
        <SessionAuth 
            accessDeniedScreen={AccessDeniedScreen}
            overrideGlobalClaimValidators={(globalValidators) => [
                ...globalValidators, UserRoleClaim.validators.includes("admin"),
            ]
        }>
            {props.children}
        </SessionAuth>
    );
}

Above we are creating a generic component called AdminRoute which enforces that its child components can only be rendered if the user has the admin role.

In the AdminRoute component, we use the SessionAuth wrapper to ensure that the session exists. We also add the UserRoleClaim validator to the <SessionAuth> component which checks if the validators pass or not. If all validation passes, we render the props.children component. If the claim validation has failed, it will display the AccessDeniedScreen component instead of rendering the children. You can also pass your own custom component to the accessDeniedScreen prop.

note

You can extend the AdminRoute component to check for other types of validators as well. This component can then be reused to protect all of your app's components (In this case, you may want to rename this component to something more appropriate, like ProtectedRoute).

If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself:

import Session from "supertokens-auth-react/recipe/session";
import {UserRoleClaim} from "supertokens-auth-react/recipe/userroles"

function ProtectedComponent() {
    let claimValue = Session.useClaimValue(UserRoleClaim)
    if (claimValue.loading || !claimValue.doesSessionExist) {
        return null;
    }
    let roles = claimValue.value;
    if (Array.isArray(roles) && roles.includes("admin")) {
        // User is an admin
    } else {
        // User doesn't have any roles, or is not an admin..
    }
}
feature

You can also build your own custom claim validators based on your app's requirements.

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