Most PayloadCMS authentication examples focus on basic email and password flows or simplified OAuth demonstrations. These approaches rarely hold up once real operational requirements are introduced, such as multiple frontends, native applications, or external identity providers.
As a result, teams often end up working against the framework. Session state is pushed through layers where it does not belong, req.user is referenced before any session exists, and admin authentication becomes tightly coupled to application authentication. These shortcuts may work initially, but they become increasingly difficult to reason about as the system scales.
In practice, authentication is the most fragile part of a headless architecture when it is treated as an afterthought. It is also the area least suited to reactive fixes under pressure. This is why Payload v3’s shift toward explicit custom authentication strategies is significant. It restores architectural control while also requiring teams to treat authentication as a first class design concern rather than a convenience feature.
Rethinking auth
The core shift is conceptual. Payload should not be viewed as the component responsible for authenticating users. Instead, it should be treated as a system that trusts identities that have already been verified elsewhere. Your identity provider, whether Google, a specialist authentication service, or a custom OAuth server, owns the authentication ceremony, including PKCE, redirects, device flows, and magic links.
Payload’s responsibility is narrower and more precise. Given verifiable proof of identity on an incoming request, such as headers, tokens, or cookies, it must resolve that identity to a user record and, where appropriate, create or update that record. This separation of concerns is exactly what custom authentication strategies are designed to support.
A custom strategy receives the request context and answers a single question: which user, if any, does this request represent? Once this contract is enforced, the architecture naturally becomes clearer. Frontend applications handle OAuth flows explicitly, while Payload focuses on enforcing access control using consistent and trusted user data.
Production
Most issues emerge at the boundaries. Administrative users and application users are rarely interchangeable. External integrations often require service accounts or API keys that bypass interactive login entirely. Mobile applications need authentication paths that never touch the admin interface.
When teams rely on ad hoc solutions, such as logging in through the admin UI and reusing that session, authentication logic becomes fragmented across routes, hooks, and middleware. This fragmentation makes systems harder to test, harder to audit, and harder to evolve.
A strategy driven approach enforces centralisation. One strategy can map signed tokens from an OAuth provider to a user collection. Another can handle internal service credentials. A third can be reserved exclusively for administrative access. This structure is easier to reason about, simpler to validate, and significantly easier to replace when identity requirements change.
OAuth wiring
The full implementation that prompted this discussion is documented on the Rubix Studios blog. It walks through a complete Payload v3 configuration, from the OAuth flow to collection setup and the custom authentication strategy itself. It also demonstrates how to keep the CMS stateless while preserving a practical admin experience.
For teams already using Payload, or planning a migration, this walkthrough provides a production ready reference rather than a contrived example:
PayloadCMS Custom Auth Strategy on Rubix Studios
Top comments (0)