Merge pull request #727 from supertokens/appinfo-refactor

Appinfo refactor

v2/emailpassword/common-customizations/multiple-clients.mdx

@@ -0,0 +1,124 @@
+---
+id: multiple-clients
+title: Setting up multiple frontends for one backend
+hide_title: true
+---
+
+<!-- COPY DOCS -->
+<!-- ./thirdpartyemailpassword/common-customizations/multiple-clients.mdx -->
+
+import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"
+import TabItem from '@theme/TabItem';
+
+# Setting up multiple frontends for one backend
+
+Many a times, you have a setup where different frontend clients query the same backend. For example, this can happen in the case of a mobile app and a web app - both of these types of clients query the same backend. Another common use case is that you may have a common testing backend that is shared across local frontend development (on `localhost`), and a staging / testing frontend (on `test.yoursite.com`).
+
+In all these cases, the location of the different frontend clients are different. In case of a mobile app, it can be a deep link to the app, in case of local development, it can be `http://localhost:3000`, for staging, it can be `https://test.yoursite.com`, etc. Not only is the domain different, but so is the protocol (http vs https).
+
+All of these have an impact on the functioning of SuperTokens. For example, if your frontend is on `localhost` and your API is `api.example.com`, then the `cookieSameSite` value for sessions should resolve to `none`, whereas if the frontend is on `test.example.com`, then the `cookieSameSite` value should resolve to `lax`. Another example is the effect on magic links, password reset or email verification links - the domains and protocols of these would need to change based on the frontend that is querying - if the query is coming from the `localhost` site, then the link URL would be `http:localhost...`, whereas if it's coming from the test site, it would be `https://test.example.com...`.
+
+## Step 1: Define a dynamic origin on the backend
+
+In order to facilitate this, we allow you to configure an `origin` function on the backend which takes in the request object, and returns a string representing the domain of the request:
+
+<BackendSDKTabs>
+<TabItem value="nodejs">
+
+```tsx
+import supertokens from "supertokens-node";
+
+supertokens.init({
+    appInfo: {
+        appName: "...",
+        apiDomain: "...",
+        // highlight-start
+        origin: (input) => {
+            if (input.request !== undefined) {
+                let origin = input.request.getHeaderValue("origin");
+                if (origin === undefined) {
+                    // this means the client is in an iframe, it's a mobile app, or
+                    // there is a privacy setting on the frontend which doesn't send
+                    // the origin
+                } else {
+                    if (origin === "https://test.example.com") {
+                        // query from the test site
+                        return "https://test.example.com";
+                    } else if (origin === "http://localhost:3000") {
+                        // query from local development
+                        return "http://localhost:3000";
+                    }
+                }
+            }
+            // in case the origin is unknown or not set, we return a default
+            // value which will be used for this request.
+            return "https://test.example.com";
+        }
+        // highlight-end
+    },
+    supertokens: {
+        connectionURI: "...",
+    },
+    recipeList: [/* ... */]
+})
+```
+
+</TabItem>
+
+<TabItem value="go">
+
+:::note
+Coming Soon
+:::
+
+</TabItem>
+<TabItem value="python">
+
+:::note
+Coming Soon
+:::
+
+</TabItem>
+</BackendSDKTabs>
+
+- We remove the `websiteDomain` config in the `appInfo` config, and replace it with the `origin` config as shown above.
+- The `origin` config is a function that takes an optional request object, and returns a string representing the domain of the request. We first check for if the `request` is not provided, and if not, then we fallback on a default value. If it is provided, then we attempt to read the `origin` header from the request and return a domain based on that.
+- There may be cases where the `origin` header is not set, in which case we fallback on the default value once again. This can happen for:
+    - Mobile app frontends.
+    - Frontend in an iframe
+    - Privacy setting on the frontend.
+    In these cases, you may want to set a custom prop in all requests (in the URL as a query param) indicating the type of client, read that from the request object above and return a domain based on that.
+- There are several cases where the input request object may not be provided:
+    - In case you are calling a function like `EmailVerification.createEmailVerificationLink` manually from your APIs.
+    - In case of certain dashboard actions like sending an email verification link - here the request object is omited cause the origin will be that of the dashboard and not your frontend app.
+
+    Therefore, in these cases, it makes sense to fallback on a sensible default.
+
+:::caution
+Do not return the `origin` header as is because it can result in an attack wherein an attacker can inject their custom origin header value in the request, and the links generated (for example for password reset) would then point to their custom origin.
+
+Instead, as shown above, check for each known origin explicitly (including port and protocol), and return only known values. 
+:::
+
+## Step 2: Determine the right method for sending session tokens (cookies vs auth header)
+
+:::important
+This section is only applicable for browser based frontend config.
+:::
+
+By default, browser based apps use cookies for session tokens which are saved against the API domain. Keeping this in mind, you need to think through the right setting for [token transfer method](./sessions/token-transfer-method) based on the following scenarios:
+
+- If users can login to multiple frontends at the same time: 
+    - Via login forms on each of those frontends:
+        - For example, you have two websites: `a.example.com` and `b.example.com` (or `app1.com` and `app2.com`), and both have their respective login forms on which users can login. Both of these query the same `apiDomain` (for example, `api.example.com`). In this case, you should use header based auth and not cookie based. If you use cookie based auth, then logging into the second site will overwrite the tokens from the first site since the session tokens are saved against the api domain (which is the same for both). Using header based auth, the tokens will be saved against the frontend domains which are both different, allowing users to be logged into both the sites at the same time.
+    - Via a common login form:
+        - For example, you have `auth.example.com` which logs users into `a.example.com` and `b.example.com`. In this case, you can use cookie based sessions, with the [sub domain sharing feature](./sessions/share-sessions-across-sub-domains) enabled.
+        - If the domains are not sub domains and are entirely different base domains (like `app1.com` and `app2.com`), then you need to use SuperTokens as an OAuth provider. This feature is coming soon.
+
+- If users should not login to multiple frontends at the same time:
+    - For example, you have `test.example.com` for your staging site and `localhost:3000` for your local dev site. Both use the same `apiDomain` of `api.example.com`. In this case, you don't really care what happens if a user logs into both of these sites together. In this case, the login from the second site will overwrite the one from the first site, and that's OK. So you can continue to use cookie based auth.
+
+- If your frontend and api are on different base domains:
+    - If your frontend is on `app1.com` and your `apiDomain` is on `api.example.com`, they are said to be on different base domains. Another example is the frontend being on `localhost` and the `apiDomain` being on `api.example.com`.
+    - In this case, using cookie based auth will not work on browsers like Safari, or chrome incognito (since by default, they disallow third party cookies). So you should use header based auth instead. SuperTokens allows you to [choose header based auth for some sites, and cookies for others](./sessions/token-transfer-method). 
+    - Note that if the two domains are sub domains, or the same domain but with differnet ports, then they are considered to be on the same base domain and won't have any issues with cookie based auth.

v2/emailpassword/sidebars.js

@@ -488,6 +488,7 @@ module.exports = {
             "common-customizations/changing-base-path/api-base-path"
           ]
         },
+        "common-customizations/multiple-clients",
         "common-customizations/userid-format",
         {
           type: 'category',

v2/passwordless/common-customizations/multiple-clients.mdx

@@ -0,0 +1,124 @@
+---
+id: multiple-clients
+title: Setting up multiple frontends for one backend
+hide_title: true
+---
+
+<!-- COPY DOCS -->
+<!-- ./thirdpartyemailpassword/common-customizations/multiple-clients.mdx -->
+
+import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"
+import TabItem from '@theme/TabItem';
+
+# Setting up multiple frontends for one backend
+
+Many a times, you have a setup where different frontend clients query the same backend. For example, this can happen in the case of a mobile app and a web app - both of these types of clients query the same backend. Another common use case is that you may have a common testing backend that is shared across local frontend development (on `localhost`), and a staging / testing frontend (on `test.yoursite.com`).
+
+In all these cases, the location of the different frontend clients are different. In case of a mobile app, it can be a deep link to the app, in case of local development, it can be `http://localhost:3000`, for staging, it can be `https://test.yoursite.com`, etc. Not only is the domain different, but so is the protocol (http vs https).
+
+All of these have an impact on the functioning of SuperTokens. For example, if your frontend is on `localhost` and your API is `api.example.com`, then the `cookieSameSite` value for sessions should resolve to `none`, whereas if the frontend is on `test.example.com`, then the `cookieSameSite` value should resolve to `lax`. Another example is the effect on magic links, password reset or email verification links - the domains and protocols of these would need to change based on the frontend that is querying - if the query is coming from the `localhost` site, then the link URL would be `http:localhost...`, whereas if it's coming from the test site, it would be `https://test.example.com...`.
+
+## Step 1: Define a dynamic origin on the backend
+
+In order to facilitate this, we allow you to configure an `origin` function on the backend which takes in the request object, and returns a string representing the domain of the request:
+
+<BackendSDKTabs>
+<TabItem value="nodejs">
+
+```tsx
+import supertokens from "supertokens-node";
+
+supertokens.init({
+    appInfo: {
+        appName: "...",
+        apiDomain: "...",
+        // highlight-start
+        origin: (input) => {
+            if (input.request !== undefined) {
+                let origin = input.request.getHeaderValue("origin");
+                if (origin === undefined) {
+                    // this means the client is in an iframe, it's a mobile app, or
+                    // there is a privacy setting on the frontend which doesn't send
+                    // the origin
+                } else {
+                    if (origin === "https://test.example.com") {
+                        // query from the test site
+                        return "https://test.example.com";
+                    } else if (origin === "http://localhost:3000") {
+                        // query from local development
+                        return "http://localhost:3000";
+                    }
+                }
+            }
+            // in case the origin is unknown or not set, we return a default
+            // value which will be used for this request.
+            return "https://test.example.com";
+        }
+        // highlight-end
+    },
+    supertokens: {
+        connectionURI: "...",
+    },
+    recipeList: [/* ... */]
+})
+```
+
+</TabItem>
+
+<TabItem value="go">
+
+:::note
+Coming Soon
+:::
+
+</TabItem>
+<TabItem value="python">
+
+:::note
+Coming Soon
+:::
+
+</TabItem>
+</BackendSDKTabs>
+
+- We remove the `websiteDomain` config in the `appInfo` config, and replace it with the `origin` config as shown above.
+- The `origin` config is a function that takes an optional request object, and returns a string representing the domain of the request. We first check for if the `request` is not provided, and if not, then we fallback on a default value. If it is provided, then we attempt to read the `origin` header from the request and return a domain based on that.
+- There may be cases where the `origin` header is not set, in which case we fallback on the default value once again. This can happen for:
+    - Mobile app frontends.
+    - Frontend in an iframe
+    - Privacy setting on the frontend.
+    In these cases, you may want to set a custom prop in all requests (in the URL as a query param) indicating the type of client, read that from the request object above and return a domain based on that.
+- There are several cases where the input request object may not be provided:
+    - In case you are calling a function like `EmailVerification.createEmailVerificationLink` manually from your APIs.
+    - In case of certain dashboard actions like sending an email verification link - here the request object is omited cause the origin will be that of the dashboard and not your frontend app.
+
+    Therefore, in these cases, it makes sense to fallback on a sensible default.
+
+:::caution
+Do not return the `origin` header as is because it can result in an attack wherein an attacker can inject their custom origin header value in the request, and the links generated (for example for password reset) would then point to their custom origin.
+
+Instead, as shown above, check for each known origin explicitly (including port and protocol), and return only known values. 
+:::
+
+## Step 2: Determine the right method for sending session tokens (cookies vs auth header)
+
+:::important
+This section is only applicable for browser based frontend config.
+:::
+
+By default, browser based apps use cookies for session tokens which are saved against the API domain. Keeping this in mind, you need to think through the right setting for [token transfer method](./sessions/token-transfer-method) based on the following scenarios:
+
+- If users can login to multiple frontends at the same time: 
+    - Via login forms on each of those frontends:
+        - For example, you have two websites: `a.example.com` and `b.example.com` (or `app1.com` and `app2.com`), and both have their respective login forms on which users can login. Both of these query the same `apiDomain` (for example, `api.example.com`). In this case, you should use header based auth and not cookie based. If you use cookie based auth, then logging into the second site will overwrite the tokens from the first site since the session tokens are saved against the api domain (which is the same for both). Using header based auth, the tokens will be saved against the frontend domains which are both different, allowing users to be logged into both the sites at the same time.
+    - Via a common login form:
+        - For example, you have `auth.example.com` which logs users into `a.example.com` and `b.example.com`. In this case, you can use cookie based sessions, with the [sub domain sharing feature](./sessions/share-sessions-across-sub-domains) enabled.
+        - If the domains are not sub domains and are entirely different base domains (like `app1.com` and `app2.com`), then you need to use SuperTokens as an OAuth provider. This feature is coming soon.
+
+- If users should not login to multiple frontends at the same time:
+    - For example, you have `test.example.com` for your staging site and `localhost:3000` for your local dev site. Both use the same `apiDomain` of `api.example.com`. In this case, you don't really care what happens if a user logs into both of these sites together. In this case, the login from the second site will overwrite the one from the first site, and that's OK. So you can continue to use cookie based auth.
+
+- If your frontend and api are on different base domains:
+    - If your frontend is on `app1.com` and your `apiDomain` is on `api.example.com`, they are said to be on different base domains. Another example is the frontend being on `localhost` and the `apiDomain` being on `api.example.com`.
+    - In this case, using cookie based auth will not work on browsers like Safari, or chrome incognito (since by default, they disallow third party cookies). So you should use header based auth instead. SuperTokens allows you to [choose header based auth for some sites, and cookies for others](./sessions/token-transfer-method). 
+    - Note that if the two domains are sub domains, or the same domain but with differnet ports, then they are considered to be on the same base domain and won't have any issues with cookie based auth.

v2/passwordless/sidebars.js

@@ -472,6 +472,7 @@ module.exports = {
             "common-customizations/changing-base-path/api-base-path"
           ]
         },
+        "common-customizations/multiple-clients",
         "common-customizations/userid-format",
         {
           type: 'category',

v2/src/plugins/codeTypeChecking/jsEnv/package.json

@@ -53,7 +53,7 @@
     "socket.io": "^4.6.1",
     "socketio": "^1.0.0",
     "supertokens-auth-react": "^0.35.0",
-    "supertokens-node": "^16.1.0",
+    "supertokens-node": "^16.3.0",
     "supertokens-node7": "npm:[email protected]",
     "supertokens-react-native": "^4.0.0",
     "supertokens-web-js": "^0.8.0",