@medusajs/auth
Documentation | Website
Building blocks for digital commerce
Auth Module for Medusa: manages auth identities, provider identities, password reset tokens, verifications, and multi-factor authentication (MFA) factors and recovery codes. It authenticates actors (such as admin users and customers) through pluggable Auth Module Providers. It ships with @medusajs/medusa and is registered by default, so you normally use it through the Medusa application rather than installing it directly.
At a glance
| Package | @medusajs/auth |
| Type | Commerce Module |
| Module key | Modules.AUTH ("auth") |
| Registered by default | Yes, with the emailpass provider |
| Import from | @medusajs/medusa/auth |
Features
- Authenticate actors through Auth Module Providers. Official providers:
@medusajs/auth-emailpass: email and password.@medusajs/auth-github: GitHub OAuth.@medusajs/auth-google: Google OAuth.@medusajs/auth-oidc: OpenID Connect.
- Link multiple provider identities to one auth identity.
- Password reset tokens and token-based verifications.
- Built-in MFA with TOTP and recovery codes.
Installation
No installation needed. The module ships with @medusajs/medusa and is registered by default with the emailpass provider and mfa.encryption_key set from the AUTH_MFA_ENCRYPTION_KEY environment variable.
Usage
To add providers, register the module in medusa-config.ts:
import { defineConfig } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/auth",
options: {
providers: [
{
resolve: "@medusajs/medusa/auth-emailpass",
id: "emailpass",
},
],
},
},
],
})
Configuration
| Option | Type | Description | Default |
|---|---|---|---|
providers |
{ resolve: string, id: string, options?: Record<string, unknown> }[] |
Auth Module Providers to register. | emailpass provider |
mfa.encryption_key |
string |
Key used to encrypt MFA secrets at rest. | AUTH_MFA_ENCRYPTION_KEY env var |
mfa.recovery_code_count |
number |
Number of recovery codes generated for an auth identity. | 10 |
mfa.challenge_ttl_seconds |
number |
Seconds an MFA challenge remains valid. | 300 |
mfa.challenge_max_attempts |
number |
Failed verification attempts allowed per MFA challenge. | 5 |
mfa.disable_policy |
"challenge" | "session" |
Policy used when disabling MFA. | "session" |
mfa.providers |
{ resolve?: string, id: string, options?: Record<string, unknown> }[] |
Additional MFA providers, or options for built-in ones such as totp. |
- |
verification.providers |
{ resolve?: string, id: string, options?: Record<string, unknown> }[] |
Additional verification providers, or options for the built-in token provider. |
- |