feat: ability to login with email, username or both (#7086)

`auth.loginWithUsername`:

```ts
auth: {
  loginWithUsername: {
    allowEmailLogin: true, // default: false
    requireEmail: false, // default: false
  }
}
```

#### `allowEmailLogin`
This property will allow you to determine if users should be able to
login with either email or username. If set to `false`, the default
value, then users will only be able to login with usernames when using
the `loginWithUsername` property.

#### `requireEmail`
Require that users also provide emails when using usernames.

Author: JarrodMFlesch

docs/authentication/overview.mdx

@@ -83,12 +83,50 @@ The following options are available:
 | **`disableLocalStrategy`** | Advanced - disable Payload's built-in local auth strategy. Only use this property if you have replaced Payload's auth mechanisms with your own.                                                                                     |
 | **`forgotPassword`**       | Customize the way that the `forgotPassword` operation functions. [More details](./email#forgot-password).                                                                                                             |
 | **`lockTime`**             | Set the time (in milliseconds) that a user should be locked out if they fail authentication more times than `maxLoginAttempts` allows for.                                                                                          |
+| **`loginWithUsername`**    | Ability to allow users to login with username/password. [More](/docs/authentication/overview#login-with-username)                                                                                                                     |
 | **`maxLoginAttempts`**     | Only allow a user to attempt logging in X amount of times. Automatically locks out a user from authenticating if this limit is passed. Set to `0` to disable.                                                                       |
 | **`strategies`**           | Advanced - an array of custom authentification 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).                                                                       |
 | **`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
+
+You can allow users to login with their username instead of their email address by setting the `loginWithUsername` property to `true`.
+
+Example:
+
+```ts
+{
+  slug: 'customers',
+  auth: {
+    loginWithUsername: true,
+  },
+}
+```
+
+Or, you can pass an object with additional options:
+
+```ts
+{
+  slug: 'customers',
+  auth: {
+    loginWithUsername: {
+      allowEmailLogin: true, // default: false
+      requireEmail: false, // default: false
+    },
+  },
+}
+```
+
+**`allowEmailLogin`**
+
+If set to `true`, users can log in with either their username or email address. If set to `false`, users can only log in with their username.
+
+**`requireEmail`**
+
+If set to `true`, an email address is required when creating a new user. If set to `false`, email is not required upon creation.
+
 ## Admin Auto-Login
 
 For testing and demo purposes you may want to skip forcing the admin user to login in order to access the [Admin Panel](../admin/overview). Typically, all users should be required to login to access the Admin Panel, however, you can speed up local development time by enabling auto-login.

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

@@ -8,7 +8,7 @@ function unlockResolver(collection: Collection) {
   async function resolver(_, args, context: Context) {
     const options = {
       collection,
-      data: { email: args.email },
+      data: { email: args.email, username: args.username },
       req: isolateObjectProperty(context.req, 'transactionID'),
     }
 

packages/graphql/src/schema/initCollections.ts

@@ -429,12 +429,24 @@ function initCollectionsGraphQL({ config, graphqlResult }: InitCollectionsGraphQ
       }
 
       if (!collectionConfig.auth.disableLocalStrategy) {
+        const authArgs = {}
+
+        const canLoginWithEmail =
+          !collectionConfig.auth.loginWithUsername ||
+          collectionConfig.auth.loginWithUsername?.allowEmailLogin
+        const canLoginWithUsername = collectionConfig.auth.loginWithUsername
+
+        if (canLoginWithEmail) {
+          authArgs['email'] = { type: new GraphQLNonNull(GraphQLString) }
+        }
+        if (canLoginWithUsername) {
+          authArgs['username'] = { type: new GraphQLNonNull(GraphQLString) }
+        }
+
         if (collectionConfig.auth.maxLoginAttempts > 0) {
           graphqlResult.Mutation.fields[`unlock${singularName}`] = {
             type: new GraphQLNonNull(GraphQLBoolean),
-            args: {
-              email: { type: new GraphQLNonNull(GraphQLString) },
-            },
+            args: authArgs,
             resolve: unlock(collection),
           }
         }
@@ -455,9 +467,8 @@ function initCollectionsGraphQL({ config, graphqlResult }: InitCollectionsGraphQ
             },
           }),
           args: {
-            email: { type: GraphQLString },
+            ...authArgs,
             password: { type: GraphQLString },
-            username: { type: GraphQLString },
           },
           resolve: login(collection),
         }
@@ -466,8 +477,8 @@ function initCollectionsGraphQL({ config, graphqlResult }: InitCollectionsGraphQ
           type: new GraphQLNonNull(GraphQLBoolean),
           args: {
             disableEmail: { type: GraphQLBoolean },
-            email: { type: new GraphQLNonNull(GraphQLString) },
             expiration: { type: GraphQLInt },
+            ...authArgs,
           },
           resolve: forgotPassword(collection),
         }

packages/next/src/routes/rest/auth/unlock.ts

@@ -8,9 +8,18 @@ import { headersWithCors } from '../../../utilities/headersWithCors.js'
 export const unlock: CollectionRouteHandler = async ({ collection, req }) => {
   const { t } = req
 
+  const authData = collection.config.auth?.loginWithUsername
+    ? {
+        email: typeof req.data?.email === 'string' ? req.data.email : '',
+        username: typeof req.data?.username === 'string' ? req.data.username : '',
+      }
+    : {
+        email: typeof req.data?.email === 'string' ? req.data.email : '',
+      }
+
   await unlockOperation({
     collection,
-    data: { email: req.data.email as string },
+    data: authData,
     req,
   })
 

packages/next/src/views/Edit/Default/Auth/index.tsx

@@ -98,14 +98,16 @@ export const Auth: React.FC<Props> = (props) => {
     <div className={[baseClass, className].filter(Boolean).join(' ')}>
       {!disableLocalStrategy && (
         <React.Fragment>
-          {!loginWithUsername && (
+          {(!loginWithUsername ||
+            loginWithUsername?.allowEmailLogin ||
+            loginWithUsername?.requireEmail) && (
             <EmailField
               autoComplete="email"
               disabled={disabled}
               label={t('general:email')}
               name="email"
               readOnly={readOnly}
-              required
+              required={!loginWithUsername || loginWithUsername?.requireEmail}
             />
           )}
           {loginWithUsername && (

packages/next/src/views/Edit/Default/Auth/types.ts

@@ -5,7 +5,7 @@ export type Props = {
   collectionSlug: SanitizedCollectionConfig['slug']
   disableLocalStrategy?: boolean
   email: string
-  loginWithUsername: boolean
+  loginWithUsername: SanitizedCollectionConfig['auth']['loginWithUsername']
   operation: 'create' | 'update'
   readOnly: boolean
   requirePassword?: boolean

packages/next/src/views/Login/LoginField/index.tsx

@@ -0,0 +1,109 @@
+'use client'
+import type { PayloadRequest } from 'payload'
+
+import { EmailField, TextField, useConfig, useTranslation } from '@payloadcms/ui'
+import { email, username } from 'payload/shared'
+import React from 'react'
+export type LoginFieldProps = {
+  type: 'email' | 'emailOrUsername' | 'username'
+}
+export const LoginField: React.FC<LoginFieldProps> = ({ type }) => {
+  const { t } = useTranslation()
+  const config = useConfig()
+
+  if (type === 'email') {
+    return (
+      <EmailField
+        autoComplete="email"
+        label={t('general:email')}
+        name="email"
+        required
+        validate={(value) =>
+          email(value, {
+            name: 'email',
+            type: 'email',
+            data: {},
+            preferences: { fields: {} },
+            req: { t } as PayloadRequest,
+            required: true,
+            siblingData: {},
+          })
+        }
+      />
+    )
+  }
+
+  if (type === 'username') {
+    return (
+      <TextField
+        label={t('authentication:username')}
+        name="username"
+        required
+        validate={(value) =>
+          username(value, {
+            name: 'username',
+            type: 'text',
+            data: {},
+            preferences: { fields: {} },
+            req: {
+              payload: {
+                config,
+              },
+              t,
+            } as PayloadRequest,
+            required: true,
+            siblingData: {},
+          })
+        }
+      />
+    )
+  }
+
+  if (type === 'emailOrUsername') {
+    return (
+      <TextField
+        label={t('authentication:emailOrUsername')}
+        name="username"
+        required
+        validate={(value) => {
+          const passesUsername = username(value, {
+            name: 'username',
+            type: 'text',
+            data: {},
+            preferences: { fields: {} },
+            req: {
+              payload: {
+                config,
+              },
+              t,
+            } as PayloadRequest,
+            required: true,
+            siblingData: {},
+          })
+          const passesEmail = email(value, {
+            name: 'username',
+            type: 'email',
+            data: {},
+            preferences: { fields: {} },
+            req: {
+              payload: {
+                config,
+              },
+              t,
+            } as PayloadRequest,
+            required: true,
+            siblingData: {},
+          })
+
+          if (!passesEmail && !passesUsername) {
+            return `${t('general:email')}: ${passesEmail} ${t('general:username')}: ${passesUsername}`
+          }
+
+          return true
+        }}
+      />
+    )
+  }
+
+  return null
+}

packages/next/src/views/Login/LoginForm/index.tsx

@@ -8,17 +8,12 @@ const Link = (LinkImport.default || LinkImport) as unknown as typeof LinkImport.
 
 import type { FormState, PayloadRequest } from 'payload'
 
-import {
-  EmailField,
-  Form,
-  FormSubmit,
-  PasswordField,
-  TextField,
-  useConfig,
-  useTranslation,
-} from '@payloadcms/ui'
-import { email, password, text } from 'payload/shared'
+import { Form, FormSubmit, PasswordField, useConfig, useTranslation } from '@payloadcms/ui'
+import { password } from 'payload/shared'
 
+import type { LoginFieldProps } from '../LoginField/index.js'
+
+import { LoginField } from '../LoginField/index.js'
 import './index.scss'
 
 export const LoginForm: React.FC<{
@@ -36,7 +31,17 @@ export const LoginForm: React.FC<{
   } = config
 
   const collectionConfig = config.collections?.find((collection) => collection?.slug === userSlug)
-  const loginWithUsername = collectionConfig?.auth?.loginWithUsername
+  const { auth: authOptions } = collectionConfig
+  const loginWithUsername = authOptions.loginWithUsername
+  const canLoginWithEmail =
+    !authOptions.loginWithUsername || authOptions.loginWithUsername.allowEmailLogin
+  const canLoginWithUsername = authOptions.loginWithUsername
+
+  const [loginType] = React.useState<LoginFieldProps['type']>(() => {
+    if (canLoginWithEmail && canLoginWithUsername) return 'emailOrUsername'
+    if (canLoginWithUsername) return 'username'
+    return 'email'
+  })
 
   const { t } = useTranslation()
 
@@ -75,47 +80,7 @@ export const LoginForm: React.FC<{
       waitForAutocomplete
     >
       <div className={`${baseClass}__inputWrap`}>
-        {loginWithUsername ? (
-          <TextField
-            label={t('authentication:username')}
-            name="username"
-            required
-            validate={(value) =>
-              text(value, {
-                name: 'username',
-                type: 'text',
-                data: {},
-                preferences: { fields: {} },
-                req: {
-                  payload: {
-                    config,
-                  },
-                  t,
-                } as PayloadRequest,
-                required: true,
-                siblingData: {},
-              })
-            }
-          />
-        ) : (
-          <EmailField
-            autoComplete="email"
-            label={t('general:email')}
-            name="email"
-            required
-            validate={(value) =>
-              email(value, {
-                name: 'email',
-                type: 'email',
-                data: {},
-                preferences: { fields: {} },
-                req: { t } as PayloadRequest,
-                required: true,
-                siblingData: {},
-              })
-            }
-          />
-        )}
+        <LoginField type={loginType} />
         <PasswordField
           autoComplete="off"
           label={t('general:password')}

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

@@ -1,6 +1,6 @@
 import type { Field } from '../../fields/config/types.js'
 
-export default [
+export const accountLockFields: Field[] = [
   {
     name: 'loginAttempts',
     type: 'number',

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

@@ -7,8 +7,7 @@ const encryptKey: FieldHook = ({ req, value }) =>
 const decryptKey: FieldHook = ({ req, value }) =>
   value ? req.payload.decrypt(value as string) : undefined
 
-// eslint-disable-next-line no-restricted-exports
-export default [
+export const apiKeyFields = [
   {
     name: 'enableAPIKey',
     type: 'checkbox',