From 60fd1cbc6c8e8078820ce09a0a3d76cbdc2fecf1 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 7 Jan 2025 16:42:45 +0200 Subject: [PATCH] docs: document dependencies for auth provider (#10865) * docs: document dependencies for auth provider * fixes * document overriding callback url --- .../commerce-modules/auth/auth-flows/page.mdx | 17 +++++- .../auth/auth-providers/emailpass/page.mdx | 37 +++++++------ .../auth/auth-providers/github/page.mdx | 49 ++++++++++------- .../auth/auth-providers/google/page.mdx | 54 ++++++++++++------- .../auth/authentication-route/page.mdx | 14 +++-- .../auth/module-options/page.mdx | 3 +- www/apps/resources/generated/edit-dates.mjs | 8 +-- .../page.mdx | 4 ++ .../merger-custom-options/auth-provider.ts | 4 ++ 9 files changed, 125 insertions(+), 65 deletions(-) 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 4061945845..94c997ddaf 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 @@ -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. diff --git a/www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx b/www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx index b1a4041932..5a867d5388 100644 --- a/www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/auth-providers/emailpass/page.mdx @@ -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 diff --git a/www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx b/www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx index 4b42203f19..49434d604c 100644 --- a/www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx @@ -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= --- +## 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). diff --git a/www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx b/www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx index d583e96b84..d93583e8ab 100644 --- a/www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/auth-providers/google/page.mdx @@ -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= --- +--- + +## 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). 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 ea4434ac66..3f51e2dff5 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 @@ -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. @@ -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 -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. @@ -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: diff --git a/www/apps/resources/app/commerce-modules/auth/module-options/page.mdx b/www/apps/resources/app/commerce-modules/auth/module-options/page.mdx index 89c01c6ddc..7880ce1bf5 100644 --- a/www/apps/resources/app/commerce-modules/auth/module-options/page.mdx +++ b/www/apps/resources/app/commerce-modules/auth/module-options/page.mdx @@ -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: [ { diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 9972837eb6..fff190df78 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -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", diff --git a/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx b/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx index e20b702e7e..738ce8fe91 100644 --- a/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx +++ b/www/apps/resources/references/auth_provider/classes/auth_provider.AbstractAuthModuleProvider/page.mdx @@ -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... }, diff --git a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts index c723bf4b8b..59b5b9c163 100644 --- a/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts +++ b/www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/auth-provider.ts @@ -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... },