diff --git a/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx b/www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
index 56d429c588..5762321e03 100644
--- 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
-### 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
-#### 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.
diff --git a/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx b/www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
index 116c29fdd0..288995623e 100644
--- 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.
+
+
+These routes are added by Medusa's application layer, not the Auth Module.
+
+
+
+## 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.
+
+
+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.
+
+
+
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).
-
\ No newline at end of file
+
+
+---
+
+## 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.
+
+
+
+The URL of the authentication portal is received from the Auth Module Provider.
+
+
+
+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": "..."
+}
+```
\ No newline at end of file
diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs
index dd4015da6b..26436fea71 100644
--- 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",
diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs
index 0795d27cfa..4b20eff7a1 100644
--- 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": []
}
]
},
diff --git a/www/apps/resources/sidebar.mjs b/www/apps/resources/sidebar.mjs
index d828b9b61f..52ceeb8b17 100644
--- 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",
},
],
},