Payload CMS Release: Release 0.19.2

TL;DR

PayloadCMS v0.19.2 introduces extensible authentication strategies, allowing developers to customize how users authenticate beyond the default email/password method. This release adds new authentication hooks, middleware options, and improves TypeScript support for authentication components. It also fixes several bugs related to authentication routing and strategy loading.

This update significantly enhances PayloadCMS's flexibility for implementing custom authentication flows while maintaining backward compatibility with existing implementations.

Highlight of the Release

• Introduction of extensible authentication strategies beyond email/password
• New authentication hooks: afterMe, afterLogout, and afterRefresh
• New middleware options: preMiddleware and postMiddleware (deprecating middleware)
• Improved TypeScript support for authentication components

Migration Guide

Migrating to v0.19.2

Deprecated: middleware option

The middleware option is now deprecated in favor of more specific preMiddleware and postMiddleware options. Update your code as follows:

// Old approach (deprecated)
export default buildConfig({
  collections: [{
    slug: 'users',
    auth: {
      middleware: (req, res, next) => {
        // middleware logic
        next();
      }
    }
  }]
});

// New approach
export default buildConfig({
  collections: [{
    slug: 'users',
    auth: {
      preMiddleware: (req, res, next) => {
        // runs before auth logic
        next();
      },
      postMiddleware: (req, res, next) => {
        // runs after auth logic
        next();
      }
    }
  }]
});

Using New Authentication Hooks

If you need to perform actions after authentication operations, you can now use the new hooks:

export default buildConfig({
  collections: [{
    slug: 'users',
    auth: {
      afterMe: (req, res, user) => {
        // Logic after /me endpoint
        return user; // Can modify user data
      },
      afterLogout: (req, res) => {
        // Logic after logout
      },
      afterRefresh: (req, res, token) => {
        // Logic after token refresh
        return token; // Can modify token
      }
    }
  }]
});

The existing code will continue to work as before, but consider updating to the new patterns for future compatibility.

Upgrade Recommendations

This is a minor release with significant new features but no breaking changes. We recommend all users upgrade to v0.19.2, especially if you:

1. Need custom authentication strategies beyond email/password
2. Want to use the new authentication hooks for custom post-processing
3. Are experiencing any of the bugs fixed in this release

To upgrade:

npm install [email protected]
# or
yarn add [email protected]

If you're using the deprecated middleware option, consider migrating to the new preMiddleware and postMiddleware options, though the deprecated option will continue to work for now.

Bug Fixes

Authentication Bug Fixes

• Fixed issue where anonymous passport strategy wasn't loaded last, which could cause authentication problems
• Removed reliance on authentication email, making the system more flexible for custom auth strategies
• Ensured router switch only contains top-level route components, preventing routing issues
• Fixed configuration merging to ensure only plain objects are merged within incoming configs

New Features

Extensible Authentication Strategies

PayloadCMS now supports custom authentication strategies beyond the default email/password method. This allows developers to implement various authentication providers like OAuth, social logins, or any custom authentication flow.

New Authentication Hooks

• afterMe: Executes after the /me endpoint returns user data
• afterLogout: Runs after a user logs out
• afterRefresh: Triggers after a token refresh operation
• Added res parameter to token hooks for more control

Middleware Improvements

• Added preMiddleware and postMiddleware options
• Deprecated the existing middleware option in favor of these more specific options

Authentication Component Improvements

• Auth component now doesn't render if authentication is disabled
• Better TypeScript types for useAuth and custom provider components
• More properties available for extending authentication strategies

Security Updates

No specific security fixes were mentioned in this release. However, the improvements to authentication strategy handling and configuration may indirectly enhance security by providing more control over authentication flows and reducing potential for misconfiguration.

Performance Improvements

Authentication Strategy Optimization

• Reduced unnecessary strategy complexity
• Improved configuration handling for authentication strategies
• Better organization of authentication components and routes

These improvements help maintain performance while adding significant new authentication capabilities.

Impact Summary

PayloadCMS v0.19.2 significantly enhances the authentication system by introducing extensible authentication strategies. This allows developers to implement custom authentication providers beyond the default email/password method, opening up possibilities for OAuth, social logins, and other authentication flows.

The release adds important new hooks (afterMe, afterLogout, afterRefresh) that provide more control over post-authentication processing. It also introduces more specific middleware options (preMiddleware and postMiddleware) to replace the more generic middleware option.

TypeScript users will benefit from improved types for authentication components and hooks. Several bugs related to authentication routing and strategy loading have been fixed, ensuring more reliable authentication flows.

This update maintains backward compatibility while providing developers with much more flexibility in how they implement and customize authentication in their PayloadCMS projects.

Full Release Notes