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

docs: document dependencies for auth provider (#10865)

Browse Source 
* docs: document dependencies for auth provider

* fixes

* document overriding callback url
This commit is contained in:
Shahed Nasser
2025-01-07 16:42:45 +02:00
committed by GitHub
parent edcff0ed16
commit 60fd1cbc6c
9 changed files with 125 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
www/apps/resources/app/commerce-modules/auth/auth-flows/page.mdx
View File

@@ -110,7 +110,7 @@ The third-party service authentication method requires using the `authenticate`
```ts
const { success, authIdentity, location } = await authModuleService.authenticate(
"emailpass",
"google",
// passed to auth provider
{
// ...
@@ -134,6 +134,21 @@ For example, when using the `google` provider, the `location` is the URL that th
![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)
### Overriding Callback URL
The Google and GitHub providers allow you to override their `callbackUrl` option during authentication. This is useful when you redirect the user after authentication to a URL based on its actor type. For example, you redirect admin users and customers to different pages.
```ts
const { success, authIdentity, location } = await authModuleService.authenticate(
"google",
// passed to auth provider
{
// ...
callback_url: "example.com"
}
)
```
### validateCallback
Providers handling this authentication flow must implement the `validateCallback` method. It implements the logic to validate the authentication with the third-party service.

37
www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx
View File

@@ -19,28 +19,31 @@ The Emailpass auth provider is registered by default with the Auth Module.
If you want to pass options to the provider, add the provider to the `providers` option of the Auth Module:
```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"
import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
// ...
const modules = {
module.exports = defineConfig({
// ...
[Modules.AUTH]: {
resolve: "@medusajs/medusa/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/medusa/auth-emailpass",
id: "emailpass",
options: {
// options...
modules: [
{
resolve: "@medusajs/medusa/auth",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
options: {
providers: [
// other providers...
{
resolve: "@medusajs/medusa/auth-emailpass",
id: "emailpass",
options: {
// options...
},
},
},
],
},
},
}
],
},
}
],
})
```
### Module Options

49
www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx
View File

@@ -36,30 +36,33 @@ Learn about the authentication flow in [this guide](../../authentication-route/p
Add the module to the array of providers passed to the Auth Module:
```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"
import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
// ...
const modules = {
module.exports = defineConfig({
// ...
[Modules.AUTH]: {
resolve: "@medusajs/medusa/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/medusa/auth-github",
id: "github",
options: {
clientId: process.env.GITHUB_CLIENT_ID,
clientSecret: process.env.GITHUB_CLIENT_SECRET,
callbackUrl: process.env.GITHUB_CALLBACK_URL,
modules: [
{
resolve: "@medusajs/medusa/auth",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
options: {
providers: [
// other providers...
{
resolve: "@medusajs/medusa/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
@@ -141,6 +144,14 @@ GITHUB_CALLBACK_URL=<YOUR_GITHUB_CALLBACK_URL>
---
## Override Callback URL During Authentication
In many cases, you may have different callback URL for actor types. For example, you may redirect admin users to a different URL than customers after authentication.
The [Authenticate or Login API Route](../../authentication-route/page.mdx#login-route) can accept a `callback_url` body parameter to override the provider's `callbackUrl` option. Learn more in [this documentation](../../authentication-route/page.mdx#login-route).
---
## Examples
- [How to implement third-party / social login in the storefront.](../../../../storefront-development/customers/third-party-login/page.mdx).

54
www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx
View File

@@ -36,30 +36,36 @@ Learn about the authentication flow for third-party providers in [this guide](..
Add the module to the array of providers passed to the Auth Module:
```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"
import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
// ...
const modules = {
module.exports = defineConfig({
// ...
[Modules.AUTH]: {
resolve: "@medusajs/medusa/auth",
options: {
providers: [
// other providers...
{
resolve: "@medusajs/medusa/auth-google",
id: "google",
options: {
clientId: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
callbackUrl: process.env.GOOGLE_CALLBACK_URL,
},
modules: [
{
// ...
[Modules.AUTH]: {
resolve: "@medusajs/medusa/auth",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
options: {
providers: [
// other providers...
{
resolve: "@medusajs/medusa/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
@@ -141,6 +147,16 @@ GOOGLE_CALLBACK_URL=<YOUR_GOOGLE_CALLBACK_URL>
---
---
## Override Callback URL During Authentication
In many cases, you may have different callback URL for actor types. For example, you may redirect admin users to a different URL than customers after authentication.
The [Authenticate or Login API Route](../../authentication-route/page.mdx#login-route) can accept a `callback_url` body parameter to override the provider's `callbackUrl` option. Learn more in [this documentation](../../authentication-route/page.mdx#login-route).
---
## Examples
- [How to implement Google social login in the storefront](../../../../storefront-development/customers/third-party-login/page.mdx).

14
www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx
View File

@@ -32,9 +32,9 @@ The steps are:
2. 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)
3. Authenticate the user with the [Auth Route](#auth-route).
3. Authenticate the user with the [Auth Route](#login-route).
After registration, you only use the [Auth Route](#auth-route) for subsequent authentication.
After registration, you only use the [Auth Route](#login-route) for subsequent authentication.
<Note>
@@ -56,7 +56,7 @@ 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).
1. Authenticate the user with the [Auth Route](#login-route).
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.
@@ -87,7 +87,7 @@ curl -X POST http://localhost:9000/auth/{actor_type}/{providers}/register
<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.
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](#login-route) instead.
</Note>
@@ -180,6 +180,12 @@ This route accepts in the request body the data that the specified authenticatio
For example, the EmailPass provider requires an `email` and `password` fields in the request body.
#### Overriding Callback URL
For the [GitHub](../auth-providers/github/page.mdx) and [Google](../auth-providers/google/page.mdx) providers, you can pass a `callback_url` body parameter that overrides the `callbackUrl` set in the provider's configurations.
This is useful if you want to redirect the user to a different URL after authentication based on their actor type. For example, you can set different `callback_url` for admin users and customers.
### Response Fields
If the authentication is successful, you'll receive a `token` field in the response body object:

3
www/apps/resources/app/commerce-modules/auth/module-options/page.mdx
View File

@@ -27,7 +27,7 @@ By default, the `emailpass` provider is registered to authenticate customers and
For example:
```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"
import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
// ...
@@ -36,6 +36,7 @@ module.exports = defineConfig({
modules: [
{
resolve: "@medusajs/medusa/auth",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
options: {
providers: [
{

8
www/apps/resources/generated/edit-dates.mjs
View File

@@ -1,9 +1,9 @@
export const generatedEditDates = {
"app/commerce-modules/auth/auth-providers/emailpass/page.mdx": "2024-10-08T07:35:59.167Z",
"app/commerce-modules/auth/auth-providers/emailpass/page.mdx": "2025-01-07T12:47:24.380Z",
"app/commerce-modules/auth/auth-providers/page.mdx": "2024-10-08T07:27:21.859Z",
"app/commerce-modules/auth/authentication-route/page.mdx": "2025-01-07T09:26:27.809Z",
"app/commerce-modules/auth/examples/page.mdx": "2024-10-15T15:02:13.794Z",
"app/commerce-modules/auth/module-options/page.mdx": "2024-10-15T12:52:08.930Z",
"app/commerce-modules/auth/module-options/page.mdx": "2025-01-07T12:47:35.073Z",
"app/commerce-modules/auth/page.mdx": "2024-12-25T15:40:37.154Z",
"app/commerce-modules/cart/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
"app/commerce-modules/cart/_events/page.mdx": "2024-07-03T19:27:13+03:00",
@@ -861,8 +861,8 @@ export const generatedEditDates = {
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminClaimPreviewResponse/page.mdx": "2025-01-07T12:54:21.225Z",
"references/types/HttpTypes/interfaces/types.HttpTypes.AdminOrderEditPreviewResponse/page.mdx": "2025-01-07T12:54:21.543Z",
"references/types/interfaces/types.BaseClaim/page.mdx": "2025-01-07T12:54:20.996Z",
"app/commerce-modules/auth/auth-providers/github/page.mdx": "2024-10-08T07:37:27.882Z",
"app/commerce-modules/auth/auth-providers/google/page.mdx": "2024-10-08T07:37:06.517Z",
"app/commerce-modules/auth/auth-providers/github/page.mdx": "2025-01-07T12:47:30.196Z",
"app/commerce-modules/auth/auth-providers/google/page.mdx": "2025-01-07T12:47:32.501Z",
"app/storefront-development/customers/third-party-login/page.mdx": "2025-01-06T16:05:41.159Z",
"references/types/HttpTypes/types/types.HttpTypes.AdminWorkflowRunResponse/page.mdx": "2024-12-09T13:21:34.761Z",
"references/types/HttpTypes/types/types.HttpTypes.BatchResponse/page.mdx": "2024-12-09T13:21:33.549Z",

4
www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx
View File

@@ -467,6 +467,8 @@ This exports the module's definition, indicating that the `MyAuthProviderService
To use your Auth Module Provider, add it to the `providers` array of the Auth Module in `medusa-config.ts`:
```ts title="medusa-config.ts"
import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
@@ -477,11 +479,13 @@ module.exports = defineConfig({
// default provider
{
resolve: "@medusajs/medusa/auth-emailpass",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
id: "emailpass",
},
{
resolve: "./src/modules/my-auth",
id: "my-auth",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
options: {
// provider options...
},

4
www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts
View File

@@ -62,6 +62,8 @@ This exports the module's definition, indicating that the \`MyAuthProviderServic
To use your Auth Module Provider, add it to the \`providers\` array of the Auth Module in \`medusa-config.ts\`:
\`\`\`ts title="medusa-config.ts"
import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
@@ -72,11 +74,13 @@ module.exports = defineConfig({
// default provider
{
resolve: "@medusajs/medusa/auth-emailpass",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
id: "emailpass",
},
{
resolve: "./src/modules/my-auth",
id: "my-auth",
dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
options: {
// provider options...
},