Forem: SuperTokens

Hacktoberfest with SuperTokens

SuperTokens — Tue, 15 Oct 2024 11:45:21 +0000

Once again, Hacktoberfest is upon us 🎉

As an open-source company, we're proud to celebrate it and motivate more people to contribute to the software they use every day. Of course, that means some of our repositories will be a part of this year's Hacktoberfest effort. But before we get into the details of how you can contribute to SuperTokens - let's have a quick recap 🙂

What's Hacktoberfest?

To quote the official website, Hacktoberfest is "A month-long celebration of all things open-source". The first Hacktoberfest took place back in 2013. It started as a simple idea - during October, everyone's encouraged to make 4 pull request to an open source repository, and if their PR gets accepted, the contributor is rewarded with a limited edition t-shirt.

Hacktoberfest started as a fairly small affair but grew into a global phenomenon in which thousands of people contribute to open source. So, if you were looking for a reason to start contributing back to open source - Hacktoberfest is as good of a reason as any :)

SuperTokens at Hacktoberfest

This year, we've decided to include one repository in Hacktoberfest: Our CLI, create-supertokens-app - https://github.com/supertokens/create-supertokens-app

The reason behind it is simple - the number one question a developer might ask when first getting in contact with SuperTokens is, "How do I integrate my stack with SuperTokens"?

To answer that, we've realized a well-documented example may work best. Thus, we've decided to focus on exactly that - got a stack we don't have an example for? Help us cover it! :)

How to contribute to the `create-supertokens-app` CLI

The number one contribution type we're looking for is new scaffolds using our pre-built UI. What that means in practice is:

Carefully read through the contribution guide.
Check whether we support your chosen backend, frontend or fullstack.
(Optional) Also check whether someone else is already trying to cover what you'd like to contribute with. These things are always easier in a team 😉
Make sure to follow the Hacktoberfest guidelines
Stuck? Got questions? Hit us up on discord! Make sure to use the dedicated #hacktoberfest-2024 channel for this purpose.

We're okay with other kinds of contributions too (think README improvements and general doc improvements for the individual scaffolds), but in line with the Hacktoberfest guidelines, we're also not going to accept small typo fixes as valid.

Other ways to contribute

Got something else in mind? Thinking about writing an article or a tutorial about SuperTokens? We might be able to do something about that too. Ping us on discord on the #hacktoberfest-2024, and we'll figure something out together.

Rewards

We're currently working on an Ambassador and Contributor programs for our community members. Every valid contribution to our repos above makes you eligible for those roles. Details coming soon 😉

Conclusion

Hacktoberfest is a great opportunity to contribute to the open source ecosystem and gain some experience and exposure for yourself, regardless of your experience level. We at SuperTokens are happy to support the effort! See you on the other side of those 4 PRs 🙂

Adding login to your Next.js app using the app directory with SuperTokens

SuperTokens — Thu, 18 Jan 2024 11:32:19 +0000

Next.js has become a popular framework for building web applications. The framework recently introduced its app directory as a future replacement to the current way of organising the project and creating pages and api routes.

This blog will cover how to setup email password and social login authentication with SuperTokens using the app directory in Next.js.

(Recommended) Use `create-supertokens-app`

create-supertokens-app is a command line tool created by the SuperTokens team that lets you create new projects with SuperTokens already integrated. This is the fastest way to get started with SuperTokens. To use this tool, run the following command:

npx create-supertokens-app@latest

The tool will prompt you for your tech stack, you can choose between the app directory and the pages directory.

The rest of this article is relevant only if you are adding SuperTokens to your app manually and if you have not used the tool mentioned above. If you used create-supertokens-app, the setup is already complete and you can continue building the rest of the application. To know details about Next.js integration with SuperTokens, refer to their official documentation

Manually Setting up the Next.js project

Run the following command:

npx create-next-app <PROJECT_NAME>

create-next-app will prompt you to select details about your project, for the sake of this example we are:

Using Typescript
Using ESLint
Not using Tailwind CSS
Not using the src/ directory
Using the App router
Not using import aliases

After the tool has finished, you should have a basic Next.js app setup. You can run the project with npm run dev.

Installing and setting up SuperTokens

Install supertokens-auth-react and supertokens-node as node dependencies:

npm i supertokens-node supertokens-auth-react

In this example, we are going to be using the Social login + email password recipe of SuperTokens.

Step 1: Initialise SuperTokens for our APIs

SuperTokens' node SDK provides a set of APIs that we can use for logging in our users and managing their sessions. We will follow the quick setup guide to initialise the backend SDK. Create a /app/config/appinfo.ts file and add the following code to it:

export const appInfo = {
    appName: 'SuperTokens Next.js demo app',
    apiDomain: 'http://localhost:3000',
    websiteDomain: 'http://localhost:3000',
    apiBasePath: '/api/auth',
    websiteBasePath: '/auth',
};

apiDomain tells SuperTokens where the APIs are exposed from
websiteDomain is the base URL of the frontend
apiBasePath is the path at which the backend SDK exposes all its APIs
websiteBasePath is the path where the frontend SDK will add its routes

Because Next.js serves both the frontend and backend on the same base URL, it is important to make sure that the apiBasePath and websiteBasePath are not the same.

Create a /app/config/backend.ts file and add the following code to it:

import SuperTokens from "supertokens-node";
import ThirdPartyEmailPassword from "supertokens-node/recipe/thirdpartyemailpassword";
import Session from "supertokens-node/recipe/session";
import { TypeInput } from "supertokens-node/types";
import { appInfo } from "./appinfo";

export const backendConfig = (): TypeInput => {
    return {
        appInfo,
        supertokens: {
            connectionURI: "https://try.supertokens.io",
        },
        recipeList: [
            ThirdPartyEmailPassword.init({
                /**
                 * These are development credentials provided by SuperTokens, make sure
                 * to use your own credentials when you deploy to production.
                 */
                providers: [
                    {
                        config: {
                            thirdPartyId: "google",
                            clients: [{
                                clientId: "1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com",
                                clientSecret: "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"
                            }]
                        }
                    }, 
                    {
                        config: {
                            thirdPartyId: "github",
                            clients: [{
                                clientId: "467101b197249757c71f",
                                clientSecret: "e97051221f4b6426e8fe8d51486396703012f5bd"
                            }]
                        }
                    }, 
                    {
                        config: {
                            thirdPartyId: "apple",
                            clients: [{
                                clientId: "4398792-io.supertokens.example.service",
                                additionalConfig: {
                                    keyId: "7M48Y4RYDL",
                                    privateKey:
                                        "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgu8gXs+XYkqXD6Ala9Sf/iJXzhbwcoG5dMh1OonpdJUmgCgYIKoZIzj0DAQehRANCAASfrvlFbFCYqn3I2zeknYXLwtH30JuOKestDbSfZYxZNMqhF/OzdZFTV0zc5u5s3eN+oCWbnvl0hM+9IW0UlkdA\n-----END PRIVATE KEY-----",
                                    teamId: "YWQCXGJRJL",
                                }
                            }]
                        }
                    },
                ],
            }),
            Session.init(),
        ],
    };
}

let initialized = false;
export function ensureSuperTokensInit() {
  if (!initialized) {
    SuperTokens.init(backendConfig());
    initialized = true;
  }
}

The ThirdPartyEmailPassword recipe adds email password and social login to our project and the Session recipe adds the functionality of managing users sessions and refreshing their sessions.

In our APIs we will use ensureSuperTokensInit to make sure SuperTokens is initialised before we use any functionality from the SDK.

Also modify the dev script in the package.json to:

{
    "scripts": {
        "dev": "next dev -p 3000",
    },
}

We do this because in this example we want the project to run on port 3000, if you want to keep the default port or use another port you can modify this script. Keep in mind that if you use a different port, you also need to modify the apiDomain and websiteDomain values inside the /app/config/backend.ts file.

Step 2: Adding SuperTokens' API routes

The SuperTokens backend SDKs expose a set of API routes that we can use in our project, this makes it easier to add login to our app because we don't have to build this logic ourselves.

Start by creating a new file /app/api/auth/[...path]/route.ts. Adding [...path] as a folder makes sure that the route.ts file is called for all network calls made to the /auth/* paths. Add the following content to the route.ts file:

import { getAppDirRequestHandler } from 'supertokens-node/nextjs';
import { NextRequest, NextResponse } from 'next/server';
import { ensureSuperTokensInit } from '../../../config/backend';

ensureSuperTokensInit();

const handleCall = getAppDirRequestHandler(NextResponse);

export async function GET(request: NextRequest) {
  const res = await handleCall(request);
  if (!res.headers.has('Cache-Control')) {
    // This is needed for production deployments with Vercel
    res.headers.set(
      'Cache-Control',
      'no-cache, no-store, max-age=0, must-revalidate'
    )
  }
  return res;
}

export async function POST(request: NextRequest) {
  return handleCall(request);
}

export async function DELETE(request: NextRequest) {
  return handleCall(request);
}

export async function PUT(request: NextRequest) {
  return handleCall(request);
}

export async function PATCH(request: NextRequest) {
  return handleCall(request);
}

export async function HEAD(request: NextRequest) {
  return handleCall(request);
}

We call ensureSuperTokensInit to make sure SuperTokens is always initialised when any of the SuperTokens API routes are called. getAppDirRequestHandler is a helper function that the SuperTokens SDK provides, this adds request parsing, error handling etc so that we dont have to manually check for individual API results.

And thats it, the SuperTokens backend SDK is setup. To verify that we have set it up correctly you can open http://localhost:3000/api/auth/signup/email/exists?email=somerandomemail@email.com in your browser, if it is all working correctly you should see a response similar to:

{"status":"OK","exists":false}

You can see the full API spec to know all the API routes that the SuperTokens backend SDKs expose.

Step 3: Adding SuperTokens to the frontend

supertokens-auth-react provides a pre built UI that gets added as part of your project so that you dont have to build the login UI yourself. If you want to build your own UI you can use functions exposed by the SDK to interact with your APIs, either way you dont need to call the APIs exposed by the backend SDKs manually.

The full set of steps for initialising SuperTokens with the pre-built UI can be found in the official frontend setup guide

Create a /app/config/frontend.ts file and add the following code to it:

import ThirdPartyEmailPassword, {
    Google,
    Github,
    Apple,
} from 'supertokens-auth-react/recipe/thirdpartyemailpassword';
import Session from 'supertokens-auth-react/recipe/session';
import { appInfo } from './appinfo';
import { useRouter } from 'next/navigation';
import { SuperTokensConfig } from 'supertokens-auth-react/lib/build/types';

const routerInfo: { router?: ReturnType<typeof useRouter>; pathName?: string } =
  {};

export function setRouter(
  router: ReturnType<typeof useRouter>,
  pathName: string,
) {
  routerInfo.router = router;
  routerInfo.pathName = pathName;
}

export const frontendConfig = (): SuperTokensConfig => {
    return {
        appInfo,
        recipeList: [
            ThirdPartyEmailPassword.init({
                signInAndUpFeature: {
                    providers: [
                        Google.init(),
                        Github.init(),
                        Apple.init(),
                    ],
                },
            }),
            Session.init(),
        ],
        windowHandler: (orig) => {
            return {
                ...orig,
                location: {
                    ...orig.location,
                    getPathName: () => routerInfo.pathName!,
                    assign: (url) => routerInfo.router!.push(url.toString()),
                    setHref: (url) => routerInfo.router!.push(url.toString()),
                },
            };
        },
    };
}

Create a /app/components/supertokensProvider.tsx file and add the following contents to it:

'use client';
import React from 'react';
import { SuperTokensWrapper } from 'supertokens-auth-react';
import SuperTokensReact from 'supertokens-auth-react';
import { frontendConfig, setRouter } from '../config/frontend';
import { usePathname, useRouter } from 'next/navigation';

if (typeof window !== 'undefined') {
  // we only want to call this init function on the frontend, so we check typeof window !== 'undefined'
  SuperTokensReact.init(frontendConfig());
}

export const Providers: React.FC<React.PropsWithChildren<{}>> = ({
  children,
}) => {
  setRouter(useRouter(), usePathname() || window.location.pathname);

  return <SuperTokensWrapper>{children}</SuperTokensWrapper>;
};

We check for window not being undefined because we only want to initialise the SuperTokens React SDK on the client side. The SuperTokensWrapper component adds some context to the rest of our application so that we can access the session from anywhere.

SuperTokens wrapper initialises a React context for sessions, because of this we make this component a client component by adding 'use client' to the top of the file.

Modify the /app/layout.tsx file:

import './globals.css'
import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import { SuperTokensProvider } from './components/supertokensProvider'

const inter = Inter({ subsets: ['latin'] })

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <SuperTokensProvider>
        <body className={inter.className}>{children}</body>
      </SuperTokensProvider>
    </html>
  )
}

Step 4: Adding SuperTokens routes to our frontend

Create a new /app/auth/[[...path]]/page.tsx file. Adding [[...path]] as a folder makes sure that the page.tsx file is served for all /auth/* routes and also ensures that the /auth route itself also serves the page.tsx file. Add the following content to the page.tsx file

'use client';

import { useEffect } from 'react';
import { redirectToAuth } from 'supertokens-auth-react';
import SuperTokens from 'supertokens-auth-react/ui';
import { ThirdPartyEmailPasswordPreBuiltUI } from 'supertokens-auth-react/recipe/thirdpartyemailpassword/prebuiltui';

export default function Auth() {
  // if the user visits a page that is not handled by us (like /auth/random), then we redirect them back to the auth page.
  useEffect(() => {
    if (
      SuperTokens.canHandleRoute([ThirdPartyEmailPasswordPreBuiltUI]) === false
    ) {
      redirectToAuth({ redirectBack: false });
    }
  }, []);

  if (typeof window !== 'undefined') {
    return SuperTokens.getRoutingComponent([ThirdPartyEmailPasswordPreBuiltUI]);
  }

  return null;
}

SuperTokens.canHandleRoute returns true if SuperTokens exposes a component for the current browser url and ThirdPartyEmailPasswordPreBuiltUI are all the pre built UI components that can handle a specific set of routes. In this file we check if the current page can be handled by the SuperTokens SDK and return the relevant component from SuperTokens using SuperTokens.getRoutingComponent.

Now if you visit http://localhost:3000/auth in your browser, you can view the login page of our project and it should look like this:

Does not look the best but at least it works, lets modify the default next app styling to make it look better!

Modify /app/globals.css:

html {
  height: 100%;
}

For the sake of this example we cleared everything because we will not need the additional styles.

The login page should not look like this:

And thats it! The frontend SDK is now setup and the /auth routes are handled by SuperTokens.

Building our home page

Lets start by clearing the default home page content and styles in /app/page.tsx and /app/page.module.css

/app/page.tsx

import styles from './page.module.css'

export default function Home() {
  return (
    <main className={styles.main}>
      Hello World
    </main>
  )
}

/app/page.module.css

.main {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  min-height: 100vh;
}

In our project we want to do the following:

Display the user's userId and email on the home page
Only allow users who are logged in to view the home page
Redirect to the /auth route if the visitor is not logged in or their session has expired

Protecting your frontend routes

Start by creating a /app/sessionUtils.ts file and adding the following code to it:


import { cookies, headers } from 'next/headers';
import { NextRequest, NextResponse } from 'next/server';
import Session, { SessionContainer, VerifySessionOptions } from "supertokens-node/recipe/session";
import { ensureSuperTokensInit } from '../config/backend';
import { PreParsedRequest, CollectingResponse } from "supertokens-node/framework/custom";
import { HTTPMethod } from "supertokens-node/types";

ensureSuperTokensInit();

export async function getSSRSession(
  req?: NextRequest,
  options?: VerifySessionOptions
): Promise<{
  session: SessionContainer | undefined;
  hasToken: boolean;
  hasInvalidClaims: boolean;
  baseResponse: CollectingResponse;
  nextResponse?: NextResponse;
}> {
  const query = req !== undefined ? Object.fromEntries(new URL(req.url).searchParams.entries()) : {};
  const parsedCookies: Record<string, string> = Object.fromEntries(
      (req !== undefined ? req.cookies : cookies()).getAll().map((cookie) => [cookie.name, cookie.value])
  );
  let baseRequest = new PreParsedRequest({
      method: req !== undefined ? (req.method as HTTPMethod) : "get",
      url: req !== undefined ? req.url : "",
      query: query,
      headers: req !== undefined ? req.headers : headers(),
      cookies: parsedCookies,
      getFormBody: () => req!.formData(),
      getJSONBody: () => req!.json(),
  });

  let baseResponse = new CollectingResponse();

  try {
      let session = await Session.getSession(baseRequest, baseResponse, options);
      return {
          session,
          hasInvalidClaims: false,
          hasToken: session !== undefined,
          baseResponse,
      };
  } catch (err) {
      if (Session.Error.isErrorFromSuperTokens(err)) {
          return {
              hasToken: err.type !== Session.Error.UNAUTHORISED,
              hasInvalidClaims: err.type === Session.Error.INVALID_CLAIMS,
              session: undefined,
              baseResponse,
              nextResponse: new NextResponse("Authentication required", {
                  status: err.type === Session.Error.INVALID_CLAIMS ? 403 : 401,
              }),
          };
      } else {
          throw err;
      }
  }
}

To know more about what getSSRSession does visit the official documentation

Create a /app/components/tryRefreshClientComponent.tsx file and add the following code:

"use client";

import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import Session from "supertokens-auth-react/recipe/session";
import SuperTokens from "supertokens-auth-react";

export const TryRefreshComponent = () => {
    const router = useRouter();
    const [didError, setDidError] = useState(false);

    useEffect(() => {
        void Session.attemptRefreshingSession()
            .then((hasSession) => {
                if (hasSession) {
                    router.refresh();
                } else {
                    SuperTokens.redirectToAuth();
                }
            })
            .catch(() => {
                setDidError(true);
            });
    }, []);

    if (didError) {
        return <div>Something went wrong, please reload the page</div>;
    }

    return <div>Loading...</div>;
};

This component will be used to refresh the session if the user's current session has expired. We use Session.attemptRefreshingSession to call the refresh endpoint, if the request fails we redirect back to the login route using SuperTokens.redirectToAuth.

Create a new /app/components/userInformation.tsx file:

import { getSSRSession } from '../sessionUtils';
import { TryRefreshComponent } from './tryRefreshClientComponent';
import styles from '../../styles/Home.module.css';
import { redirect } from 'next/navigation'

export async function UserInformation() {
  const { session, hasToken } = await getSSRSession();

  if (!session) {
    if (!hasToken) {
      redirect('/auth');
    }
    return <TryRefreshComponent />;
  }

  return (
    <p className={styles.description}>
      Server side component got userId: {session.getUserId()}
    </p>
  );
}

UserInformation is a server side component. In this component we try to fetch session information using getSSRSession and if the user has a session we render the user id (we wll change this later). If the user does not have a session but a token exists we try to refresh the session, if no token exists then we redirect the user to the /auth route.

Modify /app/page.tsx

import { UserInformation } from './components/userInformation'
import styles from './page.module.css'

export default function Home() {
  return (
    <main className={styles.main}>
      <UserInformation />
    </main>
  )
}

Now if you try to open http://localhost:3000/ it will redirect you to /auth because we dont have a valid session. But if you sign in to the website it will redirect you to the home page which should look like this:

Protecting your API routes

To fetch the user's email we need to make a network call. We need to make sure that only a user with an active session can fetch their information.

Start by modifying /app/sessionUtils.ts:

import { cookies, headers } from 'next/headers';

// ...

export async function withSession(
  request: NextRequest,
  handler: (session: SessionContainer | undefined) => Promise<NextResponse>,
  options?: VerifySessionOptions
) {
  let { session, nextResponse, baseResponse } = await getSSRSession(request, options);
  if (nextResponse) {
      return nextResponse;
  }

  let userResponse = await handler(session);

  let didAddCookies = false;
  let didAddHeaders = false;

  for (const respCookie of baseResponse.cookies) {
      didAddCookies = true;
      userResponse.headers.append(
          "Set-Cookie",
          serialize(respCookie.key, respCookie.value, {
              domain: respCookie.domain,
              expires: new Date(respCookie.expires),
              httpOnly: respCookie.httpOnly,
              path: respCookie.path,
              sameSite: respCookie.sameSite,
              secure: respCookie.secure,
          })
      );
  }

  baseResponse.headers.forEach((value, key) => {
      didAddHeaders = true;
      userResponse.headers.set(key, value);
  });

  if (didAddCookies || didAddHeaders) {
      if (!userResponse.headers.has("Cache-Control")) {
          // This is needed for production deployments with Vercel
          userResponse.headers.set("Cache-Control", "no-cache, no-store, max-age=0, must-revalidate");
      }
  }

  return userResponse;
}

The withSession is a utility function we will use in all our APIs that require sessions, it will get the session if it exists and then call the handler function which will be our actual API logic. To know more about what this function does visit the official documentation

Lets create a new API route for fetching the user information, create a new file /app/api/user/route.ts:

import { NextResponse, NextRequest } from 'next/server';
import { withSession } from '../../sessionUtils';
import SuperTokens from 'supertokens-node';

export function GET(request: NextRequest) {
  return withSession(request, async (session) => {
    if (!session) {
      return new NextResponse('Authentication required', { status: 401 });
    }

    const userId = session.getUserId();
    const user = await SuperTokens.getUser(userId);

    if (user === undefined) {
        return NextResponse.json({
            email: "not found",
        })
    }

    return NextResponse.json({
      email: user.emails[0],
    });
  })
}

We are creating a GET API route for /user. This API calls withSession because we need an active session to be able to fetch the user's information. If a session does not exist we return with status 401.

We use the session to get the user's user id and then fetch the user information from SuperTokens.

Making network requests that require sessions

Now that we have session protection on our frontend route and API route, we need to actually make a network request to fetch the user's email. Modify the /app/components/userInformation.tsx file:

import { getSSRSession } from '../sessionUtils';
import { TryRefreshComponent } from './tryRefreshClientComponent';
import styles from '../page.module.css';
import { redirect } from 'next/navigation'

export async function UserInformation() {
  const { session, hasToken } = await getSSRSession();

  if (!session) {
    if (!hasToken) {
      redirect('/auth');
    }
    return <TryRefreshComponent />;
  }

  const userEmailResponse = await fetch('http://localhost:3000/api/user', {
    headers: {
      Authorization: 'Bearer ' + session.getAccessToken(),
    },
  });

  let email = "";

  if (userEmailResponse.status !== 200) {
    email = "error with status " + userEmailResponse.status;
  } else {
    email = (await userEmailResponse.json()).email;
  }

  return (
    <p className={styles.description}>
      Server side component got userId: {session.getUserId()}<br/>
      Server side component got email: {email}
    </p>
  );
}

We use session.getAccessToken() to get the current access token of the user, we use this token to make a network request to our newly created API.

Now if you open the home route in your browser you should see something similar to this:

Signing users out of the application

We also need to provide a way for users to sign out, luckily SuperTokens provides a very easy way to do this. First lets add a sign out button to the home page, create a new /app/components/signOut.tsx file:

'use client'

import { useSessionContext } from "supertokens-auth-react/recipe/session";
import { useRouter } from 'next/navigation'
import Session from "supertokens-auth-react/recipe/session";

export const SignOut = () => {
    const session = useSessionContext();
    const router = useRouter();

    if (session.loading === true) {
        return null;
    }

    const signOut = async () => {
        await Session.signOut();
        router.refresh();
    }

    return <button onClick={signOut}>Sign out</button>
}

This is a client component that will render a button to sign out if a session exists. We then use Session.signOut() to call the sign out API and then refresh the page. In this example we refresh the page because we want to demonstrate that the user would get redirected to the login page without a valid session, you can redirect to /auth directly if you prefer.

Add the SignOut component to the home page:

return (
    <div>
        <div>
            <p className={styles.description}>
            Server side component got userId: {session.getUserId()}<br/>
            Server side component got email: {email}
            </p>
        </div>
        <SignOut/>
    </div>
);

Conclusion

And thats it, our Next.js app has SuperTokens set up with frontend and api routes being exposed by the SDKs and we now have our custom API and frontend routes protected to require sessions.

This example was just a basic use case for what you can do with SuperTokens, to know more or to learn how to use other features and recipes of SuperTokens visit their official SuperTokens documentation.

To learn more about Next.js visit the Next.js documentation

How we used multi-tenancy to cut our AWS costs by 50%

SuperTokens — Wed, 18 Oct 2023 07:52:42 +0000

Part 1: How does the SuperTokens managed service work and why does it need to change.

Part 2: Using multi-tenancy to cut our AWS infra costs by more than 50%

In this part we will go over SuperTokens Multi-tenancy feature and how it evolved our deployment cycle to cut our AWS billing by 50%.

Here’s what we covered in our last post:

SuperTokens infrastructure and deployment cycle.
Improvements made to the SuperTokens deployment cycle to speed up production deployment times by 30%
How our infra costs were not sustainable and why it needed to change.

What is multi-tenancy?

As mentioned in Part 1, “We saw multi-tenancy as an opportunity to optimize the utilization of our EC2 instances by consolidating our core instances. This would cut down our costs while also providing the expected performance”… But what does that mean? Let’s break it down. Multi-tenancy is a feature, typically used by B2B SaaS companies to allow multiple organizations to sign up to their SaaS app, with the ability for each organization to have their own login methods or SSO configurations. Additionally, user pools can also be segmented. Here’s how it helped us.

How we implemented SuperTokens Multi-tenancy

With multi-tenancy, we re-architected the way we host and manage our users. Initially, whenever a user signed up and created an app with SuperTokens, it would trigger the following flow:

In this process, each development and production SuperTokens core ran in it’s own separate EC2 instances. With Multi-tenancy we now treat all SuperTokens customers as tenants. This means that we could now host multiple users on a single SuperTokens instance. Our deployment process now looks like this:

As you can see in the new deployment strategy, when a new user signs up, we now create a new tenant in a SuperTokens instance. These instances run in T3 large instances. In our testing, for development mode, up to 100 tenants can be run seamlessly on a single instance, and for production mode, up to 50 tenants can be created on a single instance.

What are the benefits of the new architecture?

1. Cost Savings

Well, the biggest difference post this change is the cost savings.

Here’s a bill for the month of July before the multi-tenancy changes kicked-in:

And here's the bill for September, post the changes going live

When compared, it's 54% down

2. Improved start-up time

Another improvement was app startup time. In the new architecture, creating a new user is as simple as creating a new tenant. When compared to the old process, the new architecture is about 94% faster and new apps can be created in seconds.

Conclusion

Multi-tenancy with SuperTokens is a powerful feature that enables businesses to create unique authentication flows for their customers, segment users into unique user pools and automatically create new tenants. For SuperTokens, multi-tenancy allowed us to consolidate our user applications to save on resources, but, your use case maybe very different. You can learn more about how multi-tenancy works and the experiences it enables by visiting the multi-tenancy feature page.

How we cut our AWS costs by more than 50%

SuperTokens — Tue, 17 Oct 2023 05:28:35 +0000

In this two part series we will go over SuperTokens manged service infrastructure and the changes we made to cut our AWS billing by more than 50%.

*Part 1: How does the SuperTokens managed service work and why does it need to change.
*
Part 2: Using multi-tenancy to cut our AWS infra costs by more than 50%

Introduction

The SuperTokens managed service powers numerous web products, mobile applications, and services and is primarily hosted on AWS. Our infrastructure leverages a suite of AWS tools, including AWS RDS for our database, EC2 instances for SuperToken deployments, and System Manager for instance management and automation. Over time, we’ve refined our deployment cycle to enhance stability, fault tolerance, and cost efficiency but our most recent update has yielded our biggest savings yet, slashing costs by over 50% while achieving record scalability.

What was the SuperTokens infrastructure like?

To gain a better understanding of the SuperTokens infrastructure, it’s crucial to grasp the deployment cycle.

SuperTokens allows users to use the SuperTokens SAAS service in two modes: development and production. Here’s the breakdown of each:

Development Mode: The Development mode used to run on an EC2 T3.small instance. To maximize resource utilization, we would deploy up to seven development core instances on the same T3.small instance. This configuration resulted in a remarkably swift setup for new development cores, typically taking a mere 15-20 seconds and was suitable for testing purposes.

Production mode: In contrast, the production mode followed a different deployment strategy. Each production mode deployment was hosted on a dedicated EC2 T2.micro instance. This meant that when a new production SuperTokens core instance had to be created, a fresh T2.micro instance was spun up, and docker was installed using System Manager. Consequently, this process required additional time when compared to the development mode, with an average deployment time of around 4-5 minutes.

For example, if 7 users were to sign up for SuperTokens, it would look like the following:

Initial Improvements to the deployment cycle

One of our initial optimizations focused on reducing the startup time for generating production instances. We recognized that creating a custom AMI(Amazon Machine Image) pre-installed with Docker alongside the operating system would cut down on start-up time. This change trimmed approximately 45 seconds from the production deployment procedure, reducing the setup time to approximately 3-4 minutes.

In retrospect, another avenue for improvement that we identified was the usage of AWS Reserved Instances. While this approach would have entailed an upfront cost, it would have resulted in substantial long-term savings.

So what prompted us to change our deployment process?

Why we had to change our deployment process

The past year has been quite a ride for SuperTokens. We released a host of new features and saw a big uptick in users. But, as our user numbers climbed, so did our infrastructure costs. With our AWS credits running out soon, we knew we had to do something to cut our expenses.

While working on our new multi-tenancy feature, we saw an opportunity to optimize the utilization of our EC2 instances by consolidating our core instances. This would cut down our costs while also providing the expected performance.

In part 2 we will go over the changes we made to achieve this.

How to create an invite-only auth flow in 2023

SuperTokens — Thu, 05 Oct 2023 06:41:41 +0000

Introduction

Whether aiming to boost referrals, drive exclusivity, or simply enhance user engagement, a well-crafted invite flow can make all the difference. In this blog post, we will delve into the steps of how you can secure your React app with Email-password authentication with SuperTokens, customized to have an invite-only flow.

Setup

Our demo app will use a React frontend with a NodeJS backend, but the instructions should translate to other frameworks and languages. You can find the list of SuperTokens-supported frameworks and languages here.

We can start a new project configured with SuperTokens using their CLI with the following command:

npx create-supertokens-app@latest

You should see the following output:

Follow the prompts on-screen and set up an app with a React frontend, and NodeJs backend configured with email-password based authentication.

We can now start customizing the authentication flows to enable invite-only authentication

Step 1: Disable Sign Ups

If you were to run the example application now, you would be greeted with the authentication page. This page allows you to sign users up. We will need to disable the sign-up UI on the frontend and disable the sign up API on the backend.

Disable the sign up UI in SuperTokens Frontend config

We can customize the frontend UI and use CSS to hide the sign up button.


import SuperTokens from "supertokens-auth-react";
import EmailPassword from "supertokens-auth-react/recipe/emailpassword";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        EmailPassword.init({
            signInAndUpFeature: {
                signInForm: {
                    style: `
                        [data-supertokens~=headerSubtitle] {
                            display: none;
                        }
                    `,
                }
            },
        }),
    ]
});

This should hide the button which allows you to switch to the sign up screen.

Disable the sign up API in SuperTokens Backend config

We override the SuperTokens backend config to disable the public facing sign up API:


import SuperTokens from "supertokens-node";
import EmailPassword from "supertokens-node/recipe/emailpassword";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        EmailPassword.init({
            override: {
                apis: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        signUpPOST: undefined,
                    }
                }
            }
        })
    ]
});

Step 2: Creating the invite-only flow

Create a protected API that will create users and send invite links

To create users and send them invite links we will need to create an API on the backend which will:

- Call the signUp function from the SuperTokens backend SDK using the user’s email and a fake password. This fake password should be unguessable and should be shared across all invited users.
Generate a password reset link and send that as an invite link to the user’s email.
Once the user clicks the link, they will be shown a page asking them to input their password after which, they can login.
Finally, we add an access control check to make sure that only users with the admin role can add additional users.

import express from "express";
import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express";
import UserRoles from "supertokens-node/recipe/userroles";
import EmailPassword from "supertokens-node/recipe/emailpassword";

const FAKE_PASSWORD = "asokdA87fnf30efjoiOI**cwjkn";

let app = express();

app.post("/create-user", verifySession({
    overrideGlobalClaimValidators: async function (globalClaimValidators) {
        return [...globalClaimValidators,
        UserRoles.UserRoleClaim.validators.includes("admin")]
    }
}), async (req: SessionRequest, res) => {
    let email = req.body.email;

    let signUpResult = await EmailPassword.signUp("public", email, FAKE_PASSWORD);
    if (signUpResult.status === "EMAIL_ALREADY_EXISTS_ERROR") {
        res.status(400).send("User already exists");
        return;
    }

    // we successfully created the user. Now we should send them their invite link
    await EmailPassword.sendResetPasswordEmail("public", signUpResult.user.id);

    res.send("Success");
});

Note:

The code above uses the default password reset path for the invite link (/auth/reset-password). You can create custom UI hosted on another path and use the password reset functions provided by the SuperTOkens frontend SDK to call the password reset token consumption API from the frontend.

Additionally, the sendResetPasswordEmail function uses the default password reset email(or the one customized using the emailDelivery config). If you would like to create the reset password link and send it yourself, you can use the createResetPasswordLink function to generate the password reset string.

Ensure that invited users have reset their passwords

To ensure that users who have reset their passwords, we need to make the following changes:

Prevent users from signing in with the FAKE_PASSWORD.
Prevent users from resetting their password by setting their new password as the FAKE_PASSWORD.
Prevent users from updating their password and setting it to the FAKE_PASSWORD.


import SuperTokens from "supertokens-node";
import EmailPassword from "supertokens-node/recipe/emailpassword";

const FAKE_PASSWORD = "asokdA87fnf30efjoiOI**cwjkn"

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    supertokens: {
        connectionURI: "...",
    },
    recipeList: [
        EmailPassword.init({
            override: {
                apis: (originalImplementation) => {
                    // ... override from previous code snippets...
                    return originalImplementation
                },
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        updateEmailOrPassword: async function (input) {
                            // This can be called on the backend
                            // in your own APIs
                            if (input.password === FAKE_PASSWORD) {
                                throw new Error("Use a different password")
                            }

                            return originalImplementation.updateEmailOrPassword(input);
                        },
                        resetPasswordUsingToken: async function (input) {
                            // This is called during the password reset flow
                            // when the user enters their new password
                            if (input.newPassword === FAKE_PASSWORD) {
                                return {
                                    status: "RESET_PASSWORD_INVALID_TOKEN_ERROR"
                                }
                            }
                            return originalImplementation.resetPasswordUsingToken(input);
                        },
                        signIn: async function (input) {
                            // This is called in the email password sign in API
                            if (input.password === FAKE_PASSWORD) {
                                return {
                                    status: "WRONG_CREDENTIALS_ERROR"
                                }
                            }
                            return originalImplementation.signIn(input);
                        },
                    }
                }
            }
        })
    ]
});

And that’s it! Your app now only allows invited users to log in. Once a user is invited they will be sent an email asking to reset their password post which they are able to sign in.

Conclusion

Although there are a few customizations that need to be made, setting up an invite-only flow with SuperTokens is straightforward. You can find the related documentation for the invite flow here if you need the code for other languages/frameworks.

URI vs URL: The real difference between the two

SuperTokens — Thu, 31 Aug 2023 12:12:45 +0000

Introduction

In the ever-evolving landscape of web development, often times it can be confusing navigating the waters of all the acronyms and technical terms. In this blog we are going to be looking at URL, URI, and URN, terms often used interchangeably leading to confusion when describing the address of a webpage.

URL (Uniform Resource Locator):

The more recognizable of the two is the URL or Uniform Resource Locator. Analogous to how your physical address helps someone find your home, a URL is what guides your web browser to locate a specific resource on the internet. This resource could be a webpage, an image, a video, or any other digital content. A typical URL consists of several components, including:

Protocol: This is the communication method your browser uses to retrieve the resource. Common protocols include http, https, ftp, and more.

Domain Name: The domain name represents the address of the website's server. For example, in www.example.com, example.com is the domain name.

Path: The path specifies the specific location of the resource on the server's directory structure. It resembles a file path on your computer.

Query Parameters: These are optional parameters that provide additional information to the server, often used to customize the content you see on a webpage.

Fragment: This part points to a specific section within a web page, allowing you to jump directly to a particular part of the content.

URI (Uniform Resource Identifier):

Moving on to URI, or Uniform Resource Identifier. Think of a URI as the umbrella term that encompasses both URLs and another concept called URN (Uniform Resource Name). A URI is used to identify a resource on the internet, regardless of its type or location. In simpler terms, it's the digital fingerprint that uniquely distinguishes one resource from another.

URN (Uniform Resource Name):

As mentioned in the previous section, URN or Uniform Resource Name, is a subset of URIs that serves as a persistent, location-independent identifier for a resource. Think of it as the "nameplate" for a digital entity. While URLs change if a resource's location shifts, URNs remain constant. This makes them invaluable for citing and referencing resources over time, especially in scenarios where the resource might move or change servers.

Conclusion

Although they are interconnected, URLs, URI, and URN are distinct and should not be confused with each other. URLs guide us to desired online destinations, while URIs stand as the overarching system of identification. URNs, on the other hand, provide the nameplates that stay fixed amid the dynamic landscape of the internet. the address of a webpage.

Understanding JWKS (JSON Web Key Set)

SuperTokens — Thu, 31 Aug 2023 10:00:16 +0000

Introduction

JWTs or Json Web Tokens are most commonly used to identify authenticated users and validate API requests. Part of this verification process requires the use of cryptographic keys to validate the integrity of the JWT to make sure it has not been tampered with. The set of keys used for this process is called JWKS or Json Web Key Set. In this blog post, we will go over what JWKS are and how they are used. If you are interested in learning more about JWTs and how they work, check out our guide.

What are JSON Web Keys (JWKs)?

JSON Web Keys (JWKs) are a JSON data structure that represents cryptographic keys. These keys are primarily used for verifying JWTs in OAuth flows. JWKs are designed to be easily exchanged, making them a standardized and interoperable format for representing cryptographic keys.

Structure of the JWKS

A sample JWKS will have the following layout:


{
"jwk":
  [
    {
     "alg":"RSA",
     "mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
     "exp":"AQAB",
     "Kid":"2011-04-29"
    }
  ]
}

A JWK consists of a JWK Container Object, which is a JSON object that contains an array of JWK key objects as a member. The values of the JWK Container Object members can change depending on which algorithm is used. The example above contains a single member using the RSA algorithm and has the following members:

alg: This member identifies the cryptographic algorithm used with the key.
mod: Contains the modulus value of the RSA public key. It is base64 encoded
exp: exponent value for the RSA public key. It is base64 encoded
kid: They Key id is used to match a specific key. During key rotation, the kid is used to choose among a set of keys within the JWK.

How do JWKS work?

To make sure a JWT has not been tampered with we need to validate its integrity by verifying the signature. This requires a public key that corresponds to the private key used by the Authorization Server to initially sign the JWT. Typically the JWKS can be retrieved by querying an endpoint exposed by the Authorization Server known as a “jwks endpoint”.

Benefits of Using JWKS

Security: JWKS enables the separation of concerns by centralizing key management. This segregation reduces the risk of exposing critical keys accidentally and is a much safer approach as opposed to having the keys hardcoded.
Scalability: As web applications grow in complexity, managing cryptographic keys in a scalable manner becomes crucial. JWKS provides a standardized way to handle keys, simplifying key distribution and rotation as the application scales.
Interoperability: JWKS is designed to be easily exchanged across different platforms and services. This interoperability fosters seamless integration between various components of the authentication ecosystem.

Considerations for JWKS implementation

For most users, you will be using an authentication provider and will not have to deal with setting up your Authorization Server, but, if you do decide to implement the flow yourself, here are some tips to ensure the security of your system in regard to JWKS:

Regular Key Rotation: Frequently rotate the cryptographic keys represented in the JWKS to minimize the impact of potential key compromises.
Access Control: Restrict access to the JWKS endpoint to only authorized clients and implement appropriate access control mechanisms.
Secure Key Storage: Store the cryptographic keys securely, employing industry-standard practices like Hardware Security Modules (HSMs) or cloud-based Key Management Services (KMS).

Conclusion

When it comes to authentication there are a number of terms and protocols thrown around which can be confusing when you first get started. We hope that through this article you have a better understanding of JWKS, its relevance to JWTs, and how they are used. If you have questions about the protocols that need JWKS, check our guides on OAuth and OIDC, they are protocols that use JWTs and rely on JWKS for verification.

Authentication vs Authorization: What's the difference?

SuperTokens — Mon, 14 Aug 2023 06:14:57 +0000

Introduction:

Although they are often conflated with each other, Authentication and Authorization represent two fundamentally different aspects of security that work together in order to protect sensitive information. In this blog, we will go over some of the key differences between the two.

The Foundation - What is Authentication?

Authentication is the process of verifying the identity of a user or entity attempting to gain access to a system or resource. It answers the fundamental question, “Who are you?” to ensure that the individual or device claiming access is, indeed, who they say they are. This identity verification process serves as the initial gatekeeper, protecting against unauthorized entry and mitigating threats like unlicensed access.

Common methods of authentication include

Something You Know: This involves providing a secret, such as a password or an OTP sent through a registered device.
Something You Have: Utilizing physical tokens like mobile authenticators or usb keys to verify identity.
Something You Are: Relying on biometric characteristics such as fingerprints, facial recognition for identification.

Understanding Authorization

While authentication lays the groundwork by confirming identity, authorization takes it a step further by determining what actions or resources an authenticated user can access. In simpler terms, authorization addresses the question, “What are you allowed to do?” and defines the scope of a user’s privileges within the system. This level of granularity is essential for protecting sensitive information and controlling data exposure to prevent unauthorized activities. Authorization mechanisms may include:

There are a number of Authorization techniques like attribute and rule based Authorization but one of the most popular methods is role based access control where users are assigned to predefined roles with associated permissions and restrictions based on their job functions. You can learn more about RBAC in our guide.

Why both matter

The importance of both authentication and authorization cannot be overstated. While authentication ensures that only legitimate users gain access to a system, authorization guarantees that these users are confined to their respective permissions and cannot perform unauthorized actions.

Imagine a scenario where a user has successfully authenticated but lacks proper authorization controls. This user, perhaps with malicious intent or due to a careless mistake, could inadvertently cause significant damage to critical data or systems, putting the entire organization at risk.

On the other hand, effective authorization without proper authentication is equally problematic. An unauthorized user could bypass authentication measures and gain access to sensitive information, leading to data breaches, financial loss, and severe reputational damage.

Best Practices for a Secure Future

To maintain robust digital security, organizations must implement a comprehensive approach that harmonizes authentication and authorization. Here are some best practices to consider:

Multi-factor Authentication (MFA): Combine multiple authentication methods to bolster identity verification, reducing the risk of unauthorized access.
Regular Access Reviews: Periodically review user permissions to ensure they align with their roles and responsibilities, removing unnecessary access.
Principle of Least Privilege: Grant users the minimum level of access required to perform their tasks, minimizing potential exposure.
Centralized Identity Management: Adopt centralized identity management systems to streamline authentication and authorization processes across the organization.

Conclusion

Authentication and authorization are the twin pillars that safeguard our sensitive information. Authentication sets the foundation by verifying identity, while authorization fortifies access controls, determining user privileges. The synergy of these two elements creates a robust security framework that protects organizations and individuals alike. By adhering to best practices and staying vigilant, we can confidently navigate the digital landscape with security and peace of mind.

Remember, it’s not just about “Who are you?” or “What are you allowed to do?” but rather the powerful combination of both that establishes a defense against malicious attackers.

SAML vs OAuth: Choosing the right protocol for authentication

SuperTokens — Mon, 07 Aug 2023 08:14:23 +0000

Introduction

SAML (Security Assertion Markup Language) and OAuth (Open Authorization) are key protocols for authentication and authorization. While both protocols serve essential purposes, they possess distinct characteristics that make them suitable for specific use cases. In this article, we will delve into the world of SAML and OAuth, exploring their differences, objectives, and applications in various scenarios.

What is SAML and OAuth?

SAML was established in the early 2000s and was designed to facilitate Single Sign-On (SSO) and federated identity management across multiple domains. Its objective is to securely exchange user identity information between an Identity Provider (IdP) and a Service Provider (SP) through XML-based messages. SAML’s focus lies primarily in enterprise environments, where seamless user authentication and trust relationships between systems are crucial.

OAuth, a comparatively younger protocol introduced around 2006, addresses the needs of authorization based on social accounts and API integration. Its primary goal is to enable delegated authorization, allowing users to grant limited access to their resources to services without revealing their credentials. OAuth’s widespread adoption stems from its ability to securely integrate with popular social platforms, such as Facebook, Twitter, and Google, and provide a standardized framework for granting access to user data through APIs.

It is important to note that although SAML can do both authentication and authorization, OAuth is primarily an authorization protocol. You can learn more about OpenID Connect, a modification of OAuth which adds support for authentication.

What are the use cases?

SAML’s intended use case is based around complex enterprise environments as an authentication protocol although it does support authorization by the attribute query route. Its robust XML exchanges and comprehensive infrastructure make it excel in scenarios that necessitate centralized identity management, cross-domain SSO, and federated authentication. SAML’s strengths shine when integrating multiple different platforms, such as Enterprise Resource Planning (ERP) systems or Customer Relationship Management (CRM) platforms, where maintaining control over user access and data sharing is paramount.

OAuth, on the other hand, thrives in the realm of the social web and API-driven ecosystems as an authorization protocol. Its simplicity and focus on delegation make it an ideal choice for scenarios that require user consent and granular access controls. OAuth’s primary use cases revolve around enabling third-party application integration, empowering developers to leverage existing user bases and resources reducing login friction while maintaining privacy and security boundaries.

Security and Mechanisms

SAML relies on XML digital signatures and encryption techniques to ensure message integrity and confidentiality. It leverages X.509 certificates and Public Key Infrastructure (PKI) to establish trust between participating entities. SAML’s cryptographic mechanisms provide a solid foundation for enterprise-grade security, enabling secure communication between IdPs and SPs.

OAuth, with its token-based approach, relies on Transport Layer Security (TLS) to secure communication channels. By utilizing tokens, OAuth enables dynamic authorization decisions and fine-grained access control. Its flexible nature makes it well-suited for resource-constrained environments and API ecosystems, where lightweight and scalable security mechanisms are essential.

Conclusion

In the realm of authentication and authorization, choosing between SAML and OAuth boils down to your requirements. SAML, suits complex systems requiring centralized identity management with SSO while OAuth, with its simplicity and emphasis on delegated authorization, can thrive on multiple platforms like mobile and can leverage pre-existing social accounts to reduce login friction.

Authentication is ever-evolving, and it is essential to stay ahead of the latest developments and emerging protocols. Ultimately, the selection of SAML or OAuth depends on the specific requirements of the application or system, ensuring the chosen protocol aligns with the desired security, scalability, and user experience goals.

Migrating users without downtime in your service (The Lazy Migration Strategy)

SuperTokens — Mon, 31 Jul 2023 06:52:20 +0000

Introduction:

On the surface, migrating your users from one authentication solution to another seems simple enough. Remove the old authentication logic, integrate with the new authentication provider, and finally import the user profiles to the new identity provider. Theoretically, this process seems very simple but, depending on the scale of your user base and the complexity of your auth schema, the difficulty can spiral out of control.

Real world migration scenarios

WeTransfer

In 2021, WeTransfer decided to consolidate their fragmented user pools across their products into a single identity store, to improve the user experience and unify the billing system. In this article by Esteban Pintos, the Senior Backend Engineer at WeTransfer, he goes over their migration experiences and some of the challenges they faced when migrating 80 million users across 3 applications to Auth0. Here are the key challenges they faced:

WeTransfer needed SSO so users who had accounts in multiple products could log in with a single account. This meant that the authentication solution they were using needed to be extensible and customizable to allow for accounts to be linked from the legacy data stores during initial sign-in.
Additionally, there were rate limits imposed on the APi responsible for importing users. This meant they could not just do a simple bulk import of all users as it could take months and increases the likelihood of things going wrong.

In their approach, they split the migration into 2 phases:

Phase 1: Lazy Migration:

In this phase users sign in with the new auth provider but, the flow is modified to check if there are other associated accounts and link them.
These customizations need to be thoroughly tested so that error cases are handled and the users are not lost during migration #### Phase 2: Bulk Import:
Once the rate of users being migrated per day leveled out they initiated the second phase of their migration strategy which was to bulk import the remaining user accounts. A number of scripts had to be written in order to load and format the user profile data to be imported into Auth0 while being cognizant of the rate limits.

Parquet’s user migration from Auth0 to Supabase

In this article by Kevin Grüneberg, he goes over how they migrated users from Auth0 to Supabase. They had reached the end of Auth0’s startup plan and the revised pricing was too expensive, which resulted in the decision to migrate away from Auth0. Similarly, they had to go through similar processes like managing linked accounts and facilitating the password hash export but they faced an additional challenge since Supabase did not support an in house OAuth endpoint, so they had to build an in house solution to integrate with Circle, their community platform.

Migrating users when auth schema is inconsistent

Finally changes in the user auth schema between providers or within the same provider can also cause issues during migration as seen with Juan Alvardo and Aggelos Arvanitakis

Our experience of migrating customers over to SuperTokens:

At SuperTokens, we have helped hundreds of customers migrate to SuperTokens and are familiar with some of the common pitfalls users encounter during their migration. Here are some of the users we have migrated over

Built Intelligence

Originally using Auth0 as its provider, Built Intelligence was forced to switch to a new provider after Auth0 revised its pricing. The new pricing structure would increase Built Intelligence’s bill by nearly 700%. After evaluating a number of auth providers, they finally settled on using SuperTokens. Adrian, the Technical Director at Built Intelligence found the documentation to be straightforward forward and after speaking to the SuperTokens team they had he had a clear vision of how the migration should be implemented.It took them two weeks to prepare a POC and test the migration for a single user. Within the span of 4 weeks, they had all their users migrated over and removed the legacy provider from their product.

You can learn more about how Built Intelligence integrated with SuperTokens in our case study.

Poppy

For Poppy, they needed to make sure that the solution they were choosing had the extensibility required to meet their needs due to issues arising from fraudulent sms requests. Poppy opted for a Lazy migration strategy slowly migrating users over to SuperTokens over the course of 6 months. Once there were only a few thousand people left on Auth0, Poppy simply asked the remaining users to reset their passwords and was able to disable Auth0 completely.

You can learn more about Poppy integrated with SuperTokens in our case study.

Apart from these users we also had to make provisions for users who were migrating from Firebase Auth. Firebase uses a modified version of the scrypt password hashing algorithm. We had to update our import password hash API to support this algorithm to ensure a smooth migration experience.

Here are the most important takeaways from these user migration journeys:

Validate that the provider you are switching to has the features you need.
Make sure the auth schema of the new auth solution is compatible with the old one
Check that the password hashes are compatible with the new system and can be imported. (Inability to do so will result in all users having to reset their passwords)
Plan and test your migration strategy
Be cognizant of API rate limits. Services rate limit their APIs, which if not accounted for can result in import failures and user accounts not being transferred over.

In most of the examples seen above a commonly adopted strategy for migration is “Lazy Migration”, but, what exactly is that and how does it work?

Understanding Lazy Migration:

Lazy Migration refers to a phased and strategic approach to migrating systems, applications, or data. Rather than attempting a full-scale migration in one go, Lazy Migration breaks down the process into manageable steps. This method allows organizations to transfer specific components gradually, ensuring minimal downtime and reduced risks associated with complex migrations.

The Benefits of Lazy Migration:

Reduced Downtime: One of the primary advantages of Lazy Migration is the significant reduction in downtime. By migrating components incrementally, businesses can keep essential services operational while gradually shifting to the new environment. This eliminates the need for lengthy maintenance windows or service disruptions that could affect productivity and customer satisfaction.
Risk Mitigation: Lazy Migration minimizes the risk associated with large-scale migrations. By migrating in smaller increments, businesses can identify and address potential issues early on. This iterative approach enables effective troubleshooting, ensuring a smooth transition without jeopardizing critical operations or data integrity.
Flexibility and Adaptability: Lazy Migration allows organizations to adapt their migration strategy as needed. It allows for adjustments based on real-time feedback, enabling businesses to fine-tune their approach and address any unforeseen challenges efficiently. This adaptability ensures that the migration aligns with the organization's goals and timelines.
Cost Optimization: By avoiding a complete overhaul in one go, Lazy Migration can help businesses optimize costs. It allows for a more granular allocation of resources, enabling organizations to invest in migration efforts strategically. This cost optimization ensures that budgets are utilized efficiently while achieving the desired outcomes.

Conclusion:

By breaking down migrations into smaller, manageable steps, Lazy migration can reduce downtime, mitigate risks, optimize costs, and enhance the overall user experience when shifting to a new system.

Ory vs Keycloak vs SuperTokens

SuperTokens — Wed, 14 Jun 2023 06:50:00 +0000

Open-Source Authentication Providers

Compared to a couple of years ago, open-source authentication has seen huge progress. In this post, we’ll compare three of the leading open-source authentication providers - Ory, Keycloak, and SuperTokens.

Each of these providers has its own set of pros and cons. We’ll evaluate each independently and summarize the relative strengths and weaknesses towards the end of the post.

Ory Kratos / Ory Identities

Ory Kratos is an API-first identity and user management system. Ory also offers other products including:

Ory Hydra: OAuth 2.0 and OpenID Connect provider
Ory Oathkeeper: zero-trust networking proxy
Ory Keto: open-source implementation of Google’s Zanzibar. Among these products, we’ll focus on Kratos for its relevance to authentication.

Introduced in January 2020 as an open-source authentication and identity solution, Ory Kratos is now powering companies like Fandom. Since launch, the Ory team has rebranded the Kratos product to Ory Identities. To minimize confusion, we’ll continue using the Kratos name.

Advantages

Customizability: Developers have maximum control over their user journeys and the ability to self-host authentication. In particular, Ory Actions allows developers to integrate with custom applications or third-party services such as Stripe or Mailchimp to build custom business logic. These integrations can be triggered by any user-related event such as login, registration, account recovery, account verification, or user settings update.
Support: Unlike legacy authentication providers, Ory supplies a public slack server for developers to ask questions or get help with their implementation.

Disadvantages

Technical Customization complexity. Once deployed, basic changes such as changing the color scheme for authentication screens or understanding user management can be found at console.ory.sh. However, further customizations with third party integrations are limited to Ory Actions. These provide webhook triggers, as opposed to overriding the function/ API (SuperTokens). Depending on the implementation, these triggers may even require a separate automation service.
Features gated by enterprise. A couple of Ory’s features are limited to their enterprise plan that starts at $3000/month. In particular, a private slack channel with Ory engineers is priced at $500/month or bundled with the enterprise plan. SAML is limited to enterprise. And their 99.95% service level objective (SLO) is only available at the $690/month plan.
Compliance and hosting options. Current managed hosting options are limited to EU data regions and their SOC2 certifications is still underway. They do not offer SMS based 2FA

Ory Pricing

Self-hosting with Ory is free. As an open-source startup, Ory primarily makes money through their managed service called Ory Cloud. Pricing for Ory Cloud starts at -

Essentials plan - $29/month for 1,000 DAU and $30/1,000 DAU afterward.
Scale plan - $690/month for 20,000 DAU and $30/1,000 DAU afterward.
- Additional features include 99.95% SLO and multi-tenancy
Enterprise plan - $3,000/month for 20,000 DAU
- Additional features include dedicated support, SAML, and more.

Keycloak

Keycloak is an open source software product to allow single sign-on with identity and access management. Introduced in 2014, Keycloak was one of the first open-source implementations for sign sign-on. Since then, it’s become a broader open source identity and access management solution.

Keycloak’s age shows most in its features. Of the three providers, Keycloak has the richest feature set. For sophisticated developers looking to self-host an authentication solution with minimal customizations, Keycloak is a good bet. The tradeoff is that customizing a Keycloak system is authentication on hard mode.

Advantages

Feature set. Keycloak has nearly every authentication feature possible. From SSO to SAML to passwordless (minus SMS) to Kerberos, Keycloak’s off the shelf offering is incredibly wide. These features are available to everyone, no payment required.
History and stability. Keycloak has been around a long time. In 2018, it was adopted as the upstream project to Redhat’s SSO implementation - geared towards enterprise customers. As a result, Keycloak has been extremely stable with the potential to scale up to millions of users.

Disadvantages

Support. The biggest gripe that most Keycloak users have is support. There’s no official support channel and the documentation can be frustrating at times. While Keycloak has a large community of developers, given its small core staff, resolving issues can be iffy at best. Instead, many companies turn to consultancies that specialize in wrangling with Keycloak.
Customization. Part of why Keycloak needs so much support is the fact that there’s very little off-the-shelf customization possibilities. Changes in email to sign-up fields to basic user flow require meaningful amounts of engineering. And security features like SMS 2FA aren’t supported by Keycloak, requiring developers to patch an external service into Keycloak.
No managed service. Keycloak does not offer a managed service and hence if you want that optionality to start off with or for the future, then that is not possible.
Scaling concerns. While Keycloak has been proven to scale to millions of users, most companies at a large enough stage have trouble keeping up with the engineering required to customize Keycloak. Instead, they’ll need to engage with RH SSO (where pricing starts at $1,650 per month and goes up to $43,200 per month), or migrate out of Keycloak.

Pricing

Keycloak is entirely open-source and free to use. Developers will need to self-host their implementation.

SuperTokens

SuperTokens is an open-source authentication alternative to Auth0 / Firebase Auth / AWS Cognito. Introduced in 2020, SuperTokens manages tens of millions of customer identities.

SuperTokens was built to be the best of both build and buy. Companies often have to consider the opportunity cost and complexity in building their own authentication system but also the flexibility limitations of buying from an authentication provider.

SuperTokens makes it easy to implement authentication, with great extensibility options due to the unique frontend, backend, and core architecture.

Advantages

Speed of implementation. Setting up an authentication demo locally with SuperTokens is quick with their CLI tool. Support on SuperTokens’ Discord is responsive, with engineers from SuperTokens chiming in as little as a minute.
Customization. SuperTokens’ unique architecture allows the developer to pick and choose what functionality they want. Developers can even build atop React, Vanilla JS, and React Native SDKs to create the pixel-perfect authentication screen (for the full list of SuperTokens SDKs, refer to the Github page).
Authentication focused. SuperTokens is focused on authentication. Keycloak is a single product within Red Hat which is a part of the larger IBM organization. Ory has four distinct product lines including end point security and an implementation of Google’s Zanzibar - which all need to be managed simultaneously.

Disadvantages

Tech stack support. SuperTokens provides backend SDKs for Nodejs, Golang and Python. On the frontend, SuperTokens has Reactjs, VanillaJS, and React Native(only session management). For Angular and Vuejs, developers would need to build their own UI.
Feature maturity. SuperTokens is not as feature rich as some of the other alternatives - especially Keycloak
Additional integration: To provide the additional customisability, SuperTokens also requires developers to integrate SuperTokens backend SDK into their API layer

Pricing

Self-hosting with SuperTokens is free.

As an open-source startup, SuperTokens offers a managed service that abstracts the complexity with self-hosting.

Free if under 5,000 MAUs
2 cents per MAU or $20 per 1,000 MAU
Custom pricing available for enterprise

Choosing an Auth Provider

Compared to a couple of years ago, developers have far more choice in choosing an open-source authentication provider. All three are great options, used in production across startups and large enterprises alike.

By Github stars, SuperTokens is the fastest growing of the three and was one of the fastest growing open source companies in 2022. Keycloak is the oldest, most feature rich and is 100% free. Ory is somewhere in the middle of the two.

Django Bootstrap Login Template (How-To)

SuperTokens — Thu, 09 Mar 2023 10:47:10 +0000

High Level Refresher

Django is a high-level Python framework that follows the model-template-views architectural pattern. Django is one of the most popular web frameworks due to its security, scalability, and flexible design. Companies like Instagram, Reddit, and Dropbox all used Django.

Bootstrap is an open-source CSS framework that provides pre-built HTML, CSS, and JavaScript components. This includes elements such as navigation bars, forms, buttons, modals, and more. Originally created by Twitter, Bootstrap is now maintained by a large developer community.

Prerequisites

A basic understanding of HTML, CSS, and Javascript
A basic understanding of Django
Python3 installed on your machine
Django installed on your machine

Setting up a Django application

Let’s first create a project. In your command line, find the correct directory, and run the following command:

$ django-admin startproject django_login

This creates the project we’ll be working in. From there, we’ll need to create an application. Since we’re building a login screen, navigate into the project with cd django_login, and run the following command:

$ python3 manage.py startapp login

Let’s now run the server to test if everything has been set up correctly. Run the following command:

$ python3 manage.py runserver

By deploying our Django application, we can check in real-time if the build is compiling correctly. Since we have only initialized our Django application, in localhost:8000/, you should see the following webpage:

Below is a command-line screenshot of setting up a Django application from scratch

Editing Project Configs

django_login/settings.py

First, we’ll notify our project that we’ve created an application. To do this, go into the django_login folder and find the settings.py file. Scroll down to the INSTALLED_APPS section and add 'login' (our application name) to the list of applications.

django_login/urls.py

From there, we’ll need to edit the urls.py file to account for our new application. We will be using the built-in LoginView from Django which will display the login form and process the login action.

Replace the template code with the following:

from django.contrib import admin
from django.urls import path, include
from django.contrib.auth.views import LoginView

urlpatterns = [
    path('', LoginView.as_view()),
    path('login/', include('login.urls')),
    path('admin/', admin.site.urls),
]

Building the login screen with Bootstrap

login/templates/registration/login.html

First, within the login folder, we’ll need to create a templates folder, and then a registration folder within. From there, we’ll create a login.html file.

Because we’re using the built-in LoginView of Django, we must provide the HTML template with the registration/login.html format.

Inside login.html, we’ll add the following Bootstrap code (delivered via CDN for convenience, though there are other Bootstrap installation methods):


<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Signin</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-GLhlTQ8iRABdZLl6O3oVMWSktQOp6b7In1Zl3/Jr59b6EGGoI1aFkw7cmDA6j6gD" crossorigin="anonymous">    
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/js/bootstrap.bundle.min.js" integrity="sha384-w76AqPfDkMBDXo30jS1Sgez6pr3x5MlQ1ZAGC+nuZB+EYdgRZgiwxhTBTkF7CXvN" crossorigin="anonymous"></script>

  </head>
  <body class="text-center">
    <form class="form-signin">
      <h1 class="h3 mb-3 font-weight-normal">Django Login Demo</h1>
      {% csrf_token %}
      <input id="inputEmail" class="form-control" placeholder="Email address" required="" autofocus="" type="email">
      <input id="inputPassword" class="form-control" placeholder="Password" required="" type="password">
      <div class="checkbox mb-3">
        <label>
          <input value="remember-me" type="checkbox"> Remember me
        </label>
      </div>
      <button class="btn btn-lg btn-primary btn-block" type="submit">Sign in</button>
    </form>
  </body>
</html>

<style>
html,
body {
  height: 100%;
}

body {
  display: -ms-flexbox;
  display: -webkit-box;
  display: flex;
  -ms-flex-align: center;
  -ms-flex-pack: center;
  -webkit-box-align: center;
  align-items: center;
  -webkit-box-pack: center;
  justify-content: center;
  padding-top: 40px;
  padding-bottom: 40px;
  background-color: #f5f5f5;
}

.form-signin {
  width: 100%;
  max-width: 330px;
  padding: 15px;
  margin: 0 auto;
}

.form-signin .checkbox {
  font-weight: 400;
}

.form-signin .form-control {
  position: relative;
  box-sizing: border-box;
  height: auto;
  padding: 10px;
  font-size: 16px;
}

.form-signin .form-control:focus {
  z-index: 2;
}

.form-signin input[type="email"] {
  margin-bottom: -1px;
  border-bottom-right-radius: 0;
  border-bottom-left-radius: 0;
}

.form-signin input[type="password"] {
  margin-bottom: 10px;
  border-top-left-radius: 0;
  border-top-right-radius: 0;
}
</style>

login/views.py

Now that we have our HTML, we need to render it in Django. Go to the views.py file and replace the template code with the following:

from django.shortcuts import render

def index(request):
    return render(request, 'authentication/login.html')

Running the application

Once everything is set up, your login folder structure should look like this:

When we run python manage.py runserver, the following webpage should show up on your localhost.

Great success!

Conclusion

Congrats - you’ve created a login screen using Django with Bootstrap! You’ll still need to set up the authentication logic (hashing & storing the user credentials, session management, building the signup and forgot password screens, and redirecting post-login).

But for now - time to celebrate!

At SuperTokens, we simplify your authentication process - and help you set up a fully functioning Django authentication flow within minutes. Check us out or message us on Discord!

Forem: SuperTokens

Hacktoberfest with SuperTokens

What's Hacktoberfest?

SuperTokens at Hacktoberfest

How to contribute to the create-supertokens-app CLI

Other ways to contribute

Rewards

Conclusion

Adding login to your Next.js app using the app directory with SuperTokens

(Recommended) Use create-supertokens-app

Manually Setting up the Next.js project

Installing and setting up SuperTokens

Step 1: Initialise SuperTokens for our APIs

Step 2: Adding SuperTokens' API routes

Step 3: Adding SuperTokens to the frontend

Step 4: Adding SuperTokens routes to our frontend

Building our home page

Protecting your frontend routes

Protecting your API routes

Making network requests that require sessions

Signing users out of the application

Conclusion

How we used multi-tenancy to cut our AWS costs by 50%

What is multi-tenancy?

How we implemented SuperTokens Multi-tenancy

What are the benefits of the new architecture?

1. Cost Savings

2. Improved start-up time

Conclusion

How we cut our AWS costs by more than 50%

Introduction

What was the SuperTokens infrastructure like?

Initial Improvements to the deployment cycle

Why we had to change our deployment process

How to create an invite-only auth flow in 2023

Introduction

Setup

Step 1: Disable Sign Ups

Disable the sign up UI in SuperTokens Frontend config

Disable the sign up API in SuperTokens Backend config

Step 2: Creating the invite-only flow

Create a protected API that will create users and send invite links

Ensure that invited users have reset their passwords

Conclusion

URI vs URL: The real difference between the two

Introduction

URL (Uniform Resource Locator):

URI (Uniform Resource Identifier):

URN (Uniform Resource Name):

Conclusion

Understanding JWKS (JSON Web Key Set)

Introduction

What are JSON Web Keys (JWKs)?

Structure of the JWKS

How do JWKS work?

Benefits of Using JWKS

Considerations for JWKS implementation

Conclusion

Authentication vs Authorization: What's the difference?

Introduction:

The Foundation - What is Authentication?

Common methods of authentication include

Understanding Authorization

Why both matter

Best Practices for a Secure Future

Conclusion

SAML vs OAuth: Choosing the right protocol for authentication

Introduction

What is SAML and OAuth?

What are the use cases?

Security and Mechanisms

Conclusion

Migrating users without downtime in your service (The Lazy Migration Strategy)

Introduction:

Real world migration scenarios

WeTransfer

Phase 1: Lazy Migration:

Parquet’s user migration from Auth0 to Supabase

Migrating users when auth schema is inconsistent

Our experience of migrating customers over to SuperTokens:

How to contribute to the `create-supertokens-app` CLI

(Recommended) Use `create-supertokens-app`