payload-workos-oauth

WorkOS OAuth plugin for Payload CMS - adds Google OAuth login to your Payload admin panel.

Features

• 🔐 Google OAuth authentication via WorkOS
• 🎨 Clean, customizable login button
• 🔒 Admin-only access control
• 🍪 JWT-based authentication with secure cookies
• ⚡ No session middleware required
• 🎯 Easy integration with existing Payload CMS projects

Installation

npm install payload-workos-oauth

Prerequisites

1. A WorkOS account
2. Google OAuth configured in your WorkOS dashboard
3. Payload CMS v2.0.0 or higher

Usage

1. Configure the plugin in your Payload config

import { buildConfig } from "payload/config";
import { workosOAuthPlugin } from "payload-workos-oauth";

export default buildConfig({
  // ... other config
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  plugins: [
    workosOAuthPlugin({
      clientID: process.env.WORKOS_CLIENT_ID || "",
      clientSecret: process.env.WORKOS_API_KEY || "",
      callbackURL: `${process.env.PAYLOAD_PUBLIC_SERVER_URL}/workos-oauth/callback`,
      buttonLabel: "Sign in with Google",
    }),
  ],
});

2. Set environment variables

WORKOS_CLIENT_ID=your_workos_client_id
WORKOS_API_KEY=your_workos_api_key
PAYLOAD_PUBLIC_SERVER_URL=https://your-domain.com

3. Configure WorkOS

In your WorkOS dashboard:

1. Add a redirect URI: https://your-domain.com/workos-oauth/callback
2. Enable Google OAuth provider
3. Copy your Client ID and API Key

4. Ensure users have admin role

Only users with role: 'admin' can log in via OAuth. Make sure your users collection has this field configured.

Configuration Options

Option	Type	Required	Description
clientID	string	Yes	Your WorkOS Client ID
clientSecret	string	Yes	Your WorkOS API Key
callbackURL	string	Yes	The OAuth callback URL
buttonLabel	string	No	Custom button text (default: "Sign in with Google")
hideDefaultLogin	boolean	No	Hide the default email/password login form (default: false)
authorizePath	string	No	Custom authorization endpoint path (default: "/workos-oauth/authorize")
callbackPath	string	No	Custom callback endpoint path (default: "/workos-oauth/callback")
successRedirect	string	No	Custom redirect after login (default: "/admin")
components.Button	React.ComponentType	No	Custom button component

Hide Default Login Form

If you want to show only the OAuth button and hide the default email/password login form, set hideDefaultLogin to true:

workosOAuthPlugin({
  clientID: process.env.WORKOS_CLIENT_ID || "",
  clientSecret: process.env.WORKOS_API_KEY || "",
  callbackURL: `${process.env.PAYLOAD_PUBLIC_SERVER_URL}/workos-oauth/callback`,
  buttonLabel: "Sign in with Google",
  hideDefaultLogin: true, // This will hide the email/password form
});

When hideDefaultLogin is enabled:

• Only the OAuth button will be displayed on the login page
• The default email/password form will be hidden
• The "OR" divider will not be shown

Custom Button Component

You can provide your own button component:

import CustomButton from "./CustomButton";

workosOAuthPlugin({
  // ... other options
  components: {
    Button: CustomButton,
  },
});

Your custom button component will receive these props:

interface ButtonProps {
  authorizePath: string;
  buttonLabel: string;
}

How It Works

1. User clicks "Sign in with Google" on the Payload admin login page
2. User is redirected to WorkOS/Google OAuth
3. User authenticates with Google
4. WorkOS redirects back to your callback URL with an authorization code
5. Plugin exchanges the code for user profile information
6. Plugin finds the user in Payload by email (must have role: 'admin')
7. Plugin generates a JWT token and sets a secure cookie
8. User is redirected to the admin dashboard

Security

• Only users with role: 'admin' can authenticate via OAuth
• JWT tokens are signed with your Payload secret
• Cookies are set with httpOnly flag for security
• All server-side modules are properly isolated from client bundle

License

MIT

Author

Bibek Thapa

Contributing

Contributions are welcome! Please open an issue or submit a pull request.