Auth Module

In this section of the documentation, you will find resources to learn more about the Auth Module and how to use it in your application.

Medusa has auth related features available out-of-the-box through the Auth Module. A module is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in commerce modules, such as this Auth Module.

Auth Features#

• Basic User Authentication: Authenticate users using their email and password credentials.
• Third-Party and Social Authentication: Authenticate users using third-party services and social platforms, such as Google and GitHub.
• Authenticate Custom Actor Types: Create custom user or actor types, such as managers, authenticate them in your application, and guard routes based on the custom user types.
• Custom Authentication Providers: Integrate third-party services with custom authentication providors.

How to Use the Auth Module#

In your Medusa application, you build flows around commerce modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the @medusajs/medusa/core-flows package.

For example:

src/workflows/authenticate-user.ts
1import { 2  createWorkflow, 3  WorkflowResponse,4  createStep,5  StepResponse,6} from "@medusajs/framework/workflows-sdk"7import { Modules, MedusaError } from "@medusajs/framework/utils"8import { MedusaRequest } from "@medusajs/framework/http"9import { AuthenticationInput } from "@medusajs/framework/types"10
11type Input = {12  req: MedusaRequest13}14
15const authenticateUserStep = createStep(16  "authenticate-user",17  async ({ req }: Input, { container }) => {18    const authModuleService = container.resolve(Modules.AUTH)19
20    const { success, authIdentity, error } = await authModuleService21      .authenticate(22        "emailpass",23       {24          url: req.url,25          headers: req.headers,26          query: req.query,27          body: req.body,28          authScope: "admin", // or custom actor type29          protocol: req.protocol,30        } as AuthenticationInput31      )32
33    if (!success) {34      // incorrect authentication details35      throw new MedusaError(36        MedusaError.Types.UNAUTHORIZED,37        error || "Incorrect authentication details"38      )39    }40
41    return new StepResponse({ authIdentity }, authIdentity?.id)42  },43  async (authIdentityId, { container }) => {44    if (!authIdentityId) {45      return46    }47    48    const authModuleService = container.resolve(Modules.AUTH)49
50    await authModuleService.deleteAuthIdentities([authIdentityId])51  }52)53
54export const authenticateUserWorkflow = createWorkflow(55  "authenticate-user",56  (input: Input) => {57    const { authIdentity } = authenticateUserStep(input)58
59    return new WorkflowResponse({60      authIdentity,61    })62  }63)

You can then execute the workflow in your custom API routes, scheduled jobs, or subscribers:

API Route
Show Imports
5import { authenticateUserWorkflow } from "../../workflows/authenticate-user"6
7export async function GET(8  req: MedusaRequest,9  res: MedusaResponse10) {11  const { result } = await authenticateUserWorkflow(req.scope)12    .run({13      req,14    })15
16  res.send(result)17}

Learn more about workflows in this documentation.

Configure Auth Module#

The Auth Module accepts options for further configurations. Refer to this documentation for details on the module's options.

Providers#

Medusa provides the following authentication providers out-of-the-box. You can use them to authenticate admin users, customers, or custom actor types.