Best practices for Custom OAuth/Social Login & Session Management

[shestakov2103]

Hi everyone!

I am implementing a custom Social Login (OAuth) flow in Payload CMS 3 that interacts with a Nuxt.js frontend.

My current handler logic is as follows:

• Nuxt sends user info (email, provider, externalId) to a custom Payload endpoint.
• The handler finds or creates a user in the users collection.
• It generates a token using jwtSign and returns it.

Payload-native approach: Is there a way to trigger Payload's internal login logic (which handles session persistence automatically) from within a custom handler, rather than re-implementing jwtSign and manual DB updates?

Here is my current oauthLoginHandler.ts:

export const oauthLoginHandler: PayloadHandler = async (req) => {
    const data = await req.json?.()
    const { email, name, provider, externalId } = data

    if (process.env.INTERNAL_SECRET_KEY === req.headers.get('x-internal-secret')) {
        if (provider && externalId) {
            let user = await req.payload
                .find({
                    collection: 'users',
                    where: {
                        and: [{ provider: { equals: provider } }, { externalId: { equals: externalId } }],
                    },
                    depth: 0,
                })
                .then((res) => res.docs[0])

            if (!user && email) {
                user = await req.payload.create({
                    collection: 'users',
                    data: {
                        email,
                        name,
                        provider,
                        externalId,
                        password: crypto.randomBytes(32).toString('hex'),
                        role: 'user',
                        _verified: true,
                    },
                })
            }

            if (user) {
                const { sid } = await addSessionToUser({
                    collectionConfig: req.payload.collections['users'].config,
                    payload: req.payload,
                    req,
                    user,
                })

                const fieldsToSign = getFieldsToSign({
                    collectionConfig: req.payload.collections['users'].config,
                    email: user.email,
                    sid,
                    user: user,
                })

                const token = await jwtSign({
                    fieldsToSign,
                    secret: req.payload.secret,
                    tokenExpiration: req.payload.collections['users'].config.auth.tokenExpiration,
                })

                const cookie = generatePayloadCookie({
                    collectionAuthConfig: req.payload.collections['users'].config.auth,
                    cookiePrefix: req.payload.config.cookiePrefix,
                    token: token.token,
                    returnCookieAsObject: false,
                })

                return Response.json(
                    { user, token: token.token, exp: token.exp },
                    {
                        status: 200,
                        headers: {
                            'Set-Cookie': cookie,
                        },
                    },
                )
            }
        }
    }

    return new Response(null, { status: 404 })
}

[phlppgdfry]

You are close — the missing piece is using Payload's built-in generatePayloadCookie utility to produce the session cookie instead of calling jwtSign yourself.

Payload v3 exposes generatePayloadCookie from payload (re-exported from payload/utilities in some versions). Combined with payload.sign() (or the JWT utilities on req.payload), you can piggyback on Payload's own session machinery without re-implementing it.

Here is a cleaner version of your handler:

import type { PayloadHandler } from 'payload'
import { generatePayloadCookie, getCookieExpiration } from 'payload/utilities'

export const oauthLoginHandler: PayloadHandler = async (req) => {
  const data = await req.json?.()
  const { email, name, provider, externalId } = data

  if (process.env.INTERNAL_SECRET_KEY !== req.headers.get('x-internal-secret')) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const payload = req.payload
  const collectionConfig = payload.collections['users'].config

  // Find or create the user
  let user = await payload
    .find({
      collection: 'users',
      where: { and: [{ provider: { equals: provider } }, { externalId: { equals: externalId } }] },
      depth: 0,
    })
    .then((res) => res.docs[0])

  if (!user && email) {
    user = await payload.create({
      collection: 'users',
      data: {
        email,
        name,
        provider,
        externalId,
        password: crypto.randomBytes(32).toString('hex'),
        role: 'user',
        _verified: true,
      },
    })
  }

  if (!user) {
    return Response.json({ error: 'User not found and could not be created' }, { status: 400 })
  }

  // Use Payload's own JWT signing — same secret and expiry as a normal login
  const token = await payload.sign(
    { id: user.id, email: user.email, collection: 'users' },
    collectionConfig.auth.tokenExpiration,
  )

  // Generate the HTTP-only cookie Payload normally sets on login
  const cookie = generatePayloadCookie({
    collectionAuthConfig: collectionConfig.auth,
    cookiePrefix: payload.config.cookiePrefix,
    token,
  })

  return Response.json(
    { user, token },
    {
      status: 200,
      headers: { 'Set-Cookie': cookie },
    },
  )
}

Key points

• payload.sign() uses the same secret Payload uses internally, so the resulting JWT is identical to what a normal email/password login produces.
• generatePayloadCookie() produces the correctly configured HttpOnly; SameSite=Lax; Path=/ cookie string that Payload's /api/users/login endpoint sets — you do not need to construct it manually.
• collectionConfig.auth.tokenExpiration reads the expiry you configured in your users collection, keeping it DRY.

Security note

The x-internal-secret header guard is fine for a same-host scenario, but make sure your Nuxt app and Payload are not on separate publicly-accessible origins where that header could be spoofed. If they are, consider using the OAuth state parameter or a short-lived PKCE verifier instead of a shared secret.