feat: auth sessions (#12483)

Adds full session functionality into Payload's existing local authentication strategy. It's enabled by default, because this is a more secure pattern that we should enforce. However, we have provided an opt-out pattern for those that want to stick to stateless JWT authentication by passing `collectionConfig.auth.useSessions: false`. Todo: - [x] @jessrynkar to update the Next.js server functions for refresh and logout to support these new features - [x] @jessrynkar resolve build errors --------- Co-authored-by: Elliot DeNolf <denolfe@gmail.com> Co-authored-by: Jessica Chowdhury <jessica@trbl.design> Co-authored-by: Jarrod Flesch <30633324+JarrodMFlesch@users.noreply.github.com> Co-authored-by: Sasha <64744993+r1tsuu@users.noreply.github.com>

Author: 5 people

docs/authentication/operations.mdx

@@ -180,19 +180,22 @@ As Payload sets HTTP-only cookies, logging out cannot be done by just removing a
 **Example REST API logout**:
 
 ```ts
-const res = await fetch('http://localhost:3000/api/[collection-slug]/logout', {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
+const res = await fetch(
+ 'http://localhost:3000/api/[collection-slug]/logout?allSessions=false',
+ {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
  },
-})
+)
 ```
 
 **Example GraphQL Mutation**:
 
 ```
 mutation {
- logout[collection-singular-label]
+ logoutUser(allSessions: false)
 }
 ```
 
@@ -203,6 +206,10 @@ mutation {
  docs](../local-api/server-functions#reusable-payload-server-functions).
 </Banner>
 
+#### Logging out with sessions enabled
+
+By default, logging out will only end the session pertaining to the JWT that was used to log out with. However, you can pass `allSessions: true` to the logout operation in order to end all sessions for the user logging out.
+
 ## Refresh
 
 Allows for "refreshing" JWTs. If your user has a token that is about to expire, but the user is still active and using the app, you might want to use the `refresh` operation to receive a new token by executing this operation via the authenticated user.

docs/authentication/overview.mdx

@@ -91,6 +91,7 @@ The following options are available:
 | **`strategies`** | Advanced - an array of custom authentication strategies to extend this collection's authentication with. [More details](./custom-strategies). |
 | **`tokenExpiration`** | How long (in seconds) to keep the user logged in. JWTs and HTTP-only cookies will both expire at the same time. |
 | **`useAPIKey`** | Payload Authentication provides for API keys to be set on each user within an Authentication-enabled Collection. [More details](./api-keys). |
+| **`useSessions`** | True by default. Set to `false` to use stateless JWTs for authentication instead of sessions. |
 | **`verify`** | Set to `true` or pass an object with verification options to require users to verify by email before they are allowed to log into your app. [More details](./email#email-verification). |
 
 ### Login With Username

docs/local-api/server-functions.mdx

@@ -393,15 +393,15 @@ export default function LoginForm() {
 
 ### Logout
 
-Logs out the current user by clearing the authentication cookie.
+Logs out the current user by clearing the authentication cookie and current sessions.
 
 #### Importing the `logout` function
 
 ```ts
 import { logout } from '@payloadcms/next/auth'
 ```
 
-Similar to the login function, you now need to pass your Payload config to this function and this cannot be done in a client component. Use a helper server function as shown below.
+Similar to the login function, you now need to pass your Payload config to this function and this cannot be done in a client component. Use a helper server function as shown below. To ensure all sessions are cleared, set `allSessions: true` in the options, if you wish to logout but keep current sessions active, you can set this to `false` or leave it `undefined`.
 
 ```ts
 'use server'
@@ -411,7 +411,7 @@ import config from '@payload-config'
 
 export async function logoutAction() {
  try {
- return await logout({ config })
+ return await logout({ allSessions: true, config })
  } catch (error) {
  throw new Error(
  `Logout failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
@@ -434,7 +434,7 @@ export default function LogoutButton() {
 
 ### Refresh
 
-Refreshes the authentication token for the logged-in user.
+Refreshes the authentication token and current session for the logged-in user.
 
 #### Importing the `refresh` function
 
@@ -453,7 +453,6 @@ import config from '@payload-config'
 export async function refreshAction() {
  try {
  return await refresh({
- collection: 'users', // pass your collection slug
  config,
  })
  } catch (error) {

docs/plugins/sentry.mdx

@@ -74,9 +74,7 @@ import * as Sentry from '@sentry/nextjs'
 
 const config = buildConfig({
  collections: [Pages, Media],
- plugins: [
- sentryPlugin({ Sentry })
- ],
+ plugins: [sentryPlugin({ Sentry })],
 })
 
 export default config
@@ -98,9 +96,7 @@ export default buildConfig({
  pool: { connectionString: process.env.DATABASE_URL },
  pg, // Inject the patched pg driver for Sentry instrumentation
  }),
- plugins: [
- sentryPlugin({ Sentry })
- ],
+ plugins: [sentryPlugin({ Sentry })],
 })
 ```
 

packages/graphql/src/resolvers/auth/logout.ts

@@ -7,6 +7,7 @@ import type { Context } from '../types.js'
 export function logout(collection: Collection): any {
  async function resolver(_, args, context: Context) {
  const options = {
+ allSessions: args.allSessions,
  collection,
  req: isolateObjectProperty(context.req, 'transactionID'),
  }

packages/graphql/src/schema/initCollections.ts

@@ -487,6 +487,9 @@ export function initCollections({ config, graphqlResult }: InitCollectionsGraphQ
 
  graphqlResult.Mutation.fields[`logout${singularName}`] = {
  type: GraphQLString,
+ args: {
+ allSessions: { type: GraphQLBoolean },
+ },
  resolve: logout(collection),
  }
 

packages/next/src/auth/logout.ts

@@ -1,24 +1,46 @@
 'use server'
 
+import type { SanitizedConfig } from 'payload'
+
 import { cookies as getCookies, headers as nextHeaders } from 'next/headers.js'
-import { getPayload } from 'payload'
+import { createLocalReq, getPayload, logoutOperation } from 'payload'
 
 import { getExistingAuthToken } from '../utilities/getExistingAuthToken.js'
 
-export async function logout({ config }: { config: any }) {
+export async function logout({
+ allSessions = false,
+ config,
+}: {
+ allSessions?: boolean
+ config: Promise<SanitizedConfig> | SanitizedConfig
+}) {
  const payload = await getPayload({ config })
  const headers = await nextHeaders()
- const result = await payload.auth({ headers })
+ const authResult = await payload.auth({ headers })
 
- if (!result.user) {
+ if (!authResult.user) {
  return { message: 'User already logged out', success: true }
  }
 
- const existingCookie = await getExistingAuthToken(payload.config.cookiePrefix)
+ const { user } = authResult
+ const req = await createLocalReq({ user }, payload)
+ const collection = payload.collections[user.collection]
 
+ const logoutResult = await logoutOperation({
+ allSessions,
+ collection,
+ req,
+ })
+
+ if (!logoutResult) {
+ return { message: 'Logout failed', success: false }
+ }
+
+ const existingCookie = await getExistingAuthToken(payload.config.cookiePrefix)
  if (existingCookie) {
  const cookies = await getCookies()
  cookies.delete(existingCookie.name)
- return { message: 'User logged out successfully', success: true }
  }
+
+ return { message: 'User logged out successfully', success: true }
 }

packages/next/src/auth/refresh.ts

@@ -3,33 +3,45 @@
 import type { CollectionSlug } from 'payload'
 
 import { headers as nextHeaders } from 'next/headers.js'
-import { getPayload } from 'payload'
+import { createLocalReq, getPayload, refreshOperation } from 'payload'
 
 import { getExistingAuthToken } from '../utilities/getExistingAuthToken.js'
 import { setPayloadAuthCookie } from '../utilities/setPayloadAuthCookie.js'
 
-export async function refresh({ collection, config }: { collection: CollectionSlug; config: any }) {
+export async function refresh({ config }: { config: any }) {
  const payload = await getPayload({ config })
- const authConfig = payload.collections[collection]?.config.auth
+ const headers = await nextHeaders()
+ const result = await payload.auth({ headers })
 
- if (!authConfig) {
+ if (!result.user) {
+ throw new Error('Cannot refresh token: user not authenticated')
+ }
+
+ const collection: CollectionSlug | undefined = result.user.collection
+ const collectionConfig = payload.collections[collection]
+
+ if (!collectionConfig?.config.auth) {
  throw new Error(`No auth config found for collection: ${collection}`)
  }
 
- const { user } = await payload.auth({ headers: await nextHeaders() })
+ const req = await createLocalReq({ user: result.user }, payload)
 
- if (!user) {
- throw new Error('User not authenticated')
+ const refreshResult = await refreshOperation({
+ collection: collectionConfig,
+ req,
+ })
+
+ if (!refreshResult) {
+ return { message: 'Token refresh failed', success: false }
  }
 
  const existingCookie = await getExistingAuthToken(payload.config.cookiePrefix)
-
  if (!existingCookie) {
- return { message: 'No valid token found', success: false }
+ return { message: 'No valid token found to refresh', success: false }
  }
 
  await setPayloadAuthCookie({
- authConfig,
+ authConfig: collectionConfig.config.auth,
  cookiePrefix: payload.config.cookiePrefix,
  token: existingCookie.value,
  })

packages/payload/src/auth/baseFields/sessions.ts

@@ -0,0 +1,32 @@
+import type { ArrayField } from '../../fields/config/types.js'
+
+export const sessionsFieldConfig: ArrayField = {
+ name: 'sessions',
+ type: 'array',
+ access: {
+ read: ({ doc, req: { user } }) => {
+ return user?.id === doc?.id
+ },
+ update: () => false,
+ },
+ admin: {
+ disabled: true,
+ },
+ fields: [
+ {
+ name: 'id',
+ type: 'text',
+ required: true,
+ },
+ {
+ name: 'createdAt',
+ type: 'date',
+ defaultValue: () => new Date(),
+ },
+ {
+ name: 'expiresAt',
+ type: 'date',
+ required: true,
+ },
+ ],
+}

packages/payload/src/auth/endpoints/logout.ts

@@ -9,8 +9,10 @@ import { logoutOperation } from '../operations/logout.js'
 
 export const logoutHandler: PayloadHandler = async (req) => {
  const collection = getRequestCollection(req)
- const { t } = req
+ const { searchParams, t } = req
+
  const result = await logoutOperation({
+ allSessions: searchParams.get('allSessions') === 'true',
  collection,
  req,
  })