SuperTokens

supertokens

by Supertokens Team Introduction So you’re creating a web app and have decided to use Supabase. You now face the decision of how you want to implement authentication. Supabase comes with its own authentication solution, based on a fork of . Netlify’s goTrue It provides authentication flows like email-password, social login, and phone number based OTP and is ideal for quickly building out authentication for many use cases. However, if your app is going to scale to a large number of users or have non-standard requirements, it may make sense to consider alternatives since GoTrue has some limitations: For example: For B2C apps: Features like account linking only link accounts that share the same email. For B2B apps: There is currently no support for multi factor authentication. Now that we know the limitations, let’s dive deeper into when to use Supabase auth and when to consider other solutions: : Use Supabase Auth if You need to quickly set up an app with Email-Password, Social Login, or Phone number-based authentication methods. Your app does not need a custom flow or you do not require multi-factor authentication. : Consider alternative solutions if You’re building a high-growth startup that will have a large number of users or will be selling to big companies. Require features such as: language translations, multi-factor authentication, and field validators. You require a custom flow - For example, You are building a streaming service and would like to limit the number of active sessions for a user, or maybe you need to verify a user’s email before a user enters their password during sign-up. So what third-party options are available that offer the flexibility you need and, are easy to use? We have a that compares some of the most popular solutions out there, but today we are looking at SuperTokens, how it can adapt to accommodate your custom requirements and why it pairs so well with Supabase. blog What is SuperTokens? SuperTokens is an Open Source Authentication solution. We have a managed service, but if you prefer to handle your own data, you can use our self-hosted solution. We built SuperTokens from the ground up to be easy to use and customizable. Note: SuperTokens requires you to have an api layer. If your app does not require a discrete api layer, Supabase auth is a more viable option. What does SuperTokens offer? All popular sign up methods such as passwordless (with email or SMS), email and password, social login. A Pre-built UI that is hosted on your domain itself. SDKs that will handle automatically create and manage user’s session tokens (access & refresh tokens). Hosted and self hosted options that enable you to manage your own data. 2FA, user roles, SAML and more on the way! The ability to easily customize the end-user experience or the backend auth logic within your API layer: This is what makes SuperTokens really powerful. You can learn more about SuperTokens architecture and how customizations work from our . guide Examples of some customizations you can make with SuperTokens: Here is a list of possible use cases and how SuperTokens can help you achieve them. : If your app requires users to sign up with their work-related emails or Google workspace-associated domains, you can use the SuperTokens email validator functions to enforce the check. Restrict signups to work emails : Collect user’s name and age on the Sign Up or Sign In pages. Collect more information on signup : Don’t like the default email and SMS templates? Create your own email and SMS content! You can also choose your own delivery method if you don’t want to use the default service. Use your own SMS / email sending service : SuperTokens allows you to migrate users from other auth providers to SuperTokens and preserve the users’ original userId. This allows you to continue to use any data you had mapped to the previous provider’s userId. Migration Example apps with custom flows Here are some examples of custom flows we’ve already built: Verify a users email before they enter their password during Sign Up Say you have a custom requirement where you want to verify a user’s ownership of an email before they type in a password during sign-up. Example app with . email verification before entering the password during sign up Email Verification with OTP Instead of having the user click a link during email verification, maybe you would like them to enter an OTP. Example app with . email verification with OTP Login with Phone number Password In this flow, users create an account using their phone number and password. Example app with . phone number and password login These are just some of the use cases that SuperTokens supports. If you have a custom requirement, feel free to join our . We are passionate about Auth and would love to discuss your use case. discord Integrating SuperTokens into Supabase We provide a on how to secure you Supabase app with SuperTokens. The guide details the process of leveraging Supabase’s Row Level Security feature to create powerful authorization policies so only authorized users can access data. guide Conclusion In the end, the authentication solution you choose depends on your use case. For apps where you need to quickly setup simple authentication flows, Supabase Auth is a great choice. For startups or mid-level organisations looking for an open-source authentication solution that can grow with their organisation, SuperTokens is a great choice. Written by the Folks at — hope you enjoyed! We are always available on our Discord server. Join us if you have any questions or need any help. SuperTokens

Protecting Your Supabase App With SuperTokens Authentication

Using SuperTokens in a VueJS App With Your Own UI

Uso de SuperTokens en una aplicación VueJS con su propia interfaz de usuario

Building your own auth service can be tedious, complex and time-consuming. To save time, developers often resort to using third party auth services for auth. This post will guide you on how to add authentication to a VueJS app with SuperTokens. What is SuperTokens? is an open source project which enables you to add auth to your app quickly. It gives you a pre-built auth UI and backend APIs for an end-to-end integration experience. SuperTokens Before we dive into the code, let’s discuss the overall architecture. Architecture SuperTokens is built out of three components: Frontend SDK Backend SDK Core microservice that talks to a database. We’ll use the SuperTokens frontend SDK in our Vue app to add all the auth forms (login, signup, reset password etc). You can also build your own UI using the helper functions from frontend SDKs, but we will focus on the pre-built UI in this blog. The pre-built UI are ReactJS components (provided by the ). In order to use them, we will have to render React components in our VueJS app. supertokens-auth-react library For the backend, we will use the NodeJS SDK provided by SuperTokens . This SDK exposes all of the auth APIs (like , / etc) via a middleware, for the frontend to call. When these APIs are called, the SDK will talk to the SuperTokens Core microservice to read and write information to the database. supertokens-node library /auth/signin auth/signout The SuperTokens core service can be either self-hosted (and connected to your own db), or be hosted by the team behind SuperTokens (sign up on ). supertokens.com In order to keep the app’s bundle size small, we will limit the use of the SDK to all of the auth related routes ( by default), and use a lighter weight, vanilla JS SDK ( ) for all other routes in our app. Finally, we will then use code splitting and lazy importing to make sure that the SDK is only bundled when visiting the routes. supertokens-auth-react /auth/* supertokens-web-js library supertokens-auth-react /auth/* Frontend Integration 1. Setup and Install Create a new Vue + Typescript app: npm init vue@latest In the prompt, select Typescript and Vue Router: Once that’s done, head inside the project and install the following dependencies: npm i --save cors express npm-run-all react supertokens-auth-react react-dom supertokens-node The library will be used on the frontend to render the login UI, and the library will be used on the backend to expose the auth API routes. supertokens-auth-react supertokens-node 2. Call the and function supertokens-auth-react supertokens-web-js init Start by create the component inside folder. This component will render the SuperTokens React component to handle authentication on the frontend: AuthView /src/views <script lang="ts">
    export default {
        // See next sections
    }
</script>

<template>
    <main>
        <div id="authId" />
    </main>
</template> Notice that we have made a element with the . This is where we will render the react components provided by SuperTokens. <div> id="authId" Next, let’s create a file - which is the actual React component that we will be rendering. Inside this file, we will initialize the SDK and use it in the React function. /src/components/Supertokens.tsx supertokens-auth-react render import * as React from "react";
import * as SuperTokens from "supertokens-auth-react";
import * as ThirdPartyEmailPassword from "supertokens-auth-react/recipe/thirdpartyemailpassword";
import { Github, Google } from "supertokens-auth-react/recipe/thirdpartyemailpassword";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
   appInfo: {
       appName: "SuperTokens Demo App",
       apiDomain: "http://localhost:3001",
       websiteDomain: "http://localhost:4200",
   },
   recipeList: [
       ThirdPartyEmailPassword.init({
           signInAndUpFeature: {
               providers: [Github.init(), Google.init()],
           }
       }),
       Session.init(),
   ],
});

class SuperTokensReactComponent extends React.Component {
   override render() {
       if (SuperTokens.canHandleRoute()) {
           return SuperTokens.getRoutingComponent();
       }
       return "Route not found";
   }
}

export default SuperTokensReactComponent; The snippet above uses the recipe (social + email / password login). You can choose another recipe as well by following the quick setup section in the . ThirdPartyEmailPassword guides on supertokens.com Next, we will load this inside the component: SuperTokensReactComponent AuthView <script lang="ts">
import * as React from "react";
import * as ReactDOM from "react-dom";
import SuperTokensReactComponent from "../components/Supertokens";

export default{
    mounted(){
        ReactDOM.render(React.createElement(SuperTokensReactComponent),
            document.getElementById('authId'));
    }
    beforeDestroy(){
        ReactDOM.unmountComponentAtNode(document.getElementById('authId') as Element);
    }
}
</script> The above takes care of the related routes. For all the other pages in our app, we want to be able to know if a session exists and extract information from it. To do this, we will use the SDK. We initialize this SDK in our Vue app’s root file / : /auth/* supertokens-web-js src/main.ts import Vue from "vue";
import VueCompositionAPI, { createApp, h } from "@vue/composition-api";
import * as SuperTokens from "supertokens-web-js";
import * as Session from "supertokens-web-js/recipe/session";

import App from "./App.vue";
import router from "./router";

SuperTokens.init({
    appInfo: {
        appName: "SuperTokens Demo",
        apiDomain: "http://localhost:3001",
    },
    recipeList: [Session.init()],
});

Vue.use(VueCompositionAPI);

const app = createApp({
    router,
    render: () => h(App),
});

app.mount("#app"); The config for the call, the and the for both the functions ( and ) should always be the same. Session.init apiDomain appName init supertokens-auth-react supertokens-web-js 3.  Setup Routing to show the Login UI Vue CLI already generates the initial routing for our app inside / . We’ll update this file so that all routes load the component we created earlier: src/router.index.ts /auth/* AuthView import Vue from 'vue'
import VueRouter from 'vue-router'
import HomeView from '../views/HomeView.vue'

Vue.use(VueRouter)

const router = new VueRouter({
    mode: 'history',
    base: import.meta.env.BASE_URL,
    routes: [{
        path:'/auth*',
        name:'auth',
        component: () => import('../views/AuthView.vue'),
    }]
})

export default router The path for the component is . The * indicates that any sub / nested paths with /auth as the parent path should be rendered by the component. The component will in turn render the ReactJS component we created earlier which will use the SDK to show the auth UI. AuthView /auth* AuthView AuthView supertokens-auth-react We lazy load the route because the component loads ReactJS as a dependency. Lazy loading makes sure that these dependencies are only injected in the component when you visit the routes. For all of the other routes, these dependencies are not imported thereby maintaining the overall bundle size of the application. /auth AuthView AuthView /auth/* 4. View the Login UI If you now visit , you should see the login UI as shown below: http://localhost:4200/auth Backend Integration You can see the backend quick setup section in our , or even copy the code from . As a summary: docs on supertokens.com our example app You need to initialize the SDK and provide it the (similar to how you did on the frontend). supertokens-node recipeList Then you need to setup , add the SuperTokens and to your app. The SuperTokens exposes all the auth related API routes (like sign in, sign up, sign out etc) to the frontend. CORS middleware errorHandler middleware Finally, you need to provide the (location) of the SuperTokens core. To get started quickly, you can provide it (this is a core that we host for demo purposes). connectionURI https://try.supertokens.com Once you’ve successfully setup your server, you can now try and sign up on the frontend. Session management Inside file we’ll check if the user is authenticated and conditionally render a template. For authenticated users, we can show them a logout button with information about their session (like their ). For unauthenticated users, we can show them a button to route to the page. /src/views/HomeView.vue userId /auth <script lang="ts">
import * as Session from "supertokens-web-js/recipe/session";
export default {
    data() {
        return {
            session: false,
            userId: "",
        };
    },
    mounted() {
        this.getUserInfo();
    },
    methods: {
        redirectToLogin() {
            window.location.href = "/auth";
        },
        async getUserInfo() {
            this.session = await Session.doesSessionExist();
            if (this.session) {
                this.userId = await Session.getUserId();
            }
        },
        async onLogout() {
            await Session.signOut();
            window.location.reload();
        },
    },
};
</script>

<template>
    <main>
        <div class="body">
            <h1>Hello</h1>

            <div v-if="session">
                <span>UserId:</span>
                <h3>{{ userId }}</h3>

                <button @click="onLogout">Sign Out</button>
            </div>
            <div v-else>
                <p>
                    Visit the <a href="https://supertokens.com">SuperTokens tutorial</a> to learn how to build Auth
                    under a day.
                </p>
                <button @click="redirectToLogin">Sign in</button>
            </div>
        </div>
    </main>
</template> To load the component on / we’ll update the file: HomeView /src/router/index.ts const router = new VueRouter({
    // ...
    routes: [{
        path: "/",
        name: "home",
        component: HomeView,
    }, /*...*/],
}); If you now visit , you should see the following page: http://localhost:4200 SuperTokens Core Setup Whilst doing the backend setup, we are using as the for the core. This is a demo core instance hosted by the team of SuperTokens. You can use this for as long as you like, but when you are committed to using SuperTokens, you should switch to a or a of the core. https://try.supertokens.com connectionURI self hosted managed version Conclusion To summarize, we used the ReactJS SDK provided by SuperTokens to show the pre-built login UI for our Vue app. We also optimized the bundle size so that the ReactJS SDK is only loaded for auth related routes. Useful links: Example Vue app Discord community (to ask questions) List of recipes / auth methods Written by the Folks at — hope you enjoyed! We are always available on our . Join us if you have any questions or need any help. SuperTokens Discord server

How SuperTokens' Pre Built UI Can Be Used With VueJS

Need authentication but not sure who to go with? Read on for an in-depth comparison of the leading authentication providers. Introduction Solutions that authenticate and manage users’ access to a system have never been more important. In today’s post, we will be looking at some of the leading Authentication providers, breaking down their features and pricing so you can decide if they fit your requirements. Auth0 and Okta Auth0 Auth0 is an authentication and authorization software as a service platform. It started in 2013 as an identity management service to allow developers to easily connect their apps to enterprise and social providers. Over the years they have scaled their services, achieved compliance certifications, and added more features. Today they are one of the leading Auth providers in the space. Okta Okta is another leader in the authentication and authorization space, but, with a focus on workforce identity and integration with other enterprise services. On May 3, 2021, Okta announced they had acquired Auth0 for $6.5B. This brought a lot of attention to Auth0. Okta is notorious for being a sales-focused company and many speculate that this practice will trickle down to Auth0. You can learn more about what that means for the market . here So what is the difference between Auth0 and Okta? As mentioned previously Okta’s main focus is workforce identity. Although they do offer customer identity solutions, pricing for these plans is billed annually and it can be . After the Auth0 acquisition, Okta now encourages developers who are looking for more affordable auth solutions to use Auth0 extremely expensive Advantages of using Auth0 Simple Setup: Setting up authentication in your app with Auth0 is simple. The docs are well written, accessible, and also provide demo apps. SDK and Integration support: They support over and , meaning if you have a use case, Auth0 will probably have an SDK to support that framework and integration to support that service. 60 SDKs 50 integrations Feature set: Auth0’s wide breadth of features is one of its largest selling points. Whether you are an indie developer looking for email-password login for your side project or a massive enterprise that requires enterprise connections and MFA Auth0 will have you covered. Disadvantages of using Auth0 Expensive One of the biggest reasons people switch away from Auth0 is how expensive their pricing can get. To give some context Auth0’s free plan allows for up to and up to two social connections. This is fine for small projects but as your business starts to scale, Auth0’s pricing starts to scale much faster. For example, if you have around and have enterprise connections enabled you can expect to pay around . 7000 MAUs 7000 MAUs $1800/month If you need to migrate your users, you would need to have an enterprise plan to export your user’s password hashes. Opaque Pricing: After , Auth0’s pricing for plans becomes completely custom. This makes it hard for developers who are evaluating Auth0 to know how much they would have to pay once their product scales past the boundaries of the base plans. 10000 MAUs Extensibility: Auth0’s rules, hooks, and actions all provide ways for extending and customizing Auth0s service but you are limited by the number of flows they allow you to customize. Auth0’s extensibility options don’t allow you to change the logic of a flow. To use this feature you have to add your code to their dashboard. This makes maintaining the code a hassle. Auth0 Pricing: Free Plan Auth0’s free plan allows having up to and up to 2 social connections and 3 Actions, Rules, and hooks. 7000 MAUs Paid Plans Auth0 splits its paid plans into two sections based on your use case, with each use case having a free, professional, and enterprise tier. In both cases, the enterprise tier has fully custom pricing and you need to talk to their support team. Use Case 1: Business to Consumer The essential plan allows for up to , unlimited social login, custom domains, and user role management. 10,000 MAUs The professional plan adds multifactor authentication, the ability to connect your own database, and additional action, rules, and hooks Use Case 2: Business to Business The essential plan offers enterprise connections, multi-factor authentication, user role management, and organisations. The professional plan allows you to connect your own database and increases the number of organisations and the actions, hooks, and roles. So is Auth0 the way to go? Auth0 has all the functionality you need and is easy to set up and integrate with, but their pricing doesn’t scale well and it can become very expensive as your userbase grows and you require more features. Amazon Cognito Cognito is a service that provides authentication, authorization, and user management for web and mobile apps. It is part of the AWS suite of products and can be used easily with any of their other offerings such as Lambda. Cognito supports multiple compliance programs and can scale to millions of users. It has grown in popularity due to its accessible pricing. Advantages of using Cognito Pricing: One reason why so many people use Cognito is its price. It offers its basic authentication flow for free for the first and it is $0.0055 per MAU after that. 50000 MAUs Integration with other AWS services: Cognito’s tight integration with other AWS services such as API Gateway, AppSync, and ALB removes a whole layer of custom code you’d have to write if you use AWS’s services. Disadvantages of using Cognito Developer Experience: Cognito’s documentation can vary in quality with some features not being documented at all. This can make working with the product very confusing and frustrating. Cognito is also not just a user management system but a single service with 3 distinct features. These are User Pools, Identity Pools, and Sync. This can be very confusing for newcomers. There have also been complaints about Cognito being slow to respond to bugs and feedback. For example, was breaking the flow for many users and was open for 4 years before it was resolved with the help of a community member. this issue Features: Cognito’s core feature set is limited and it relies on other services in AWS’s stack to make up for this gap. This results in the user having to deal with AWS services when they require more advanced features. UI Customization: Cognito’s built-in UI offers basic branding and colour customization through their dashboard. If you need a more custom design you will need to create your own UI. Migration: Cognito does not allow you to export user password hashes. This can make migration to another database or service much harder. AWS Cognito Pricing Cognito’s free tier offers up to for free. Included are the Identity pool features which cover access control and RBAC. 50,000 MAUs Free: User pools free for up to 50000 MAUs for SAML / OIDC 50 MAUs identity pools (Access control, RBAC, etc) Paid Features: Cognito offers pricing tiers for additional MAUs and users with SAML/OIDC connections. They also offer advanced security features like compromised credential protection, risk-based adaptive authentication, and monitoring. Pricing tiers for additional MAUs: Additional SAML/OIDC users: per MAU after the first in the free tier $0.015 50 Pricing tiers for advanced security features : SMS charges for multi-factor: Inbound charges: Outbound charges: So is Cognito the way to go? Cognito’s free tier and integration with other AWS services position it as a great auth provider, but it does not provide the best developer experience. Users have complained about the documentation being confusing at times, making it hard to integrate with. SuperTokens SuperTokens is an open-source authentication solution that provides a managed service for hassle-free auth and an on-prem solution so developers can manage their data. Starting as a session management solution in 2019, SuperTokens has evolved into a complete auth solution providing email-password, social and passwordless login with extensive customization options to curate the login experience to your needs. SuperTokens differentiates itself from its competitors with its flexibility. If you don’t want to deal with handling user data you can use the managed service or, you can self-host the solution for free and control 100% of the data with your database. There are also no restrictions on completely customising the auth flow with their feature. override Advantages of using SuperTokens: Completely Open Source: All of SuperTokens SDKs including the core service are open source. This allows developers to poke around the code for vulnerabilities and contribute to features. Simple Setup: SuperTokens modular architecture makes the setup simple. It allows the developer to pick and choose what functionality they want and only see documentation relevant to their use case. Pre-built Auth UI that can be embedded in your website natively Support over . Discord Flexibility: As mentioned previously Supertokens has a managed service with reasonable pricing as well as a completely free self-hosted version. SuperTokens provides an override feature that enables you to fully customise authentication flows on both your frontend and backend. SuperTokens also provides pre-built UI components that can be rendered directly on your frontend Disadvantages of using SuperTokens: Enterprise features: At the time of writing this post, SuperTokens doesn’t offer some enterprise features like SCIM provisioning, admin, and organization support. Tech Stack Support As of writing this article SuperTokens supports , and on the backend with , and on the frontend. They currently do not support many popular languages like and and they do not have pre-built UI for popular frontend frameworks like and . Nodejs Golang Python Reactjs(All Features) VanillaJS(only session management) React Native(only session management) Java Php Angular Vue SuperTokens Pricing: At the time of writing this article, the SuperTokens feature set is completely free. If you decide to use the self-hosted version you can download the core and use it for free for an unlimited amount of users. Self-Hosted: Free forever for unlimited users. Managed Service: Free for the first . 5000 MAUs for every beyond the free limit of up to . $29/month 5000 MAUs 50000 MAUs Custom pricing beyond 50000 MAUs So is SuperTokens the way to go? SuperToken’s feature set and pricing make it a great choice for startups and mid-level businesses, but it may not be the best fit for large organisations that require enterprise features. Conclusion So what authentication provider do you go with? Well in the end it depends on your use case. If your costs can scale with Auth0’s pricing and you don’t need to customise their flows too much, then Auth0 is the way to go. AWS Cognito’s generous free tier and tight integration with other AWS services make it a great option if you can deal with sub-par documentation and support. If you are a startup or mid-level organisation looking for an open-source solution that can grow with your organisation, with extensive customization options and the ability to self-host or use a managed service, SuperTokens is a clear choice. Written by the Folks at — hope you enjoyed it! We are always available on our . SuperTokens Discord server Also Published here

Auth0 vs Okta vs Cognito vs SuperTokens Compared (2022)

This blog will take you through connecting the SuperTokens core service with a MySQL or a PostgreSQL database with and without Docker. This is only applicable if you are self-hosting the SuperTokens core service. There are several methods for how you might want to run SuperTokens along with a database. In this blog, we will cover: Running with MySQL: a) Running SuperTokens and MySQL without docker b) Running SuperTokens with Docker and MySQL without docker c) Running SuperTokens without Docker and MySQL with docker d) Running SuperTokens and MySQL with docker, but without docker-compose e) Running SuperTokens and MySQL with docker, with docker-compose Running with PostgreSQL: a) Running SuperTokens and PostgreSQL without docker b) Running SuperTokens with Docker and PostgreSQL without docker c) Running SuperTokens without Docker and PostgreSQL with docker d) Running SuperTokens and PostgreSQL with docker, but without docker-compose e) Running SuperTokens and PostgreSQL with docker, with docker-compose Please feel free to navigate to the correct section based on your setup. In each section, we will be linking to the SuperTokens documentation wherever applicable so that this blog is not very lengthy. All the sections below assume that you will be using a Linux based operating system. For Windows, the syntax for some of the steps might be different, but the overall steps that need to be performed will be the same. 1a) Running SuperTokens and MySQL without docker Install SuperTokens on your local machine by following the . self-hosted, without docker, instructions in the SuperTokens’ documentation Connect to the MySQL server on your local machine and create a database for SuperTokens to write to: create database supertokens; If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step. Create a MySQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables: CREATE USER 'supertokens_user'@'localhost' IDENTIFIED BY 'somePassword'; GRANT ALL ON supertokens.* TO 'supertokens_user'@'localhost'; FLUSH PRIVILEGES; Notice that we only allow this user to work via . This would only work if the SuperTokens core is running locally as well. If you are running the core in a different location, then you would need to replace in the above with . 'localhost' 'localhost' '%' Edit the SuperTokens file (located in ) to add the following config: config.yaml /usr/lib/supertokens/config.yaml mysql_connection_uri: "mysql://supertokens_user:[email protected]:3306/supertokens" Make sure that you put in the right values for the user, password, database name and location of your MySQL instance in the above connection uri string. Run SuperTokens by running on your terminal: supertokens start supertokens start

Loading storage layer.
Loading MySQL config.
...
Started SuperTokens on localhost:3567 with PID: ... Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 1b) Running SuperTokens with Docker and MySQL without docker For this setup to work, we must connect SuperTokens and MySQL via the host machine’s network. For this, we will have to expose the MySQL db to the local IP. Start by pulling the SuperTokens docker image that is compatible with MySQL: docker pull registry.supertokens.io/supertokens/supertokens-mysql Expose MySQL server to all network interfaces on your machine. To do this, edit the file (MySQL config file) to include: my.cnf bind-address = 0.0.0.0 Be sure to restart your MySQL server after saving the file. Connect to the MySQL server on your local machine and create a database for SuperTokens to write to: create database supertokens; If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step. Create a MySQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables: REATE USER 'supertokens_user'@'%' IDENTIFIED BY 'somePassword'; GRANT ALL ON supertokens.* TO 'supertokens_user'@'%'; FLUSH PRIVILEGES; Run the SuperTokens docker image with the env var specifying the MySQL connection URI: docker run \
  -p 3567:3567 \
  --network=host \
  -e MYSQL_CONNECTION_URI="mysql://supertokens_user:[email protected]:3306/supertokens" \
  -d registry.supertokens.io/supertokens/supertokens-mysql Be sure to replace with the correct IP of your system. 192.168.1.1 This will start the docker image in the background. You can find it by running: docker ps If you want to run it in the foreground, you can remove the option from the command. -d docker run Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 1c) Running SuperTokens without Docker and MySQL with docker Install SuperTokens on your local machine by following the . self-hosted, without docker, instructions in the SuperTokens’ documentation Start the MySQL docker container: docker run \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_USER=supertokens_user \
  -e MYSQL_PASSWORD=somePassword \
  -e MYSQL_DATABASE=supertokens \
  --network=host \
  -p 3306:3306 \
  -d mysql The above will start the mysql db with a new database called . SuperTokens core will store the data in this database. If you want the data to be stored in an existing db, please provide that db’s name instead. supertokens Edit the SuperTokens file (located in ) to add the following config: config.yaml /usr/lib/supertokens/config.yaml mysql_connection_uri: "mysql://supertokens_user:[email protected]:3306/supertokens" Make sure that you put in the right values for the user, password, database name and location of your MySQL instance in the above connection uri string. Run SuperTokens by running on your terminal: supertokens start supertokens start

Loading storage layer.
Loading MySQL config.
...
Started SuperTokens on localhost:3567 with PID: ... Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 1d) Running SuperTokens and MySQL with docker, but without docker-compose Start by pulling the SuperTokens docker image that is compatible with MySQL: docker pull registry.supertokens.io/supertokens/supertokens-mysql Start the MySQL docker container: docker run \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_USER=supertokens_user \
  -e MYSQL_PASSWORD=somePassword \
  -e MYSQL_DATABASE=supertokens \
  --network=host \
  -p 3306:3306 \
  -d mysql The above will start the mysql db with a new database called . SuperTokens core will store the data in this database. If you want the data to be stored in an existing db, please provide that db’s name instead. supertokens Run the SuperTokens docker image with the env var specifying the MySQL connection URI: docker run \
  -p 3567:3567 \
  --network=host \
  -e MYSQL_CONNECTION_URI="mysql://supertokens_user:[email protected]:3306/supertokens" \
  -d registry.supertokens.io/supertokens/supertokens-mysql Be sure to replace with the correct IP of your system. 192.168.1.1 This will start the docker image in the background. You can find it by running: docker ps If you want to run it in the foreground, you can remove the option from the command. -d docker run Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 1e) Running SuperTokens and MySQL with docker, with docker-compose Use the following docker compose file. You can call it docker-compose.yaml version: '3'

services:
  db:
    image: mysql:latest
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_USER: supertokens_user
      MYSQL_PASSWORD: somePassword
      MYSQL_DATABASE: supertokens
    ports:
      - 3306:3306
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
      timeout: 20s
      retries: 10

  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-mysql
    depends_on:
      - db
    ports:
      - 3567:3567
    environment:
      MYSQL_CONNECTION_URI: mysql://supertokens_user:[email protected]:3306/supertokens
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: >
        bash -c 'exec 3<>/dev/tcp/127.0.0.1/3567 && echo -e "GET /hello HTTP/1.1\r\nhost: 127.0.0.1:3567\r\nConnection: close\r\n\r\n" >&3 && cat <&3 | grep "Hello"'
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  app_network:
    driver: bridge You can run the following command to start the service: docker-compose up Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 2a) Running SuperTokens and PostgreSQL without docker Install SuperTokens on your local machine by following the . self-hosted, without docker, instructions in the SuperTokens’ documentation Connect to the PostgreSQL server on your local machine and create a database for SuperTokens to write to: CREATE DATABASE supertokens; If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step. Create a PostgreSQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables: CREATE USER supertokens_user WITH ENCRYPTED PASSWORD 'somePassword'; GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user; Edit the SuperTokens file (located in ) to add the following config: config.yaml /usr/lib/supertokens/config.yaml postgresql_connection_uri: "postgresql://supertokens_user:[email protected]:5432/supertokens" Make sure that you put in the right values for the user, password, database name and location of your postgreSQL instance in the above connection uri string. Run SuperTokens by running supertokens start on your terminal: supertokens start

Loading storage layer.
Loading PostgreSQL config.
...
Started SuperTokens on localhost:3567 with PID: ... Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 2b) Running SuperTokens with Docker and PostgreSQL without docker For this setup to work, we must connect SuperTokens and PostgreSQL via the host machine’s network. For this, we will have to allow PostgreSQL to allow incomming client connections over the network. Start by pulling the SuperTokens docker image that is compatible with PostgreSQL: docker pull registry.supertokens.io/supertokens/supertokens-postgresql Allow incoming client connections to your PostgreSQL database over your network by adding the following lines to the and file. postgresql.conf pg_hba.conf postgresql.conf listen_addresses = '0.0.0.0' pg_hba.conf host all all 0.0.0.0/0 md5 Connect to the PostgreSQL server on your local machine and create a database for SuperTokens to write to: CREATE DATABASE supertokens; If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step. Create a PostgreSQL user with full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables: CREATE USER supertokens_user with encrypted password 'somePassword'; GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user; Run the SuperTokens docker image with the env var specifying the PostgreSQL connection URI: docker run \              
  -p 3567:3567 \
  --network=host \
  -e POSTGRESQL_CONNECTION_URI="postgresql://supertokens_user:[email protected]:5432/supertokens" \
  -d registry.supertokens.io/supertokens/supertokens-postgresql Be sure to replace with the correct IP of your system. 192.168.1.1 This will start the docker image in the background. You can find it by running: docker ps If you want to run it in the foreground, you can remove the option from the command. -d docker run Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 2c) Running SuperTokens without Docker and PostgreSQL with docker Install SuperTokens on your local machine by following the . self-hosted, without docker, instructions in the SuperTokens’ documentation Start the PostgreSQL docker container: docker run \
  -e POSTGRES_USER=root \
  -e POSTGRES_PASSWORD=root \
  --network=host \
  -p 5432:5432 \
  -d postgres \
  -c listen_addresses=0.0.0.0 The above will start the PostgreSQL db. You will need to connect to the database and create a user with the privileges. CREATE DATABASE supertokens; If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step. Create a PostgreSQL user with full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables: CREATE USER supertokens_user with encrypted password 'somePassword'; GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user; Edit the SuperTokens file (located in ) to add the following config: config.yaml /usr/lib/supertokens/config.yaml postgresql_connection_uri: "postgresql://supertokens_user:[email protected]:5432/supertokens" Make sure that you put in the right values for the user, password, database name and location of your PostgreSQL instance in the above connection uri string. Run SuperTokens by running on your terminal: supertokens start supertokens start

Loading storage layer.
Loading PostgreSQL config.
...
Started SuperTokens on localhost:3567 with PID: ... Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 2d) Running SuperTokens and PostgreSQL with docker, but without docker-compose Start by pulling the SuperTokens docker image that is compatible with PostgreSQL: docker pull registry.supertokens.io/supertokens/supertokens-postgresql Start the PostgreSQL docker container: docker run \
  -e POSTGRES_USER=root \
  -e POSTGRES_PASSWORD=root \
  --network=host \
  -p 5432:5432 \
  -d postgres \
  -c listen_addresses=0.0.0.0 The above will start the PostgreSQL db. You will need to connect to the database and create a user with the privileges. CREATE DATABASE supertokens; If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step. Create a PostgreSQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables: CREATE USER supertokens_user with encrypted password 'somePassword'; GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user; Run the SuperTokens docker image with the env var specifying the PostgreSQL connection URI: docker run \              
  -p 3567:3567 \
  --network=host \
  -e POSTGRESQL_CONNECTION_URI="postgresql://supertokens_user:[email protected]:5432/supertokens" \
  -d registry.supertokens.io/supertokens/supertokens-postgresql Be sure to replace with the correct IP of your system. 192.168.1.1 This will start the docker image in the background. You can find it by running: docker ps If you want to run it in the foreground, you can remove the option from the command. -d docker run Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello 2e) Running SuperTokens and PostgreSQL with docker, with docker-compose Use the following docker compose file. You can call it docker-compose.yaml version: '3'

services:
  db:
    image: 'postgres:latest'
    environment:
      POSTGRES_USER: supertokens_user 
      POSTGRES_PASSWORD: somePassword 
      POSTGRES_DB: supertokens
    ports:
      - 5432:5432
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'pg_isready -U supertokens_user']
      interval: 5s
      timeout: 5s
      retries: 5

  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-postgresql
    depends_on:
      - db
    ports:
      - 3567:3567
    environment:
      POSTGRESQL_CONNECTION_URI: "postgresql://supertokens_user:[email protected]:5432/supertokens"
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: >
        bash -c 'exec 3<>/dev/tcp/127.0.0.1/3567 && echo -e "GET /hello HTTP/1.1\r\nhost: 127.0.0.1:3567\r\nConnection: close\r\n\r\n" >&3 && cat <&3 | grep "Hello"'
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  app_network:
    driver: bridge You can run the following command to start the service: docker-compose up Verify that it is setup correctly by querying the core service: curl http://localhost:3567/hello If you get back a reply, the core setup is done! Hello Written by the Folks at — hope you enjoyed! We are always available on our . SuperTokens Discord server

How to connect SuperTokens to a MySQL or to a PostgreSQL database

In this tutorial, you’ll learn how to add SuperTokens authentication to your React and NodeJS application and deploy it on Vercel. Getting started To get started with SuperTokens, please visit the and pick the login method you want for your application. After choosing a guide, follow the quick setup section or one of the sections for integrating with a framework that you have chosen. Recipe Guides page We also have a blog post on how to integrate , if that is what you are looking for. email password + social login with express and react Restructuring your application for Vercel deployment Once you have done the basic implementation on your local system, we want to do the following to convert your application so that it can be deployed on Vercel: Create an folder. This folder will contain the API logic that we can deploy on Vercel. We will be exposing the API's entry point via an file in this folder. api index.js Open the and export at the end of the file as shown below index.js app module.exports = app; Note: We are deploying our backend as a standalone express app, and not with serverless functions that Vercel provides. If you want to deploy using , then you can check out our nextJS framework integration guide that's within the recipe guide. /pages/api /pages/api Change the appInfo config to get Vercel deployments to work To enable your project to run on production and the inspect sites for Vercel, you need to make the and point to the URLs generated by Vercel. The production URL is always the same for an app, but the inspect URL keeps changing. To allow it to work in this dynamic condition, we must set the values of and dynamically. websiteDomain appDomain apiDomain websiteDomain On the backend appInfo = {
    appName: "My App",
    apiDomain: process.env.VERCEL_URL,
    websiteDomain: process.env.VERCEL_URL,
    apiBasePath: "/api/auth",
    websiteBasePath: "/auth",
}, Vercel provides an env var - - to the backend which is equal to the inspect URL / production URL (depending on the site that’s loaded). So we use this to set the and values dynamically. process.env.VERCEL_URL apiDomain websiteDomain On the frontend We can use it to get the currently loaded URL and set those to the and . This way, even if the inspect URL keeps on changing, it will still point to the current domain. window.location.origin apiDomain websiteDomain appInfo = {
    appName: "TodoApp",
    apiDomain: window.location.origin,
    websiteDomain: window.location.origin,
    apiBasePath: "/api/auth",
    websiteBasePath: "/auth",      
}, This only works if the frontend and backend of your application have the same domain. If your backend is hosted elsewhere and you use Vercel only for the frontend, be sure to change the on the frontend and backend to point to your backend server. In this case however, your app may not function properly for inspect deployments since your backend server has no way of knowing what the inspect URL of the frontend site would be on each deployment. apiDomain Update the CORS Middleware You also need to update the CORS middleware origin with the environment variable. VERCEL_URL app.use(
    cors({
        origin: process.env.VERCEL_URL,
        allowedHeaders: ['content-type', ...SuperTokens.getAllCORSHeaders()],credentials: true,
    })
); Configure Vercel and Deploy With the backend and frontend of your application code updated, create a file in the root directory of your application which will instruct Vercel to push all traffic on path to our express backend server: vercel.json /api/* {
    "rewrites": [{ "source": "/api/(.*)", "destination": "/api" }]
} Finally, to deploy the app to Vercel, you need to run the Vercel command on the root of your project: vercel Once deployed, you should be able to test the login functionality on the inspect URL and the production URL. Demo app We also have that has Email Password login with express and React, and is configured to work with Vercel. You can even see its . a demo app on our GitHub live preview Written by the Folks at — hope you enjoyed! We are always available on our server. Join us if you have any questions or need any help. SuperTokens Discord

Deploying SuperTokens with React and NodeJS on Vercel

This tutorial walks you through integrating your frontend with social login APIs provided by SuperTokens. Note, that it’s only meant for users who are building their own frontend and are building a website. If you are using our pre-built UI, these API integrations are already done for you. To start off, you want to make sure that you have finished the frontend and backend quick setup guides for that you have chosen. the recipe As of this writing, that’s either: (only social login) ThirdParty recipe (social + email password login) ThirdPartyEmailPassword recipe After finishing the quick setup guides, you should have: Session feature setup on the frontend All social auth + sessions-related APIs are exposed via your backend API (as per ). this API spec Now we can see how to integrate your frontend UI to work with the backend social auth APIs exposed by SuperTokens. For ease of explanation, we will assume the following: We want to implement sign in with GitHub Your website domain is http://localhost:3000 Your API domain is You have chosen the default and in both cases) api base path website base path (/auth You want to implement the thirdpartyemailpassword recipe. The authorization redirect URL set on the github dashboard is http://localhost:3000/auth/callback/github The authorization redirect URL set on the github dashboard is http://localhost:3000/auth/callback/github On a high level, there are two steps to the flow: When the user clicks on the Sign in with GitHub button, you want to fetch the GitHub redirect URL and redirect the user to that page. This is where the user will interact with GitHub to enter their credentials. When GitHub redirects the user back to your app, you want to use the (one time use) auth code issues by Github to sign in / sign up the user. Step 1 When the user clicks on Sign in with GitHub button, you want to make the following API call: const response = await fetch(“http://localhost:3001/auth/authorisationurl?thirdPartyId=github”, 
    {
        method: 'GET',
        headers: {
            rid: “thirdpartyemailpassword”
        }
    }
); A successful response will look something like: {
    "status": "OK",
    "url": "https://github.com/login/oauth/authorize?
scope=read%3Auser+user%3Aemail&
client_id=21d82062d1f35b68e66c"
} A couple of pointers: As stated previously, we assume that your API is on and the api base path is . Therefore, the resulting API URL is http://localhost:3001 /auth http://localhost:3001/auth/authorisationurl. As stated previously, we assume that your API is on and the api base path is . Therefore, the resulting API URL is http://localhost:3001 /auth http://localhost:3001/auth/authorisationurl. This API takes one query param which is the field. Since we are implementing logic with GitHub, the value of this is github. If we were implementing login with Google, the value of this would be google. thirdPartyId The header contains a special rid field whose value is . This helps the backend SDK know which recipe to send this request to. If you are implementing the recipe, the value of this header should be thirdpartyemailpassword thirdparty third-party. The response is where the user is supposed to be redirected to. The URL contains the scopes and the github client ID you configured on the backend when following . the quick setup > backend guide The URL returned in the response is where you will redirect your user to. Before doing that though, you will need to append a query param called to this url whose value should be the callback URL you configured on the GitHub dashboard. We assume that this URL is redirect_uri http://localhost:3000/auth/callback/github. let urlObj = new URL(response.url)

urlObj.searchParams.append("redirect_uri", "http://localhost:3000/auth/callback/github");

let url = urlObj.toString(); The value of url after the above operation will be: https://github.com/login/oauth/authorize?scope=read%3Auser+user%3Aemail&client_id=21d82062d1f35b68e66c&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback%2Fgithub As you can see, we have appended the redirect_uri query param successfully. Now we can redirect the user to this URL. Step 2 When the user is navigated back to your app (from GitHub), the URL will contain a query param (on successful login), like this: code http://localhost:3000/callback/github?code=3cf143e0af0f1bed8d34 First, you need to extract this code in the following way: let code = new URL(window.location.href).searchParams.get('code'); Then, you need to call another API exposed by the SuperTokens backend SDK to complete the login operation: const response = await fetch('http://localhost:3001/auth/signinup', {
    method: 'POST',
    headers: {
        ‘rid’: “thirdpartyemailpassword”,
       'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        code,
        redirectURI: ”http://localhost:3000/callback/github”,
            thirdPartyId: “github”
    }
}); Successful execution will result in a response that looks something like: {
  "status": "OK",
  "user": {
    "id": "fa7a0841-b533-4478-95533-0fde890c3483",
    "email": "johndoe@gmail.com"
  },
  "createdNewUser": true
} A few important points: The in the request body is the same as what you had put on the GitHub dashboard. redirectURI Just like the previous API call, we add a header with the value of . rid thirdpartyemailpassword Where are the session tokens? From inspecting the response from the API call, we don’t see an access token / JWT in the body - so where are they? /signinup SuperTokens issues session cookies that get sent via the header in the response and is automatically handled by the browser. Set-Cookie Furthermore, our frontend SDK handles these session tokens for you automatically: Automatic refresh of session Automatic injection of the access token for your API calls Provides a signOut function These features are a part of the session recipe that you initialized when following the quick setup guide. Conclusion We have seen how to integrate your custom UI with the social login API exposed by SuperToken’s backend SDK. It involves calling the GET and the POST API. Furthermore, we see that on successful login, we are issued cookie-based session tokens which are handled automatically via our frontend SDK. /authorisationurl /signinup Written by the Folks at — hope you enjoyed! We are always available on our . Join us if you have any questions or need any help. SuperTokens Discord server

How to Add a Social Login to Your Website with SuperTokens (Custom UI Only)

Auth requirements are quite varied. Therefore any auth solution must provide the ability to customise their APIs. Each solution uses its own terminology for this feature: Keycloak uses “Implementing a SPI” Auth0 calls these “Auth0 actions” Firebase calls these “Extend using cloud functions” AWS Cognito uses the term “Lambda triggers & Custom challenge” SuperTokens calls this feature “Overrides” These features allow you to change the default behaviour of the auth APIs by: Creating an HTTP webhook in your API layer which is then called by the auth provider Uploading code to the auth provider (for example JS code for Auth0, or Java interface implementation for Keycloak) which run at specific points in the API’s logic. Uploading code to the auth provider which can replace the existing API’s logic entirely (as opposed to just running at specific points in the API) How powerful these solutions are, depends on: The auth provider providing the right “hook points” in their API, where your custom code can run. Your familiarity with the programming language you need to use to write the custom code. How easily your custom code can integrate with your existing infrastructure code (for example database connection setup), and how easily it can be maintained (for example, you may need to maintain the custom code snippets in your git repo as well as on the auth provider’s dashboard). In this article, we will be talking about how to customise the auth APIs provided by SuperTokens using its “Override” feature. In order to understand that, we must first understand how SuperTokens fits within an app. SuperTokens’ architecture Here we can see the architecture diagram for the self-hosted version of SuperTokens. On the left, we have the client (browser, mobile app) which talks to your APIs. Your API layer has your application APIs (shown as /api1/, /api2/, ..) and also APIs automatically exposed by the SuperTokens backend SDKs via our middleware function (shown as /auth/signin, /auth/signout, ...). The SuperTokens APIs talk to the SuperTokens Core (HTTP microservice) to persist data in the database. Your application APIs can also talk to the core if needed. Keeping this in mind, the concept of override is that you can change the behaviour of the SuperTokens APIs (exposed to the frontend) as per your requirements (all within your API layer, in the language you already use). Think of this being similar to overrides in object-oriented programming where you have an original implementation, and you can modify its behaviour by overriding the existing functions. You can even call the “super” class implementation of that function in your override function. Overriding feature in SuperTokens Whilst this article is focused on a NodeJS backend, the concepts here are very similar to all the other backend SDKs provided by SuperTokens. To override the default implementation, we must use the override config value when calling . Each recipe inside the , accepts an override config that can be used to change the behaviour of that recipe: supertokens.init recipeList supertokens.init({
   appInfo: {...},
   recipeList: [
       EmailPassword.init({
           override: {
               functions: (originalImplementation) => {
                   return originalImplementation
               },
               apis: (originalImplementation) => {
                   return originalImplementation
               }
           }
       }),
       Session.init({...})
   ]
}) In the above, we have defined the skeleton code for how to override the behaviour of the EmailPassword recipe. A very similar skeleton is applicable for overriding the Session (or any other) recipe. There are two types of override: APIs: These govern how the APIs exposed by that recipe behave. For EmailPassword, these are the sign in / sign up, reset password and email verification APIs. By overriding these, you can change how these APIs behave when they are called from the frontend. Functions: These are the functions that govern how the recipe itself behaves. They can be called by you manually in your APIs and they are also used in the APIs we expose to the frontend. By default, they query the SuperTokens core and return its response. The difference between the two are: API functions have access to the request and response objects depending on the web framework being used API functions can call several recipe functions or even call functions from multiple recipes. For example, the API function in the EmailPassword recipe, calls the recipe function from EmailPassword recipe and the function from the Session recipe. signInPOST signIn createNewSession You always want to try and use the config since that will make the minimum change to the default behaviour. If the inputs to those functions don’t suffice for your use case, then you should override the APIs. override.functions In both these types of overrides, they accept the variable as an input and the return is an object that has the same type as the . originalImplementation originalImplementaion For EmailPassword recipe, the object contains: originalImplementation For function override (see full type def ): here signIn signUp updateEmailOrPassword createResetPasswordToken resetPasswordUsingToken getUserByEmail getUserById For API override (see full type def ) here signInPOST signUpPOST emailExistsGET generatePasswordResetTokenPOST passwordResetPOST For Session recipe, the object contains: originalImplementation For function override (See full type def ) here createNewSession getAccessTokenLifeTimeMS getAllSessionHandlesForUser getRefreshTokenLifeTimeMS getSession getSessionInformation refreshSession revokeAllSessionsForUser revokeMultipleSessions revokeSession updateAccessTokenPayload updateSessionData For API override (see full type def ) here refreshPOST signOutPOST In the code snippet above, we are not modifying the default behaviour of any of these functions since we are simply returning the object. If you want to modify the function, then we can do so like this: originalImplementation signIn EmailPassword.init({
   override: {
       functions: (originalImplementation) => {
           return {
               ...originalImplementation,
               signIn: async function (input) {
                   let email = input.email;
                   let password = input.password;
 
                   // TODO: some custom logic before
 
                   let originalResponse = await originalImplementation.signIn(input);
 
                   // TODO: some custom logic after
 
                   return originalResponse;
               }
           }
       },
       apis: (originalImplementation) => {
           return {
               ...originalImplementation
           }
       }
   }
}) In the above code snippet, we have provided a custom function that uses the original implementation’s function. As marked above (in comments), we can write custom logic before or after calling the original implementation. signIn signIn TODO If we wish, we can even avoid calling the original implementation entirely and define our own logic. For example, if we wanted to use a different password hashing algorithm that is not supported by SuperTokens. Special cases for modifying APIs Sometimes, you may want to modify the default API to: Access the request object, for example, to read the origin header Send a custom reply to your frontend UI that deviates from our predefined output types Disable an API we have provided entirely. For example, you may want to do this if you do not want users to self sign up in your application. The function signature of all the API interface functions has an parameter that contains the original request and response objects. You can read from the request object and write to the response object as you normally would in your own APIs. options For example, if you want to read the request’s origin header during the sign up API, you can do it as follows: EmailPassword.init({
   override: {
       apis: (originalImplementation) => {
           return {
               ...originalImplementation,
               signUpPOST: async function (input) {
                   if (originalImplementation.signUpPOST === undefined) {
                       throw new Error("should never come here.");
                   }
 
                   let origin = input.options.req.getHeaderValue("origin");
 
                   // TODO: do something with the origin
 
                   return originalImplementation.signUpPOST(input);
               }
 
           }
       }
   }
}) As you can see above, we can access the request object using input.options.req. Likewise, if we want to send a custom response to the frontend, we can access the response object via . input.options.res Finally, to disable an API that we provide, you can set it to as follows: undefined EmailPassword.init({
   override: {
       apis: (originalImplementation) => {
           return {
               ...originalImplementation,
               signUpPOST: undefined
 
           }
       }
   }
}) This will disable the sign up API, and requests to /auth/signup will be passed along to your APIs or yield a 404. Advantages of the override method: Make modifications in the language and web framework you are already familiar with, within your own backend layer. This allows you to reuse your code for connecting to your database, sending a custom reply, logging requests and responses, sending analytics events, handling errors etc. Furthermore, since you already know the language and the web framework, the learning curve is minimal. Easier maintainability: Some auth providers require you to upload code onto their dashboard. This means you need to make sure that changes to that version of the code in your git repo are reflected on the auth provider’s dashboard (and vice versa). This can be a headache, especially with larger team sizes. With SuperTokens, all the mods you will ever need will live in the same codebase as all of your other backend code - SuperTokens is just another library you use. Flexibility in customisations: If you noticed, we don’t provide any special “hook” points (like pre-sign up or post sign up callbacks). You simply create your own implementation based on the original implementation. In fact, you can even copy the original implementation’s code and paste that in your own implementation if required. Hence, your modifications can be at any point in the API logic. In turn, this provides maximum flexibility. Flexibility in integrations: Auth APIs have to interact with several other services like those used for sending emails or SMSs, spam/anomaly detection or rate-limiting. Since the APIs are all within your own backend layer, you can use any such service(s) in the APIs we provide - you are not limited to the ones we (eventually will) support. Conclusion In the post, we saw how we can use the Overrides feature to modify the behaviour of any of the auth APIs exposed by SuperTokens. Whilst this blog focuses on NodeJS, the concept is the same in all the other SDKs we provide. Written by the Folks at — hope you enjoyed! We are always available on our . Join us if you have any questions or need any help. SuperTokens Discord server First Published here

Overriding the SuperTokens APIs for Custom Usecases

by Supertokens Team Roles-based access control (RBAC) is a security approach that uses roles to define what a user is and isn’t allowed to do. In a RBAC system, users are assigned roles with varying permissions for different resources, including files, databases, and applications. So, when a user tries to access a resource, the system will first find the roles associated with the user and then check if any of the roles have the appropriate permission. If so, the user is allowed to access the resource. If not, the user is denied access. For our example, we’ll be building a sample blogging app. First, we have a role. We’ll want to allow s to read all blog posts, but only edit or delete posts created by them. regular-user regular-user On the other hand, we create an role that allows s to create, edit, and delete all blog posts. admin admin So if a user with only the role tried to edit a blog post by another user, our system would see that the role doesn’t have the permission to edit that blog post and deny the request. regular-user regular-user RBAC vs. ABAC? Attribute-based access control (ABAC) is another approach that assigns permissions based on user attributes, resource attributes, and environment attributes. For example, a design file can be restricted to only users that have designer in their title and accessed on weekdays. While ABAC gives finer granularity over access to different resources, RBAC wins out on the ease of implementation. The initial setup cost of RBAC is magnitudes lower than ABAC. With RBAC, companies have a straightforward method for grouping users with similar access needs and then assigning permissions to those groups. With ABAC, companies must first define variables and configure different attribute-based rules, which can be a cumbersome process. Advantages of RBAC Easy to understand: Because of its intuitive structure, the underlying business logic with RBAC is simple to communicate and understand – even with dozens of different roles. : As you ship new features or change the application structure, adding or modifying roles can easily extend access to new resources for users that need them. Extendibility : Using RBAC forces developers to think about and organize application permissions and access control. This information can then be used by compliance officers during audits. Improving compliance : It becomes easy for developers to implement application security best practices around access control for their APIs, greatly reducing the chances of breaches. Decreased risk of data breaches / leakage Disadvantages of RBAC : It can be complex to make exceptions to how a role works. In our example above, if we want to add a rule that users with role cannot edit their own post if they have already made ten edits, it will have to be added in the API logic as an exception. There is no way for the roles / permissions system to express it easily. This causes issues since we have to encode this rule in all places where we are checking for the permission. Difficult to make exceptions regular-user edit:self Because the only way to add granularity to a RBAC system is by creating a new role, we can end up with hundreds of different roles that are impossible to manage. Role explosion: : There could be situations in which a user is assigned two roles that have conflicting information. In our example above, if a user is assigned the role and the role, they have and permission. Which one should take precedence? The precedence logic can be coded in the APIs, but this opens the possibility for errors. Can cause conflicts in permissions admin regular-user edit:self edit:all // only allow editing if the blog post belongs to the current user 
} 
else if (permissions.contains("edit:all")) {
	// allow editing 
} This may cause issues if a user has both the and roles – despite having the role, they will not be able to edit all the blogs because the statement is executed first while the rules get skipped in the following else-if statement. admin regular-user admin edit:self edit:all Implementing RBAC At Supertokens, we’ve been thinking a lot about user authentication and authorization. In fact, it’s all that we do. We recently launched our user roles feature based on RBAC principles. Our open-source user authentication can be set up in as little as 45 minutes! You can learn more about how to use user roles and permissions features using SuperTokens via the . recipe guides docs Written by the Folks at — hope you enjoyed! We are always available on our server. Join us if you have any questions or need any help. SuperTokens Discord Also published . here

Understanding Roles-Based Access Control (RBAC)

What is Authorization? Authorization is all about answering the question “Is this user allowed to do a certain operation?”. This is different from Authentication in which we answer the question “Which user is this request coming from?” Both are essential to most applications, and as such, we first go through authentication flows to identify who the user is, and then we go through authorization flows in which we decide if the user has the permissions to do certain operations. What is Roles based access control (RBAC)? RBAC is one of the ways in which Authorization can be implemented. It allows developers to create “groups” of users that can all do the same set of operations. The name of the group is essentially the role of those users. For example, a blogging app may have a role called which allows users (who are associated with that role) to do operations like delete, edit or read all the blogs on the app. The app may have another role called which allows users to read all blogs, but edit or delete only blogs created by them. "admin" "regular-user" In formal notation, the actions that can be taken can be represented as strings like: Read all blogs: "read:all" Delete all blogs: "delete:all" Delete blogs created by self: "delete:self" Edit all blogs: "edit:all" Edit blogs created by self: "edit:self" These are known as permissions. In a grid form, the roles and permissions for our example app will look like this: The permission implies as well. Same
goes for the permission. "edit:all" "edit:self" "delete" Advantages of RBAC : The structure of roles and permissions is very intuitive. It can be understood by new employees fairly quickly. Easy to understand : As the org structure changes, assigning new roles to employees automatically gives them all the right access - there is no extra coding required, and the change can be made via a dashboard in minutes. Easy changes : Using RBAC forces executives to think about and organize access control. This information can then be used by compliance officers during audit. Improving compliance : Due to its ease of use, developers can easily implement the right access control policies in their APIs reducing the chances of data leaks. Decrease risk of data breaches / leakage Disadvantages of RBAC : It can be complex to make exceptions to how a role works. In our example above, if we want to add a rule that users with role cannot edit their own post if they have already made ten edits, it will have to be added in the API logic as an exception. There is no way for the roles / permissions system to express it easily. This causes issues since we have to make sure to encode this rule in all places where we are checking for the permission. Difficult to make exceptions "regular-user" "edit:self" : There could be situations in which a user is assigned two roles that have conflicting information. In our example above, if a user is assigned the role and the , they have and permission. Which one should take precedence? The precedence logic can be coded in the APIs, but that opens up scope for errors. Can cause conflicts in permissions "admin" "regular-user" "edit:self" "edit:all" In fact, developers may forget to define permission precedence alltogether. This can cause unintended side effects in authorization logic. In our example, if we write the API logic like this: // ...
if (permissions.contains("edit:self")) {
    // only allow edit if the blog belongs to the current user
} else if (permissions.contains("edit:all")) {
    // allow edit
}
// ... It may cause issues if a user has the and roles - despite having the role, they will not be able to edit all the blogs cause it will execute into the first statement above. "admin" "regular-user" "admin" if Code Example Let’s continue with our example above and see how we can actually implement it in an app using - an open source authentication / authorization provider. SuperTokens The code snippets below are for a NodeJS backend, but similar logic applies for the other backend SDKs offered by SuperTokens as well. All the code snippets are as per SuperTokens Node SDK version v11.0.1 Step 1) Creating the roles and permissions SuperTokens needs to know about the roles and permissions before they can be assigned to users. For that, we can use the function exposed by the SDK: createNewRoleOrAddPermissions import UserRoles from "supertokens-node/recipe/userroles";

// creating the admin role and adding permissions to it.
await UserRoles.createNewRoleOrAddPermissions("admin", ["read:all", "delete:all", "edit:all"])

// creating the regular-user role and adding permissions to it.
await UserRoles.createNewRoleOrAddPermissions("regular-user", ["read:all", "delete:self", "edit:self"]) Step 2) Assigning roles to users on sign up You can add the code snippet below in your override function for the sign up API import UserRoles from "supertokens-node/recipe/userroles";

// the value of roleToAssign needs to be fetched by you.
// For example, you could check if the user's email is of a certain domain,
// and if it is, then they would be an admin, else not.
if (roleToAssign === "admin") {
    // the userId belongs to the user who just signed up.
    await UserRoles.addRoleToUser(userId, "admin");
} else {
    await UserRoles.addRoleToUser(userId, "regular-user");
} You can even so that accessing them later (on the frontend or backend) is efficient. add the roles and permissions to the user’s session payload Step 3) Guarding APIs based on a user’s role or permissions Once you have completed session verification in your APIs, you can retrieve the user ID of the logged in user and get their roles and permissions using that: import { verifySession } from "supertokens-node/recipe/session/framework/express";
import UserRoles from "supertokens-node/recipe/userroles";

app.delete("/blog", verifySession(), async (req, res) => {
    let blogId = req.body.blogId
    let userId = req.session.getUserId();

    let roles = await UserRoles.getRolesForUser(userId).roles
    // if the user is an admin, we will be ["admin"], else we will get ["regular-user"]

    let permissions = await UserRoles.getPermissionsForRole(roles[0]).permissions
    // if the role is "admin", we get ["read:all", "delete:all", "edit:all"]
    // else we get ["read:all", "delete:self", "edit:self"]

    if (permissions.includes("delete:all")) {
        // allow delete
    } else if (permissions.includes("delete:self")) {
        if (getOwnerOfBlog(blogId) === userId) {
            // allow delete
        } else {
            // return access denied error
        }
    }
}) You can learn more about how to use user roles and permissions feature using SuperTokens via the recipe guides docs on supertokens.com. Alternate libraries Whilst SuperTokens allows you to guard your frontend and backend routes via a mapping of roles and permissions, access control goes beyond that. You may want to: Organize roles in a hierarchy such that a parent role inherits permissions from child roles. Be able to specify permission precedence with the authorization framework as opposed to in your API code. Visualize the roles and permissions relations. Define complicated policies that combine roles and permissions to determine if a user has access to a resource. For these use cases, there are dedicated authorization solutions which you can integrate with your existing authentication provider. Some examples are: Casbin Osohq Permit.io Written by the Folks at SuperTokens — hope you enjoyed! We are always available on our . Join us if you have any questions or need any help. Discord server

Stories, News & Mentions about SUPERTOKENS

Supertokens’s Stories on HackerNoon