Payload Auth Example

This Payload Auth Example demonstrates how to implement Payload Authentication into all types of applications. Follow the Quick Start to get up and running quickly.

Quick Start

To spin up this example locally, follow the steps below:

1. Run the following command to create a project from the example:

• npx create-payload-app --example auth

2. Ensure MongoDB is running:

   • This example uses the MongoDB adapter and requires an accessible MongoDB instance.
   • Configure DATABASE_URL in your .env (you can start from .env.example), for example:
     • DATABASE_URL=mongodb://127.0.0.1/payload-example-auth
   • If your MongoDB instance requires authentication, include your credentials in DATABASE_URL.

3. Start the server:

   • Depending on your package manager, run pnpm dev, yarn dev or npm run dev
   • When prompted, type y then enter to seed the database with sample data

4. Access the application:

   • Open your browser and navigate to http://localhost:3000 to access the homepage.
   • Open http://localhost:3000/admin to access the admin panel.

5. Login:

• Use the following credentials to log into the admin panel:

  Email: [email protected] > Password: demo

How it works

Collections

See the Collections docs for details on how to extend this functionality.

• Users (Authentication)

  Users are auth-enabled and encompass both admins and regular users based on the value of their roles field. Only admin users can access your admin panel to manage your content whereas user can authenticate on your front-end and access-controlled interfaces. See Access Control for more details.

  Local API

  On the server, Payload provides all operations needed to authenticate users server-side using the Local API. In Next.js that might look something like this:

  tsCopy

    import { headers as getHeaders } from 'next/headers.js'
    import { getPayload } from 'payload'
    import config from '../../payload.config'
  
    export default async function AccountPage({ searchParams }) {
      const headers = await getHeaders()
      const payload = await getPayload({ config: configPromise })
      const { permissions, user } = await payload.auth({ headers })
  
      if (!user) {
        redirect(
          `/login?error=${encodeURIComponent('You must be logged in to access your account.')}&redirect=/account`,
        )
      }
  
      return ...
    }
  

  HTTP

  The users collection also opens an http-layer to expose all auth-related operations through the REST and GraphQL APIs, including:

  • Me
  • Login
  • Logout
  • Refresh Token
  • Verify Email
  • Unlock
  • Forgot Password
  • Reset Password

  This might look something like this:

  tsCopy

  await fetch('/api/users/me', {
    method: 'GET',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
    },
  })
  

  NOTE: You can still use the HTTP APIs on the server if you don't have access to the Local API.

Security

The cors, csrf, and cookies settings are all configured to ensure that the admin panel and front-end can communicate with each other securely.

For additional help, see the Authentication docs.

Access Control

Basic role-based access control is setup to determine what users can and cannot do based on their roles, which are:

• admin: They can access the Payload admin panel to manage your application. They can see all data and make all operations.
• user: They cannot access the Payload admin panel and have a limited access to operations based on their user.

A beforeChange field hook called protectRoles is placed on this to automatically populate roles with the user role when a new user is created. It also protects roles from being changed by non-admins.

Development

To spin up this example locally, follow the Quick Start.

Seed

On boot, a seed migration performed to create a user with email [email protected], password demo, the role admin.

NOTICE: seeding the database is destructive because it drops your current database to populate a fresh one from the seed template. Only run this command if you are starting a new project or can afford to lose your current data.

Production

To run Payload in production, you need to build and serve the Admin panel. To do so, follow these steps:

1. First invoke the payload build script by running pnpm build, yarn build, or npm run build in your project root. This creates a ./build directory with a production-ready admin bundle.
2. Then run pnpm serve, yarn serve, or npm run serve to run Node.js in production and serve Payload from the ./build directory.

Deployment

If you are using an integrated Next.js setup, the easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js. Otherwise, easiest way to deploy your project is to use Payload Cloud, a one-click hosting solution to deploy production-ready instances of your Payload apps directly from your GitHub repo. You can also deploy your app manually, check out the deployment documentation for full details.

Questions

If you have any issues or questions, reach out to us on Discord or start a GitHub discussion.