Authentication

Unfold CMS uses Laravel Fortify for authentication, providing a secure login system with two-factor authentication, social login, email verification, and rate limiting.

Login

Standard Login

Users log in with their email and password at /login. The login form includes:

• Email field
• Password field
• "Remember Me" checkbox
• Link to password reset

Rate Limiting

Login attempts are rate-limited to prevent brute force attacks:

After exceeding the limit, users must wait before trying again. The lockout duration is communicated through error messages.

Two-Factor Authentication (2FA)

Unfold CMS supports TOTP-based two-factor authentication powered by Laravel Fortify.

Enabling 2FA

1. Navigate to Settings > Security in the user's profile
2. Click Enable Two-Factor Authentication
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
4. Enter the verification code to confirm
5. Save the recovery codes in a safe place

Login with 2FA

When 2FA is enabled:

1. User enters email and password
2. After successful credential check, a 2FA challenge is presented
3. User enters the 6-digit code from their authenticator app
4. Access is granted

Recovery Codes

During 2FA setup, recovery codes are generated. These can be used if the authenticator app is unavailable. Each recovery code can only be used once.

Users can regenerate recovery codes from their security settings.

Email Verification

New user accounts can require email verification before full access is granted.

Email verification can be toggled in Settings > Authentication in the admin panel.

Verification Flow

1. User registers or is created with an unverified email
2. A verification email is sent with a signed link
3. User clicks the link to verify
4. The email_verified_at timestamp is set

Unverified users can log in but may have restricted access depending on your middleware configuration.

Resending Verification

Users can request a new verification email from their profile or the verification notice page.

Password Reset

Reset Flow

1. User clicks "Forgot Password?" on the login page
2. Enters their email address
3. Receives a password reset email with a signed, time-limited link
4. Clicks the link and enters a new password
5. Password is updated and user can log in

Password reset links expire after 60 minutes.

Password Change

Authenticated users can change their password from Settings > Password. They must provide their current password to confirm the change.

When a password is changed, a password_changed notification is sent (if notifications are enabled).

Social Login

Pro Feature — Social login is available in the Pro and Agency tiers.

Unfold CMS supports OAuth-based social login through Laravel Socialite.

Supported Providers

Google, GitHub, and Facebook are supported. Enable providers and enter their credentials in Settings > Authentication > Social Login in the admin panel.

OAuth Credentials

Each provider requires OAuth credentials from their developer console:

• Google — Google Cloud Console
• GitHub — GitHub Developer Settings
• Facebook — Facebook for Developers

Set the callback URL to: https://yourdomain.com/auth/{provider}/callback

Social Login Flow

1. User clicks "Login with Google" (or other provider)
2. Redirected to the provider's OAuth consent screen
3. User grants permission
4. Redirected back to the CMS
5. If the email matches an existing account, they're logged in
6. If no match, a new account is created with the User role

Invalid Provider Handling

If a user tries to authenticate with an unconfigured provider, they're redirected back with an error message.

Registration

Registration can be enabled or disabled in Settings > Authentication in the admin panel.

Registration Flow

1. User visits /register
2. Fills in name, email, and password
3. Account is created with the User role
4. Verification email is sent (if enabled)
5. Welcome email is sent (if enabled)

Session Security

Rate Limits

All authentication endpoints are rate-limited:

Auth Page Appearance

Templates can customize the look of authentication pages (login, register, forgot password, etc.) through settings in the admin panel at Settings > Template > Auth Pages.

Layouts

Three layout options are available:

Branding Settings

These settings apply to all auth page layouts, but are most visible in the split layout:

How It Works

Auth page appearance is controlled per-template. Settings are stored with the key pattern:

template.{template_name}.auth.layout
template.{template_name}.auth.branding_title
template.{template_name}.auth.branding_description
template.{template_name}.auth.background_image
template.{template_name}.auth.background_color
template.{template_name}.auth.background_color_end

The active template's auth settings are automatically passed to all auth pages via the authAppearance shared prop in the Inertia middleware.

For Template Developers

Auth pages use the AuthLayout component (layouts/auth-layout.tsx) which automatically selects the correct layout based on the template's settings. Your auth pages should wrap their content with this component:

import AuthLayout from '@/layouts/auth-layout';

export default function Login() {
    return (
        <AuthLayout title="Sign in" description="Enter your credentials">
            {/* Form fields */}
        </AuthLayout>
    );
}

The AuthLayout component reads authAppearance from page props and renders the appropriate layout (AuthSimpleLayout, AuthCardLayout, or AuthSplitLayout).

Related

• Security Hardening — Additional security features
• User Management — Managing user accounts
• Roles & Permissions — Access control
• Templates Development — Building custom templates