Add oauth docs

v2/docusaurus.config.js

@@ -256,6 +256,20 @@ module.exports = {
         beforeDefaultRemarkPlugins,
       },
     ],
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "oauth",
+        path: "oauth",
+        routeBasePath: "docs/oauth",
+        sidebarPath: require.resolve("./oauth/sidebars.js"),
+        showLastUpdateTime: true,
+        editUrl: "https://github.com/supertokens/docs/tree/master/v2/",
+        remarkPlugins: remarkPlugins,
+        rehypePlugins: rehypePlugins,
+        beforeDefaultRemarkPlugins,
+      },
+    ],
     [
       "@docusaurus/plugin-content-docs",
       {

v2/oauth/create-an-authentication-provider.mdx

@@ -0,0 +1,166 @@
+---
+title: Create an authentication provider
+hide_title: true
+---
+
+import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"
+import TabItem from '@theme/TabItem';
+import CoreInjector from "/src/components/coreInjector"
+import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs"
+
+# Multiple Frontend Domains Using a Single Backend
+
+You can use the following guide if you have multiple **`frontend applications`** on different domains, that use the same **`backend service`**.
+
+Using the actual **OAuth 2.0** terminology, we can say that each **`frontend`** can be considered a [**Client**](/docs/oauth/introduction#client) and the **`backend`** will act as both an [**Authorization Server**](/docs/oauth/introduction#authorization) and a [**Resource Server**](/docs/oauth/introduction#resource-server).
+
+:::info
+This guide assumes that you already have setup and configured **SuperTokens** in your [**Authentication Service**](/docs/oauth/introduction#authentication-service). 
+
+For more information on how to do that please check our [quickstart guide](/docs/thirdparty/introduction).
+:::
+
+## 1. Create the OAuth2 Clients
+
+For each of your **`frontend`** applications you will have to create a separate [**OAuth2 client**](/docs/oauth/introduction#client).
+This can be done by directly calling the **SuperTokens Core** API.
+
+<CoreInjector defaultValue="https://example.com">
+
+```bash
+curl -X POST ^{coreInjector_uri_without_quotes}/recipe/oauth2/admin/clients \
+  -H "Content-Type: application/json" \
+  -H "api-key: ^{coreInjector_api_key_without_quotes}" \
+  -d '{
+      "client_name": "<YOUR_CLIENT_NAME>",
+      "response_types": ["code", "id_token"],
+      "grant_types": ["authorization_code", "refresh_token"],
+      "redirect_uri": ["https://<YOUR_DOMAIN>.com/oauth/callback"]
+    }'
+```
+
+</CoreInjector>
+
+
+- `client_name` - A human-readable name of the client that will be presented to the [**end-user**](/docs/oauth/introduction#authorization) during authorization.
+- `response_types` - Specifies the types of responses your client expects from the Authorization Server.
+    - `code`: Indicates that the [**Client**](/#authorization) will receive an [**Authorization Code**](/#authorization) that will be exchanged for an [**Access Token**](/#authorization).
+    - `id_token`: Indicates that the [**Client**](/#authorization) expects an [**ID Token**](/#authorization)
+- `grant_types` - The grant types that the [**Client**](/#authorization) will use. 
+    - `authorization_code`: Allows exchanging the [**Authorization Code**](/#authorization) for an [**Access Token**](/#authorization).
+    - `refresh_token`: Allows exchanging the [**Refresh Token**](/#authorization) for a new [**Access Token**](/#authorization).
+- `redirect_uri` - A list of URIs to which the [**Authorization Server**](/#authorization) will send the user-agent (browser) after completing the authorization step
+
+If the creation was successful, the response will return a `201` status code.
+The response body will contain a **`client_id`** field which you will need to use in the next steps.
+
+## 2. Initialize the OAuth2 recipes on the backend
+
+
+In your **`backend`** application you will need to initialize both the **OAuth2Provider** and the **OAuth2Client** recipes.
+
+<BackendSDKTabs>
+<TabItem value="nodejs">
+
+```typescript
+import supertokens from "supertokens-node";
+import OAuth2Provider from"supertokens-node/recipe/oauth2provider";
+import OAuth2Client from"supertokens-node/recipe/oauth2client";
+
+supertokens.init({
+    framework: "express",
+    supertokens: {
+        connectionURI: "<YOUR_CONNECTION_URI>",
+        apiKey: "<YOUR_API_KEY>",
+    },
+    appInfo: {
+        appName: "",
+        apiDomain: "<YOUR_API_DOMAIN>",
+        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
+        apiBasePath: "/auth",
+        websiteBasePath: "/auth"
+    },
+    recipeList: [
+        OAuth2Provider.init(),
+        // You will have to initialize the OAuth2Client recipe
+        // for each of your previously created clients 
+        OAuth2Client.init({
+          clientId: '<CLIENT_ID>',
+          oidcDiscoveryEndpoint: 'https://<AUTHENTICATION_SERVICE_DOMAIN>/auth/.well-known/openid-configuration'
+        }),
+    ]
+});
+```
+
+</TabItem>
+
+<TabItem value="go">
+
+:::caution
+
+At the moment we do not have support creating OAuth2 providers in the Go SDK.
+
+:::
+
+</TabItem>
+
+<TabItem value="python">
+
+:::caution
+
+At the moment we do not have support creating OAuth2 providers in the Python SDK.
+
+:::
+
+</TabItem>
+
+</BackendSDKTabs>
+
+## 3. Initialize the recipe on the Frontend Applications
+
+:::info
+
+The `OAuth2Provider` recipe is available, at the moment, only when using the `supertokens-auth-react` package.
+
+:::
+
+Initialize the `OAuth2Provider` recipe on the frontend of each of your applications, ensuring you set the `authMode` to `header`.
+
+```tsx
+import OAuth2Provider from "supertokens-auth-react/recipe/oauth2provider";
+import Session from "supertokens-auth-react/recipe/session";
+
+
+export const SuperTokensConfig = {
+    appInfo: {
+        appName: "App Name",
+        apiDomain: "<AUTHENTICATION_SERVICE_DOMAIN>",
+        websiteDomain: "<FRONTEND_APPLICATION_DOMAIN>",
+    },
+    recipeList: [
+        OAuth2Provider.init({ authMode: "header" }),
+        Session.init(),
+    ],
+};
+```
+
+## 4. Update the login flow in your frontend applications
+
+In your `frontend applications` you will have to add a login action that will direct the user to the authentication page.
+You can just use a link for that. The link should be structured like this:
+
+```
+<AUTHENTICATION_SERIVICE_DOMAIN>/auth/oauth/auth?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>
+```
+- `<AUTHENTICATION_SERIVICE_DOMAIN>` - The domain of your [**Authentication Service**](/docs/oauth/introduction#authentication-service).
+The example assumes that you didn't overwrite the default `apiBasePath`.
+If that's the case you will have to replace `/auth` with you custom base path.
+- `<CLIENT_ID>` - The corresponding client ID based on what you have created in the first step.
+- `<REDIRECT_URI>` - The corresponding redirect URI based on what you have created in the first step.
+
+## 5. Test the new authentication flow
+
+With everything set up, you can now test your login flow.
+Just use the link that you have created in the previous step and try to access a protected resource.
+
+

v2/oauth/customizations/add-custom-claims-in-tokens.mdx

@@ -0,0 +1,9 @@
+---
+title:  Add Custom Claims in Tokens
+hide_title: true
+---
+
+# Add custom claims in the ID / access token 
+
+If you want to properties in the token payloads you can do this by overriding either the `buildIdTokenPayload` or the `buildAccessTokenPayload` functions.
+

v2/oauth/customizations/custom-ui.mdx

@@ -0,0 +1,6 @@
+---
+title:  Implement a Custom UI
+hide_title: true
+---
+
+# Implement a Custom UI

v2/oauth/customizations/verify-tokens.mdx

@@ -0,0 +1,9 @@
+---
+title: Verify Tokens
+hide_title: true
+---
+
+# Verify Tokens
+
+
+

v2/oauth/customizations/working-with-scopes.mdx

@@ -0,0 +1,29 @@
+---
+title: Working with Scopes
+hide_title: true
+---
+
+# Working with Scopes
+
+The allowed scopes are set during the creation process of an **OAuth2 Client**.
+
+By default, our **OAuth2** implementation adds the following built-in scopes:
+- `email`: adds the `email` and `email_verified` claims into the Id Token and the User Info.
+- `phoneNumber`: adds the `phoneNumber` and `phoneNumber_verified` claims into the Id Token and the User Info
+- `roles`: adds the roles claim into the Id Token and Access Token.
+   - This will contain the roles returned by `getRolesForUser`
+   - This only works if the `UserRoles` recipe is initialized
+- `permissions`: adds the `permissions` claim into the Id Token and Access Token.
+   - This will contain the list of permissions obtained by concatenating the result of `getPermissionsForRole` for all roles returned by `getRolesForUser`
+   - This only works if the `UserRoles` recipe is initialized
+
+## Requesting Specific Scopes
+
+The client can request specific scopes by adding `scope` query param to the Authorization URL.
+The requested scopes have to be a subset of what is allowed for the client, otherwise the authentication requst will fail.
+By default all scopes are granted to the client.
+
+## Overriding granted scopes
+
+If you want to manually modify the list of scopes that are granted to the client during the authentication flow you can do this by using overrides.
+You will have to add a custom implementation for `getConsentRequest` and change the value it returns for `requestedScope`.