Medusa Authentication Plugin (v2)

Features

• 🔐 Google OAuth Authentication (fully implemented)
• 🖼️ Beautiful Success & Error Pages
• 🔄 Enhanced Profile Data with Avatar Display
• 📱 Mobile-Friendly Interface
• 🛡️ TypeScript Support
• 🐳 Docker Test Environment Included

Screenshots

Initial Login Screen

Successful Authentication Screen

Prerequisites

• Medusa backend
• Medusa admin

Quick Start with Docker

The plugin comes with a complete test environment using Docker Compose, which includes:

• Medusa backend with the auth plugin pre-configured
• Admin dashboard
• PostgreSQL database
• Redis for caching

Running the Docker Environment

# Clone the repository (if not already done)
git clone <repository-url>
cd medusa-plugin-auth-v2

# Start the Docker environment
docker-compose up -d

Access the services:

• Medusa Backend: http://localhost:9000
• Medusa Admin: http://localhost:7001
• Authentication URLs:
  • Start Google OAuth: http://localhost:9000/store/auth/google
  • Success Page: http://localhost:9000/auth/success
  • Error Page: http://localhost:9000/auth/error

Testing OAuth Flow

1. Configure your OAuth credentials in a .env file (see .env-example)
2. Restart the Docker containers to apply the changes
3. Navigate to http://localhost:9000/store/auth/google to start the OAuth flow
4. After successful authentication, you'll be redirected to the success page

Installation (without Docker)

npm install medusa-plugin-auth-v2
# or
yarn add medusa-plugin-auth-v2

Configuration

Add the plugin to your medusa-config.js or medusa-config.ts:

const { defineConfig } = require('@medusajs/medusa')

module.exports = defineConfig({
  plugins: [
    // ... other plugins
    {
      resolve: "medusa-plugin-auth-v2",
      options: {
        // JWT settings
        jwt: {
          secret: process.env.JWT_SECRET,
          expiresIn: "7d"
        },
        // Cookie settings
        cookie: {
          name: "medusa-auth",
          secure: process.env.NODE_ENV === "production",
          maxAge: 1000 * 60 * 60 * 24 * 7 // 7 days
        },
        // OAuth provider configurations
        google: {
          clientID: process.env.GOOGLE_CLIENT_ID,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
          callbackURL: process.env.GOOGLE_CALLBACK_URL,
          // Strategy options
          strategyOptions: {
            scope: ["profile", "email"]
          }
        }
      }
    }
  ]
})

Authentication Flow

The plugin provides these endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /store/auth/google | GET/POST | Starts Google OAuth flow | | /store/auth/google/callback | GET | Google OAuth callback handler | | /auth/success | GET | Success page with user profile information | | /auth/error | GET | Error page with detailed error information |

Migration from v1 to v2

If you're migrating from the v1 version of the plugin, please see our detailed Migration Guide.

Key Changes

1. File-based Routes: Routes now use Medusa v2's file-based routing system
2. Function-based Subscribers: Subscribers now use functions instead of classes
3. Container API Changes: Container registration and resolution patterns have changed
4. New Success/Error Pages: Enhanced pages with user details and error information
5. Enhanced Profile Data: Better handling of user profile information

Troubleshooting

Common Issues

1. Profile Picture Not Displaying: Add referrerpolicy="no-referrer" to image tags for Google profile pictures
2. "resolver.resolve is not a function": This indicates a container resolution issue in Medusa v2
3. Authentication Flow Starts But Never Completes: Check that your callback URLs are correctly configured

Docker Environment Issues

1. Port Conflicts: If ports 9000 or 7001 are already in use, modify the docker-compose.yml file
2. Environment Variables: Ensure all required variables are set in your .env file
3. Container Rebuilding: Use docker-compose up -d --build to rebuild containers after code changes

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License (C) 2025 Paul Pierre