Usage inside an iframe

Embed your website in an iframe with secure session management and custom storage handlers.

Overview

If your website can embed in an iframe that other websites consume, update your configuration based on this guide.

Before you start

If the sites where your iframe can embed share the same top-level domain as the iframe domain, then you can ignore this section.

Steps

1. Update the frontend configuration

Set isInIframe to true during Session.init on the frontend.
You need to use https during testing / dev for this to work. You can use tools like ngrok to create a dev env with https on your website / API domain.
Switch to using header based auth
Provide a custom windowHandler and a custom cookieHandler to ensure that the app works on safari and chrome incognito. These handlers switch from using document.cookies to localstorage to store tokens on the frontend (since safari doesn’t allow access to document.cookies in iframes), and use in-memory storage for chrome incognito (since chrome incognito doesn’t even allow access to localstorage). You can find implementations of these handlers here (windowHandler) and here (cookieHandler).

UI type

Pre-built UIDrop-in components that handle the flows for you.Custom UIBuild your own UI and call the SDK directly.

You need to make changes to the auth route configuration, as well as to the supertokens-web-js SDK configuration at the root of your application:

This change is in your auth route configuration.

import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    Session.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});

supertokensUIInit({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    supertokensUISession.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});

This change goes in the supertokens-web-js SDK configuration at the root of your application:

import SuperTokens from "supertokens-web-js";
import Session from "supertokens-web-js/recipe/session";

SuperTokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
  },
  recipeList: [
    Session.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});

import SuperTokens from "supertokens-web-js";
import Session from "supertokens-web-js/recipe/session";

SuperTokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
  },
  recipeList: [
    Session.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});

supertokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
  },
  recipeList: [
    supertokensSession.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});