Configuration

Everything lives in config/authentication.php. Top-level keys are global. Everything under defaults is per guard and can be overridden in guards.<name> — associative arrays merge recursively, lists replace wholesale (identifier.columns = ['username'] replaces ['email'], it does not merge by index).

php artisan vendor:publish --tag=authentication-config

'guards' => [
    'users' => ['model' => App\Models\User::class],
    'clients' => [
        'model' => App\Models\Client::class,
        'login' => ['password' => false, 'magic_link' => true, 'passkey' => true],
        'two_factor' => ['mode' => 'off'],
        'passkeys' => ['mode' => 'optional', 'second_factor' => 'off'],
        'registration' => ['mode' => 'open'],
        'routes' => ['enabled' => true, 'prefix' => 'clients/auth'],
    ],
],

Every guard is isolated: own model and table, own JWT audience, own refresh-token owner type, own throttle keys, own activity rows, own routes. Two guards may not share a model (a role on one table is authorization, not a guard) or an audience.

Global keys

Per-guard keys (defaults.*)

Every on/off key accepts the usual env spellings — true/false, 1/0, on/off, yes/no — so AUTHENTICATION_LOGIN_PASSWORD=off really turns password login off. A key that is not set — absent, null or blank (empty or whitespace, what KEY= in .env gives) — reads as the default shown; anything else (a typo such as disabled) throws AuthenticationMisconfigured naming the key when the guard resolves, and authentication:check lists it. The two-way string keys (identifier.normalize, risk.deny_response) and the mode keys (two_factor.mode, registration.mode, notifications.delivery, …) are just as strict: blank takes the shipped default, a typo throws.

Strict reads

Every other key is read just as strictly, and checked when the guard resolves:

• Integers (TTLs, attempt caps, throttles, lengths) take an int or a canonical integer string, so five or 1.5 throws instead of reading as the default (a blank one is not set, so the default applies) — and so does a value out of range: TTLs and caps at least 1, email_otp.length and verification.code_length 6–8, code attempts 1–100, passwords.policy.max at least policy.min.
• 0 is accepted only where it means something: tokens.refresh_absolute_ttl (no cap), invitations.resend_cooldown, verification.resend_decay and passwords.policy.uncompromised.threshold. tokens.access_ttl and sessions.max_active are null or blank (jwt’s TTL / no cap) or at least 1.
• String keys with a default (identifier.email_column, invitations.ability, activity.new_device.header, routes.prefix, routes.name, every notifications.urls.* template) throw when not a string, and read a blank as not set → the default; optional ones (laravel_guard, two_factor.issuer, queues, frontend_url, class-strings) throw when not a string, and read a blank as not set → unset.
• List keys (identifier.columns, routes.middleware, locale.supported …) must be lists of non-empty strings — a bad entry throws, it is never dropped.

The global tables.* and columns.* names throw when not a string and read a blank as not set → the shipped name; default reads a blank as users; hash_key and reauthentication_store throw when not a string (blank is not set → derived key / default store).

Environment

The common switches are env-driven (on/off switches are parsed as booleans):

AUTHENTICATION_GUARD=users
AUTHENTICATION_KEY_TYPE=bigint
AUTHENTICATION_HASH_KEY=
AUTHENTICATION_USERS_MODEL=App\Models\User

# on/off switches accept true/false, 1/0, on/off, yes/no
AUTHENTICATION_LOGIN_PASSWORD=true
AUTHENTICATION_LOGIN_MAGIC_LINK=off
AUTHENTICATION_LOGIN_EMAIL_OTP=off
AUTHENTICATION_LOGIN_PASSKEY=off

AUTHENTICATION_TWO_FACTOR=optional
AUTHENTICATION_PASSKEYS=optional
AUTHENTICATION_REGISTRATION=closed
AUTHENTICATION_VERIFICATION=optional
AUTHENTICATION_PASSWORD_BREACH_CHECK=false

AUTHENTICATION_NOTIFICATION_DELIVERY=after_response
AUTHENTICATION_FRONTEND_URL=https://app.example.com

Validation

A guard is validated the first time it is resolved — the first problem is thrown as AuthenticationMisconfigured naming the key, and php artisan authentication:check lists them all. The rules include:

• The model exists, is an Eloquent model and implements Account.
• 2FA on requires TwoFactorAuthenticatable; passkeys on (or passkey login) requires HasPasskeys.
• At least one login method is enabled; invite_only requires invitations.enabled.
• Forced enrolment with enrolment_requires_verified_email requires verification.mode other than off.
• laravel_guard is a jwt guard whose token_version is TokenVersionResolver.
• authentication.key_type equals passkeys.key_type and refresh-tokens.key_type, and the model’s key matches.
• With more than one guard: distinct laravel_guards, model morph classes and JWT audiences.
• Every switch, enum, integer, string and list key reads cleanly (see Strict reads above), so a typo fails when the guard resolves — never mid-flow.