docs: fixes and improvements to auth flow documentation (#8909)

2024-08-30 20:14:16 +03:00
parent 4350fe5368
commit c8f951dd89
5 changed files with 118 additions and 48 deletions
--- a/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
+++ b/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
@@ -3,16 +3,18 @@ sidebar_label: "Authentication Flows"
 ---

 export const metadata = {
-  title: `Authentication Flows with the Auth Provider`,
+  title: `Authentication Flows with the Auth Main Service`,
 }

 # {metadata.title}

-In this document, you'll learn how to use the Auth Provider's main service's methods to implement an authentication flow.
+In this document, you'll learn how to use the Auth Module's main service's methods to implement an authentication flow.

-## How to Register an Auth Identity
+## Authentication Methods

-The `register` method of the Auth Module's main service creates an auth identity that can be authenticated later.
+### Register
+
+The [register method of the Auth Module's main service](/references/auth/register) creates an auth identity that can be authenticated later.

 For example:

@@ -28,9 +30,7 @@ const data = await authModuleService.register(

 This method calls the `register` method of the provider specified in the first parameter and returns its data.

---
-
-## How to Authenticate a User
+### Authenticate

 To authenticate a user, you use the [authenticate method of the Auth Module's main service](/references/auth/authenticate). For example:

@@ -46,7 +46,11 @@ const data = await authModuleService.authenticate(

 This method calls the `authenticate` method of the provider specified in the first parameter and returns its data.

-### Basic Authentication Flow
+---
+
+## Auth Flow 1: Basic Authentication
+
+The basic authentication flow requires first using the `register` method, then the `authenticate` method.

 If the `authenticate` method returns the following object:

@@ -69,7 +73,11 @@ Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for

 ![Diagram showcasing the basic authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711373749/Medusa%20Resources/basic-auth_lgpqsj.jpg)

-### Authentication with Third-Party Service Flow
+---
+
+## Auth Flow 2: Third-Party Service Authentication
+
+The third-party service authentication method requires using the `authenticate` method first.

 If the `authenticate` method returns the following object:

@@ -84,7 +92,7 @@ It means the authentication process requires the user to perform an action with

 ![Diagram showcasing the first part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711374847/Medusa%20Resources/third-party-auth-1_enyedy.jpg)

-#### validateCallback
+### validateCallback

 Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.

--- a/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
+++ b/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
@@ -1,15 +1,54 @@
 export const metadata = {
-  title: `Authentication Route`,
+  title: `How to Use Authentication Routes`,
 }

 # {metadata.title}

 In this document, you'll learn about the authentication routes and how to use them to create or log-in users.

+<Note>
+
+These routes are added by Medusa's application layer, not the Auth Module.
+
+</Note>
+
+## Types of Authentication Flows
+
+### 1. Basic Authentication Flow
+
+This authentication flow doesn't require validation with third-party services.
+
+It requires the following steps:
+
+1. Registering the user with the [Register Route](#register-route).
+2. Authenticating the user with the [Auth Route](#auth-route).
+
+### 2. Third-Party Service Authenticate Flow
+
+This authentication flow authenticates the user with a third-party service, such as Google.
+
+It requires the following steps:
+
+1. Authenticate the user with the [Auth Route](#auth-route).
+2. If the authentication requires more action with the third-party service:
+    1. The auth route redirects to the third-party service's authentication portal. The URL is returned by the Auth Module Provider.
+    2. Once the authentication with the third-party service finishes, it redirects back to the [Callback Route](#callback-route). So, make sure your third-party service is configured to redirect to the [Callback Route](#callback-route).
+    3. If the callback validation is successful, you'll receive the authentication token.
+
+You may then use the [Auth Route](#auth-route) for subsequent authentication.
+
+---
+
 ## Register Route

 The Medusa application defines an API route at `/auth/{actor_type}/{provider}/register` that creates an auth identity for an actor type, such as a `customer`. It returns a JWT token that you pass to an API route that creates the user.

+<Note>
+
+This API route is useful for providers like `emailpass` that uses custom logic to authenticate a user. For authentication providers that authenticate with third-party services, such as Google, use the [Auth Route](#auth-route) instead.
+
+</Note>
+
 For example, if you're registering a customer, you:

 1. Send a request to `/auth/customer/emailpass/register` to retrieve the registration JWT token.
@@ -79,4 +118,41 @@ If the authentication is successful, you'll receive a `token` field in the respo

 [How to login Customers using the authentication route](../../../storefront-development/customers/login/page.mdx).

-</Note>
+</Note>
+
+---
+
+## Validate Callback Route
+
+The Medusa application defines an API route at `/auth/{actor_type}/{provider}/callback` that's useful for authenticating users with third-party services, such as Google.
+
+When integrating with a third-party service, you use [Auth Route](#auth-route) first to authenticate the user. If the authentication requires more action with the third-party provider, the request redirects to the authentication provider's authentication portal.
+
+<Note title="Tip">
+
+The URL of the authentication portal is received from the Auth Module Provider.
+
+</Note>
+
+Once the authentication with the third-party provider finishes, it should redirect back to this API route. So, make sure to add the necessary configuration in your provider to ensure this flow.
+
+### Path Parameters
+
+Its path parameters are:
+
+- `{actor_type}`: the actor type of the user you're authenticating. For example, `customer`.
+- `{provider}`: the auth provider to handle the authentication. For example, `google`.
+
+### Request Body Parameters
+
+This route accepts in the request body the data from the third-party service, and passes it along to the authentication provider to validate whether the customer was authenticated.
+
+### Response Fields
+
+If the authentication is successful, you'll receive a `token` field in the response body object:
+
+```json
+{
+  "token": "..."
+}
+```
--- a/www/apps/resources/generated/edit-dates.mjs
+++ b/www/apps/resources/generated/edit-dates.mjs
@@ -1,7 +1,7 @@
 export const generatedEditDates = {
  "app/commerce-modules/auth/auth-providers/emailpass/page.mdx": "2024-07-04T17:26:03+03:00",
  "app/commerce-modules/auth/auth-providers/page.mdx": "2024-07-01T10:21:19+03:00",
-  "app/commerce-modules/auth/authentication-route/page.mdx": "2024-06-13T12:21:54+03:00",
+  "app/commerce-modules/auth/authentication-route/page.mdx": "2024-08-30T12:23:50.176Z",
  "app/commerce-modules/auth/examples/page.mdx": "2024-07-04T17:26:03+03:00",
  "app/commerce-modules/auth/module-options/page.mdx": "2024-07-04T17:26:03+03:00",
  "app/commerce-modules/auth/page.mdx": "2024-08-05T07:24:27+00:00",
@@ -224,7 +224,7 @@ export const generatedEditDates = {
  "app/page.mdx": "2024-08-13T08:51:20+02:00",
  "app/commerce-modules/auth/auth-providers/_google/page.mdx": "2024-07-04T17:26:03+03:00",
  "app/commerce-modules/auth/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
-  "app/commerce-modules/auth/auth-flows/page.mdx": "2024-06-26T07:55:59+00:00",
+  "app/commerce-modules/auth/auth-flows/page.mdx": "2024-08-30T12:27:07.160Z",
  "app/commerce-modules/auth/_events/page.mdx": "2024-07-03T19:27:13+03:00",
  "app/commerce-modules/auth/auth-identity-and-actor-types/page.mdx": "2024-07-31T17:01:33+03:00",
  "app/commerce-modules/api-key/page.mdx": "2024-08-05T07:24:27+00:00",
--- a/www/apps/resources/generated/sidebar.mjs
+++ b/www/apps/resources/generated/sidebar.mjs
@@ -259,26 +259,18 @@ export const generatedSidebar = [
              {
                "loaded": true,
                "isPathHref": true,
-                "type": "sub-category",
-                "title": "Auth Flows",
-                "children": [
-                  {
-                    "loaded": true,
-                    "isPathHref": true,
-                    "type": "link",
-                    "path": "/commerce-modules/auth/authentication-route",
-                    "title": "Using API Routes",
-                    "children": []
-                  },
-                  {
-                    "loaded": true,
-                    "isPathHref": true,
-                    "type": "link",
-                    "path": "/commerce-modules/auth/auth-flows",
-                    "title": "Using Module's Service",
-                    "children": []
-                  }
-                ]
+                "type": "link",
+                "path": "/commerce-modules/auth/auth-flows",
+                "title": "Auth Flow with Module",
+                "children": []
+              },
+              {
+                "loaded": true,
+                "isPathHref": true,
+                "type": "link",
+                "path": "/commerce-modules/auth/authentication-route",
+                "title": "Auth Flow with Routes",
+                "children": []
              }
            ]
          },
--- a/www/apps/resources/sidebar.mjs
+++ b/www/apps/resources/sidebar.mjs
@@ -129,20 +129,14 @@ export const sidebar = sidebarAttachHrefCommonOptions([
                ],
              },
              {
-                type: "sub-category",
-                title: "Auth Flows",
-                children: [
-                  {
-                    type: "link",
-                    path: "/commerce-modules/auth/authentication-route",
-                    title: "Using API Routes",
-                  },
-                  {
-                    type: "link",
-                    path: "/commerce-modules/auth/auth-flows",
-                    title: "Using Module's Service",
-                  },
-                ],
+                type: "link",
+                path: "/commerce-modules/auth/auth-flows",
+                title: "Auth Flow with Module",
+              },
+              {
+                type: "link",
+                path: "/commerce-modules/auth/authentication-route",
+                title: "Auth Flow with Routes",
              },
            ],
          },