docs: document dependencies for auth provider (#10865)

* docs: document dependencies for auth provider

* fixes

* document overriding callback url

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.

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]: {
+  modules: [
-    resolve: "@medusajs/medusa/auth",
+    {
-    options: {
+      resolve: "@medusajs/medusa/auth",
-      providers: [
+      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
-        // other providers...
+      options: {
-        {
+        providers: [
-          resolve: "@medusajs/medusa/auth-emailpass",
+          // other providers...
-          id: "emailpass",
+          {
-          options: {
+            resolve: "@medusajs/medusa/auth-emailpass",
-            // options...
+            id: "emailpass",
+            options: {
+              // options...
+            },
           },
-        },
+        ],
-      ],
+      },
-    },
+    }
-  },
+  ],
-}
+})
 ```
 
 ### Module Options

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]: {
+  modules: [
-    resolve: "@medusajs/medusa/auth",
+    {
-    options: {
+      resolve: "@medusajs/medusa/auth",
-      providers: [
+      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
-        // other providers...
+      options: {
-        {
+        providers: [
-          resolve: "@medusajs/medusa/auth-github",
+          // other providers...
-          id: "github",
+          {
-          options: {
+            resolve: "@medusajs/medusa/auth-github",
-            clientId: process.env.GITHUB_CLIENT_ID,
+            id: "github",
-            clientSecret: process.env.GITHUB_CLIENT_SECRET,
+            options: {
-            callbackUrl: process.env.GITHUB_CALLBACK_URL,
+              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).

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]: {
+  modules: [
-    resolve: "@medusajs/medusa/auth",
+    {
-    options: {
+      // ...
-      providers: [
+      [Modules.AUTH]: {
-        // other providers...
+        resolve: "@medusajs/medusa/auth",
-        {
+        dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
-          resolve: "@medusajs/medusa/auth-google",
+        options: {
-          id: "google",
+          providers: [
-          options: {
+            // other providers...
-            clientId: process.env.GOOGLE_CLIENT_ID,
+            {
-            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+              resolve: "@medusajs/medusa/auth-google",
-            callbackUrl: process.env.GOOGLE_CALLBACK_URL,
+              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).

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.
 
 <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:

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: [
           {

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/github/page.mdx": "2025-01-07T12:47:30.196Z",
-  "app/commerce-modules/auth/auth-providers/google/page.mdx": "2024-10-08T07:37:06.517Z",
+  "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",

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...
             },

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...
             },