asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: update auth docs + add new storefront guides (#9020)

Browse Source 
* docs: update auth docs + add new storefront guides

* lint content

* fix vale error

* add callback response schema

* Update www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx

Co-authored-by: Stevche Radevski <sradevski@live.com>

* Update www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx

Co-authored-by: Stevche Radevski <sradevski@live.com>

* Update www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx

Co-authored-by: Stevche Radevski <sradevski@live.com>

* address PR comments

* replace google -> github

* better explanation for refresh token

---------

Co-authored-by: Stevche Radevski <sradevski@live.com>
This commit is contained in:
Shahed Nasser
2024-09-06 15:26:10 +03:00
committed by GitHub
co-authored by Stevche Radevski
parent cf3c25addf
commit a28c911c24
29 changed files with 1476 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
+62 -33
View File
@@ -50,24 +50,38 @@ This method calls the `authenticate` method of the provider specified in the fir
## 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:
The basic authentication flow requires first using the `register` method, then the `authenticate` method:
```ts
data = {
success: true,
authIdentity: {
const { success, authIdentity } = await authModuleService.register(
"emailpass",
// passed to auth provider
{
// ...
},
}
)
// later (can be another route for log-in)
const { success, authIdentity, location } = await authModuleService.authenticate(
"emailpass",
// passed to auth provider
{
// ...
}
)
if (success && !location) {
// user is authenticated
}
```
Then, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
If `success` is true and `location` isn't set, the user is authenticated successfully, and their authentication details are available within the `authIdentity` object.
The next section explains the flow if `location` is set.
<Note>
Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for the expected properties in `authIdentity`.
Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for the received properties in `authIdentity`.
</Note>
@@ -77,18 +91,31 @@ Check out the [AuthIdentity](/references/auth/models/AuthIdentity) reference for
## 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:
The third-party service authentication method requires using the `authenticate` method first:
```ts
data = {
success: true,
location: "https://....",
const { success, authIdentity, location } = await authModuleService.authenticate(
"emailpass",
// passed to auth provider
{
// ...
}
)
if (location) {
// return the location for the front-end to redirect to
}
if (!success) {
// authentication failed
}
// authentication successful
```
It means the authentication process requires the user to perform an action with a third-party service. For example, when using the `google` provider, the user goes to the URL specified in the `location`'s value to log in with their Google account.
If the `authenticate` method returns a `location` property, the authentication process requires the user to perform an action with a third-party service. So, you return the `location` to the front-end or client to redirect to that URL.
For example, when using the `google` provider, the `location` is the URL that the user is navigated to login.
![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)
@@ -96,27 +123,29 @@ It means the authentication process requires the user to perform an action with
Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.
So, once the user performs the required action, the third-party service must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](/references/auth/validateCallback). The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
So, once the user performs the required action with the third-party service (for example, log-in with Google), the frontend must redirect to an API route that uses the [validateCallback method of the Auth Module's main service](/references/auth/validateCallback).
The method calls the specified provider’s `validateCallback` method passing it the authentication details it received in the second parameter:
```ts
const data = await authModuleService.validateCallback(
"google",
// passed to auth provider
{
// ...
}
)
```
const { success, authIdentity } = await authModuleService.validateCallback(
"google",
// passed to auth provider
{
// request data, such as
url,
headers,
query,
body,
protocol,
}
)
If the authentication is successful, the `validateCallback` method returns the same data as the basic authentication:
```ts
data = {
success: true,
authIdentity: {
// ...
},
if (success) {
// authentication succeeded
}
```
If the returned `success` property is `true`, the authentication with the third-party provider was successful.
![Diagram showcasing the second part of the third-party authentication flow](https://res.cloudinary.com/dza7lstvk/image/upload/v1711375123/Medusa%20Resources/third-party-auth-2_kmjxju.jpg)
www/apps/resources/app/commerce-modules/auth/auth-identity-and-actor-types/page.mdx
+4 -4
View File
@@ -8,9 +8,9 @@ In this document, you’ll learn about concepts related to identity and actors i
## What is an Auth Identity?
The [AuthIdentity data model](/references/auth/model/AuthIdentity) represents a previously-authenticated user.
The [AuthIdentity data model](/references/auth/model/AuthIdentity) represents a registered user.
When a user is authenticated, a record of `AuthIdentity` is created. This record is used to validate the user’s authentication in future requests.
When a user is registered, a record of `AuthIdentity` is created. This record is used to validate the user’s authentication in future requests.
---
@@ -18,7 +18,7 @@ When a user is authenticated, a record of `AuthIdentity` is created. This record
An actor type is a type of user that can be authenticated. This user is a record of a data model defined by a module.
For example, the `customer` belongs to the Customer Module’s `Customer` data model. Similarly, the `user` belongs to the User Module’s `User` data model.
For example, the `customer` actor type belongs to the Customer Module’s `Customer` data model. Similarly, the `user` actor type belongs to the User Module’s `User` data model.
### Protect Routes by Actor Type
@@ -48,7 +48,7 @@ export default defineMiddlewares({
})
```
By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` can access API routes starting with `/custom/admin`.
By specifying `user` as the first parameter of `authenticate`, only authenticated users of actor type `user` (admin users) can access API routes starting with `/custom/admin`.
---
www/apps/resources/app/commerce-modules/auth/auth-providers/_google/page.mdx
-186
View File
@@ -1,186 +0,0 @@
import { Table } from "docs-ui"
export const metadata = {
title: `Google Auth Module Provider`,
}
# {metadata.title}
In this document, you’ll learn about the Google auth module provider and how to install and use it in the Auth Module.
## Features
The Google auth module provider handles authenticating users with their Google accounts.
By integrating the Google auth provider, you provide your users and customers with the ability to login with their Google account.
---
## Install the Google Auth Module Provider
<Note type="check">
- [Create a project in Google Cloud.](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
- [Create authorization credentials](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred).
- Set the Redirect Uri of your Oauth Client ID to `{medusa_url}/auth/{actor_type}/google/callback`, where:
- `{medusa_url}` is the URL of your Medusa backend.
- `{actor_type}` is the actor type that the Google auth provider can authenticate. For example, `customer`.
</Note>
To install the Google auth module provider, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/auth-google
```
Next, add the module to the array of providers passed to the Auth Module:
```js title="medusa-config.js"
import { Modules } from "@medusajs/utils"
// ...
const modules = {
// ...
[Modules.AUTH]: {
resolve: "@medusajs/auth",
options: {
providers: [
{
resolve: "@medusajs/auth-google",
id: "google",
options: {
clientID: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
callbackURL: process.env.GOOGLE_CALLBACK_URL,
successRedirectUrl:
process.env.GOOGLE_SUCCESS_REDIRECT_URL,
},
},
],
},
},
}
```
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID>
GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET>
GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
GOOGLE_SUCCESS_REDIRECT_URL=<YOUR_GOOGLE_SUCCESS_REDIRECT_URL>
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Configuration</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`clientID`
</Table.Cell>
<Table.Cell>
A string indicating the [Google API Client ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`clientSecret`
</Table.Cell>
<Table.Cell>
A string indicating the [Google Client Secret](https://support.google.com/cloud/answer/6158849?hl=en#zippy=%2Cstep-create-a-new-client-secret).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`callbackURL`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your app after the user completes their authentication in Google.
The Medusa application provides the API route `/auth/[scope]/google/callback` that you can use, where `[scope]` is the scope this config belongs to.
For example, `/auth/store/google/callback`.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`successRedirectUrl`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your app after the authentication has been successful.
If not provided, the Medusa application's callback route just returns a JSON with the JWT token of the auth identity.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
{/* TODO add how to implement authentication flow with google */}
www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx
+1 -2
View File
@@ -8,8 +8,6 @@ export const metadata = {
In this document, you’ll learn about the Emailpass auth module provider and how to install and use it in the Auth Module.
## Features
Using the Emailpass auth module provider, you allow users to register and login with an email and password.
---
@@ -31,6 +29,7 @@ const modules = {
resolve: "@medusajs/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/auth-emailpass",
id: "emailpass",
www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx
+152
View File
@@ -0,0 +1,152 @@
import { Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `GitHub Auth Module Provider`,
}
# {metadata.title}
In this document, you’ll learn about the GitHub Auth Module Provider and how to install and use it in the Auth Module.
The Github Auth Module Provider handles authenticating users with their GitHub account.
<Note title="Tip">
Learn about the authentication flow in [this guide](../../authentication-route/page.mdx).
</Note>
---
## Install the Github Auth Module Provider
<Prerequisites
items={[
{
text: "Register GitHub App. When setting the Callback URL, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.",
link: "https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app"
},
{
text: "Retrieve the client ID and client secret of your GitHub App",
link: "https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api?apiVersion=2022-11-28#using-basic-authentication"
}
]}
/>
To install the GitHub auth module provider, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/auth-github@preview
```
Next, add the module to the array of providers passed to the Auth Module:
```js title="medusa-config.js"
import { Modules } from "@medusajs/utils"
// ...
const modules = {
// ...
[Modules.AUTH]: {
resolve: "@medusajs/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/auth-github",
id: "github",
options: {
clientId: process.env.GITHUB_CLIENT_ID,
clientSecret: process.env.GITHUB_CLIENT_SECRET,
callbackUrl: process.env.GITHUB_CALLBACK_URL,
},
},
],
},
},
}
```
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```plain
GITHUB_CLIENT_ID=<YOUR_GITHUB_CLIENT_ID>
GITHUB_CLIENT_SECRET=<YOUR_GITHUB_CLIENT_SECRET>
GITHUB_CALLBACK_URL=<YOUR_GITHUB_CALLBACK_URL>
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Configuration</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell className="w-1/5">Required</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`clientId`
</Table.Cell>
<Table.Cell>
A string indicating the client ID of your GitHub app.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`clientSecret`
</Table.Cell>
<Table.Cell>
A string indicating the client secret of your GitHub app.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`callbackUrl`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your frontend after the user completes their authentication in GitHub.
At this URL, the frontend will receive a `code` query parameter. It then sends that `code` query parameter to the Medusa application's `/auth/{actor_type}/github/callback` route.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Examples
- [How to implement third-party / social login in the storefront.](../../../../storefront-development/customers/third-party-login/page.mdx).
www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx
+152
View File
@@ -0,0 +1,152 @@
import { Table, Prerequisites } from "docs-ui"
export const metadata = {
title: `Google Auth Module Provider`,
}
# {metadata.title}
In this document, you’ll learn about the Google Auth Module Provider and how to install and use it in the Auth Module.
The Google Auth Module Provider handles authenticating users with their Google account.
<Note title="Tip">
Learn about the authentication flow in [this guide](../../authentication-route/page.mdx).
</Note>
---
## Install the Google Auth Module Provider
<Prerequisites
items={[
{
text: "Create a project in Google Cloud.",
link: "https://cloud.google.com/resource-manager/docs/creating-managing-projects"
},
{
text: "Create authorization credentials. When setting the Redirect Uri, set it to a URL in your frontend that later uses Medusa's callback route to validate the authentication.",
link: "https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred"
}
]}
/>
To install the Google auth module provider, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/auth-google@preview
```
Next, add the module to the array of providers passed to the Auth Module:
```js title="medusa-config.js"
import { Modules } from "@medusajs/utils"
// ...
const modules = {
// ...
[Modules.AUTH]: {
resolve: "@medusajs/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/auth-google",
id: "google",
options: {
clientId: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
callbackUrl: process.env.GOOGLE_CALLBACK_URL,
},
},
],
},
},
}
```
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```plain
GOOGLE_CLIENT_ID=<YOUR_GOOGLE_CLIENT_ID>
GOOGLE_CLIENT_SECRET=<YOUR_GOOGLE_CLIENT_SECRET>
GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
```
### Module Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Configuration</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell className="w-1/5">Required</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`clientId`
</Table.Cell>
<Table.Cell>
A string indicating the [Google API Client ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`clientSecret`
</Table.Cell>
<Table.Cell>
A string indicating the [Google Client Secret](https://support.google.com/cloud/answer/6158849?hl=en#zippy=%2Cstep-create-a-new-client-secret).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`callbackUrl`
</Table.Cell>
<Table.Cell>
A string indicating the URL to redirect to in your frontend after the user completes their authentication in Google.
At this URL, the frontend will receive a `code` query parameter. It then sends that `code` query parameter to the Medusa application's `/auth/{actor_type}/google/callback` route.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Examples
- [How to implement Google social login in the storefront.](../../../../storefront-development/customers/third-party-login/page.mdx).
www/apps/resources/app/commerce-modules/auth/auth-providers/page.mdx
+19 -4
View File
@@ -1,3 +1,5 @@
import { CardList } from "docs-ui"
export const metadata = {
title: `Auth Providers`,
}
@@ -12,11 +14,24 @@ An auth module provider handles authenticating customers and users, either using
For example, the EmailPass Auth Module Provider authenticates a user using their email and password, whereas the Google Auth Module Provider authenticates users using their Google account.
<Note type="soon">
### Auth Providers List
Support for the Google Auth Module Provider is coming soon.
</Note>
<CardList
items={[
{
title: "Emailpass",
href: "/commerce-modules/auth/auth-providers/emailpass"
},
{
title: "Google",
href: "/commerce-modules/auth/auth-providers/google"
},
{
title: "GitHub",
href: "/commerce-modules/auth/auth-providers/github"
},
]}
/>
---
www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
+104 -21
View File
@@ -18,24 +18,51 @@ These routes are added by Medusa's application layer, not the Auth Module.
This authentication flow doesn't require validation with third-party services.
It requires the following steps:
<Note title="Example">
1. Registering the user with the [Register Route](#register-route).
2. Authenticating the user with the [Auth Route](#auth-route).
[How to register customer in storefront using basic authentication flow](../../../storefront-development/customers/register/page.mdx).
</Note>
The steps are:
![Diagram showcasing the basic authentication flow between the frontend and the Medusa application](https://res.cloudinary.com/dza7lstvk/image/upload/v1725539370/Medusa%20Resources/basic-auth-routes_pgpjch.jpg)
1. Register the user with the [Register Route](#register-route).
5. Use the authentication token to create the user with their respective API route.
- For example, for customers you would use the [Create Customer API route](!api!/store#customers_postcustomers).
- For admin users, you accept an invite using the [Accept Invite API route](!api!/admin#invites_postinvitesaccept)
2. Authenticate the user with the [Auth Route](#auth-route).
After registration, you only use the [Auth Route](#auth-route) for subsequent authentication.
### 2. Third-Party Service Authenticate Flow
This authentication flow authenticates the user with a third-party service, such as Google.
<Note title="Example">
[How to authenticate customer with a third-party provider in the storefront.](../../../storefront-development/customers/third-party-login/page.mdx).
</Note>
It requires the following steps:
![Diagram showcasing the authentication flow between the frontend, Medusa application, and third-party service](https://res.cloudinary.com/dza7lstvk/image/upload/v1725528159/Medusa%20Resources/Third_Party_Auth_tvf4ng.jpg)
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.
2. The auth route returns a URL to authenticate with third-party service, such as login with Google. The frontend (such as a storefront), when it receives a `location` property in the response, must redirect to the returned location.
3. Once the authentication with the third-party service finishes, it redirects back to the frontend with a `code` query parameter. So, make sure your third-party service is configured to redirect to your frontend page after successful authentication.
4. The frontend sends a request to the [Callback Route](#callback-route) passing the `code` query parameter.
5. If the callback validation is successful, the frontend receives the authentication token.
6. Decode the received token in the frontend using tools like [react-jwt](https://www.npmjs.com/package/react-jwt).
- If the decoded data has an `actor_id` property, then the user is already registered. So, use this token for subsequent authenticated requests.
- If not, follow the rest of the steps.
7. The frontend uses the authentication token to create the user with their respective API route.
- For example, for customers you would use the [Create Customer API route](!api!/store#customers_postcustomers).
- For admin users, you accept an invite using the [Accept Invite API route](!api!/admin#invites_postinvitesaccept)
8. The frontend sends a request to the [Refresh Token Route](#refresh-token-route) to retrieve a new token with the user information populated.
You may then use the [Auth Route](#auth-route) for subsequent authentication.
---
@@ -43,6 +70,15 @@ You may then use the [Auth Route](#auth-route) for subsequent authentication.
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.
```bash
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
-H 'Content-Type: application/json' \
--data-raw '{
"email": "Whitney_Schultz@gmail.com"
// ...
}'
```
<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.
@@ -77,11 +113,7 @@ If the authentication is successful, you'll receive a `token` field in the respo
}
```
<Note title="Example">
[How to register Customers using the authentication route](../../../storefront-development/customers/register/page.mdx).
</Note>
Use that token in the header of subsequent requests to send authenticated requests.
---
@@ -89,6 +121,15 @@ If the authentication is successful, you'll receive a `token` field in the respo
The Medusa application defines an API route at `/auth/{actor_type}/{provider}` that authenticates a user of an actor type. It returns a JWT token that can be passed in [the header of subsequent requests](!api!/store#authentication) to send authenticated requests.
```bash
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}
-H 'Content-Type: application/json' \
--data-raw '{
"email": "Whitney_Schultz@gmail.com"
// ...
}'
```
For example, if you're authenticating a customer, you send a request to `/auth/customer/emailpass`.
### Path Parameters
@@ -114,6 +155,18 @@ If the authentication is successful, you'll receive a `token` field in the respo
}
```
Use that token in the header of subsequent requests to send authenticated requests.
If the authentication requires more action with a third-party service, you'll receive a `location` property:
```json
{
"location": "https://..."
}
```
Redirect to that URL in the frontend to continue the authentication process with the third-party service.
<Note title="Example">
[How to login Customers using the authentication route](../../../storefront-development/customers/login/page.mdx).
@@ -124,18 +177,18 @@ If the authentication is successful, you'll receive a `token` field in the respo
## 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.
The Medusa application defines an API route at `/auth/{actor_type}/{provider}/callback` that's useful for validating the authentication callback or redirect from third-party services like 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.
```bash
curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/callback?code=123
```
<Note title="Tip">
The URL of the authentication portal is received from the Auth Module Provider.
Refer to the [third-party authentication flow](#2-third-party-service-authenticate-flow) section to see how this route fits into the authentication flow.
</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:
@@ -143,9 +196,9 @@ 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
### Query 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.
This route accepts a `code` query parameter, which is the code received from the third-party provider.
### Response Fields
@@ -155,4 +208,34 @@ If the authentication is successful, you'll receive a `token` field in the respo
{
"token": "..."
}
```
```
In your frontend, decode the token using tools like [react-jwt](https://www.npmjs.com/package/react-jwt):
- If the decoded data has an `actor_id` property, the user is already registered. So, use this token for subsequent authenticated requests.
- If not, use the token in the header of a request that creates the user, such as the [Create Customer API route](!api!/store#customers_postcustomers).
---
## Refresh Token Route
The Medusa application defines an API route at `/auth/token/refresh` that's useful after authenticating a user with a third-party service to populate the user's token with their new information.
It requires the user's JWT token that they received from the authentication or callback routes.
```bash
curl -X POST http://localhost:9000/auth/token/refresh \
-H 'Authorization: Bearer {token}'
```
### Response Fields
If the token was refreshed successfully, you'll receive a `token` field in the response body object:
```json
{
"token": "..."
}
```
Use that token in the header of subsequent requests to send authenticated requests.
www/apps/resources/app/commerce-modules/auth/create-actor-type/page.mdx
+1 -1
View File
@@ -251,7 +251,7 @@ To authenticate managers:
1. Send a `POST` request to `/auth/manager/emailpass/register` to create an auth identity for the manager:
```bash
curl -X POST 'http://localhost:9000/auth/manager/emailpass' \
curl -X POST 'http://localhost:9000/auth/manager/emailpass/register' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "manager@gmail.com",
www/apps/resources/app/commerce-modules/auth/examples/page.mdx
+2 -3
View File
@@ -52,7 +52,7 @@ export async function POST(
}
if (location) {
res.redirect(location)
res.json({ location })
return
}
@@ -90,8 +90,7 @@ export async function POST(request: Request) {
}
if (location) {
return NextResponse.redirect(location)
return
return NextResponse.json({ location })
}
const token = jwt.sign(authIdentity, "supersecret")
www/apps/resources/app/commerce-modules/auth/page.mdx
+2 -3
View File
@@ -49,9 +49,8 @@ const { success, authIdentity, location } =
protocol: req.protocol,
} as AuthenticationInput)
if (!authIdentity && location) {
res.redirect(location)
return
if (location) {
return res.json({ location })
}
// in callback API route