payload-auth-plugin

The template is designed as a full-stack application where the Payload backend and a Next.js frontend are served together.

Core Backend Components

• Collections: Includes Users (auth-enabled), Posts (draft-enabled, layout builder enabled), Pages (draft-enabled, layout builder enabled), Media (uploads enabled with pre-configured sizes), and Categories (nested taxonomy).
• Globals: Includes Header and Footer for managing site-wide navigation and footer data.
• Access Control: Pre-configured to allow everyone to see published posts and pages, while restricting creation/editing to users.

Core Frontend Components

• Next.js App Router: Powers the production-ready website.
• Layout Builder: Uses pre-designed blocks (Hero, Content, Media, Call To Action, Archive) to build unique page layouts.
• Lexical Editor: Provides a rich text experience supporting blocks, media, and links.
• Previewing: Supports both Draft Preview (using Versions with drafts: true) and Live Preview (with SSR support).
• On-demand Revalidation: Uses Next.js revalidation triggered by afterChange hooks to update the static frontend when content is published.

# Method 1: Recommended (via Payload Cloud)
# Go to Payload Cloud and clone this template: https://payloadcms.com/new/clone/website

# Method 2: Using create-payload-app CLI
pnpx create-payload-app my-project -t website

# Method 3: Using git sparse-checkout
git clone -n --depth=1 --filter=tree:0 https://github.com/payloadcms/payload my-project && cd my-project && git sparse-checkout set --no-cone templates/website && git checkout && rm -rf .git && git init && git add . && git mv -f templates/website/{.,}* . && git add . && git commit -m "Initial commit"

# Local Development Steps
cd my-project
cp .env.example .env
pnpm install && pnpm dev

When using withUsersCollection or withAccountCollection, the plugin follows a merge-then-override pattern. This allows you to extend the collections without redefining the entire configuration.

Override Rules

1. Fields: Plugin base fields are merged with your custom fields. For users, plugin fields are appended after yours; for accounts, plugin fields are prepended before yours.
2. Access: Plugin default access rules are applied first, then your access keys overwrite the corresponding defaults.
3. Admin: Plugin default admin config is applied first, then your admin keys overwrite them.
4. Timestamps: timestamps: true is automatically and always set on both collections.

Because of this pattern, you only need to specify the specific keys you wish to change; all other settings fall back to the plugin's defaults.

// Only override what you need
export const Users: CollectionConfig = withUsersCollection({
  slug: 'users',
  fields: [{ name: 'role', type: 'text' }],
  access: {
    read: () => true,          // override: allow public reads
    // create / delete / update → remain as plugin defaults
  },
  admin: {
    useAsTitle: 'email',       // override: display email in the admin list title
    // defaultColumns → remains as plugin default (['name', 'email'])
  },
})

Since the identifier is configurable, you can register multiple Keycloak providers for different realms within the same application. This allows you to support different SSO providers (e.g., one for employees and one for partners) simultaneously.

1. Define each provider with a unique identifier and name in authPlugin.
2. Register the corresponding callback URLs in each respective Keycloak realm using the pattern: https://your-domain.com/api/{name}/oauth/callback/{identifier}.
3. On the client, call oauth(identifier) using the specific identifier for the desired realm.

// Configuration
providers: [
  KeyCloakAuthProvider({
    realm: 'employees',
    domain: process.env.KEYCLOAK_DOMAIN!,
    identifier: 'keycloak-employees',
    name: 'Employee SSO',
    client_id: process.env.KEYCLOAK_EMPLOYEE_CLIENT_ID!,
    client_secret: process.env.KEYCLOAK_EMPLOYEE_CLIENT_SECRET!,
  }),
  KeyCloakAuthProvider({
    realm: 'partners',
    domain: process.env.KEYCLOAK_DOMAIN!,
    identifier: 'keycloak-partners',
    name: 'Partner SSO',
    client_id: process.env.KEYCLOAK_PARTNER_CLIENT_ID!,
    client_secret: process.env.KEYCLOAK_PARTNER_CLIENT_SECRET!,
  }),
]

// Client Usage
const { oauth } = authClient.signin()
<button onClick={() => oauth('keycloak-employees')}>Employee SSO</button>
<button onClick={() => oauth('keycloak-partners')}>Partner SSO</button>

Custom Scopes

By default, the provider requests openid profile email. To request additional Microsoft Graph API scopes (e.g., User.Read, Calendars.Read), use overrideScope. Note: You must also add these permissions in the Azure Portal under API permissions.

MicrosoftEntraAuthProvider({
  client_id: process.env.MSFT_ENTRA_CLIENT_ID!,
  client_secret: process.env.MSFT_ENTRA_CLIENT_SECRET!,
  tenant_id: process.env.MSFT_ENTRA_TENANT_ID!,
  overrideScope: 'openid profile email User.Read Calendars.Read',
})

Tenant Types

The tenant_id determines which users can sign in:

To allow all Microsoft accounts, use tenant_id: 'common' and ensure your Azure app registration is set to Multitenant.

MicrosoftEntraAuthProvider({
  client_id: process.env.MSFT_ENTRA_CLIENT_ID!,
  client_secret: process.env.MSFT_ENTRA_CLIENT_SECRET!,
  tenant_id: 'common',
})