Autentikasi Dua Faktor

Fortify tetap memiliki second-factor flow pada login POST:

TOTP;
recovery code;
passkeys.

PandaBear tidak menduplikasi flow tersebut.

PandaBear menambahkan dua kemampuan:

Panel dapat mewajibkan account memiliki second factor sebelum boleh menggunakan Panel.
PandaBear menyediakan Email Code sebagai alternatif second factor untuk user yang tidak menggunakan authenticator app.

Contoh Minimal

php

<?php

declare(strict_types=1);

namespace App\Panels\Admin;

use PandaPanel\Core\Panel;
use PandaPanel\Core\PanelProvider;

final class AdminPanelProvider
    extends PanelProvider
{
    public function panel(
        Panel $panel
    ): Panel {
        return $panel
            ->path('admin')
            ->auth()
            ->requireTwoFactor();
    }
}

Signed-in user tanpa second factor akan diarahkan ke Security Settings.

php

it(
    'holds a user without a second factor at the security page',
    function (): void {
        $this
            ->actingAs(
                User::factory()
                    ->create()
            )
            ->get('/admin')
            ->assertRedirect(
                route(
                    'panel.admin.pages.settings-security',
                    absolute: false
                )
            );
    }
);

Setelah account memiliki:

TOTP;
Email Code;
Passkey;

redirect tersebut berhenti.

Apa yang Dihitung sebagai Second Factor

RequireTwoFactor memeriksa dalam urutan:

Factor	Check	User Model
TOTP	`hasEnabledTwoFactorAuthentication()`	Fortify trait
Email Code	`EmailCodeFactor::isEnabledFor()`	`two_factor_email_confirmed_at`
Passkey	`passkeys()->exists()`	Passkey trait

Checks menggunakan method_exists() untuk trait-provided behavior.

Model yang tidak mendukung sebuah feature dianggap:

text

factor tidak tersedia

bukan exception.

Passkey sengaja dianggap cukup karena hardware/WebAuthn key merupakan strong authentication factor.

Panel API

php

public function requireTwoFactor(
    bool $required = true
): self;

public function requiresTwoFactor():
    bool;

Contoh:

php

Panel::make(
    'admin'
)
    ->requireTwoFactor()
    ->requiresTwoFactor();

// true

php

Panel::make(
    'kiosk'
)
    ->requireTwoFactor(false)
    ->requiresTwoFactor();

// false

Default:

text

false

Configuration dapat menggunakan expression:

php

$panel->requireTwoFactor(
    app()->isProduction()
);

Settings Requirement

User membutuhkan tempat untuk setup second factor.

API:

php

public function settings(
    bool $settings = true
): self;

public function hasSettings():
    bool;

Default settings menyediakan:

text

Profile
Security
Appearance

Jangan menggabungkan:

php

settings(false)

dengan:

php

requireTwoFactor()

tanpa menyediakan alternative setup flow.

Middleware

php

PandaPanel\Http\Middleware\RequireTwoFactor

otomatis diregistrasikan.

Stack:

php

[
    ...$panel->getMiddleware(),

    ResolvePanel::class
        . ':'
        . $panel->getId(),

    RequireTwoFactor::class
        . ':'
        . $panel->getId(),

    RequireEmailCode::class
        . ':'
        . $panel->getId(),
]

Signature:

php

public function handle(
    Request $request,
    Closure $next,
    ?string $panelId = null
): Response;

Panel id diberikan eksplisit.

Middleware juga dapat digunakan sendiri:

php

use PandaPanel\Http\Middleware\RequireTwoFactor;

Route::get(
    '/reports/payroll',
    PayrollController::class
)
    ->middleware([
        'auth',
        RequireTwoFactor::class
            . ':admin',
    ]);

Middleware melewatkan request jika:

Panel tidak diketahui;
Panel tidak mewajibkan second factor;
tidak ada signed-in user;
user sudah memiliki factor;
request adalah Security Settings;
request adalah standalone Page milik Panel.

Jika Panel mewajibkan factor tetapi tidak memiliki Security Page:

text

Framework fail-closed.

Jika setup diperlukan:

php

return redirect()
    ->route(
        $panel->routeName(
            'pages.'
            . SecuritySettings::slug()
        )
    )
    ->with(
        'warning',
        'Set up two-factor authentication to continue.'
    );

Tempat User Mengaktifkan Factor

Page:

text

{panel}/settings/security

route:

text

panel.{id}.pages.settings-security

Page berada di balik:

php

RequirePassword

Jadi user harus membuktikan password sebelum mengubah security settings.

Props:

Prop	Sumber
`canManageTwoFactor`	Fortify
`canManagePasskeys`	Fortify
`passkeys`	User relation
`passwordRules`	PandaBear helper
`emailCodeEnabled`	Email Code factor
`emailCodeUrls`	Panel routes
`twoFactorEnabled`	TOTP state
`requiresConfirmation`	Fortify config

Page menggunakan:

php

InteractsWithTwoFactorState

dan memanggil:

php

ensureStateIsValid()

agar abandoned TOTP setup tidak tertinggal dalam state separuh aktif.

TOTP write tetap menuju Fortify.

Email Code Bawaan Panel

Email Code adalah one-time code yang dikirim ke email account.

Fitur ini bukan bagian dari Login POST.

Behavior:

text

Login via Fortify
↓
Session created
↓
RequireEmailCode
↓
session belum verified?
↓
challenge
↓
kode benar
↓
session marker

Session baru selalu perlu challenge lagi.

Enable / Disable

Routes berada di balik RequirePassword.

php

public function enable(
    Request $request
): RedirectResponse;

public function disable(
    Request $request
): RedirectResponse;

URLs:

php

/admin/two-factor/enable
/admin/two-factor/disable

Enable:

php

$user
    ->forceFill([
        'two_factor_email_confirmed_at'
            => now(),
    ])
    ->save();

$request
    ->session()
    ->put(
        PanelTwoFactorController::SESSION_KEY,
        now()->timestamp
    );

Current session langsung dianggap lolos.

Disable:

text

column = null
↓
forget pending challenge
↓
hapus session marker

Challenge

Controller methods:

php

public function challenge(
    Request $request
): Response;

public function send(
    Request $request
): RedirectResponse;

public function verify(
    Request $request
): RedirectResponse;

Routes:

text

GET  {panel}/two-factor/challenge
POST {panel}/two-factor/send
POST {panel}/two-factor/verify

Challenge Page props:

Prop	Arti
`panel`	Panel definition
`sentTo`	Masked email
`retryAfter`	Detik sampai resend tersedia

send() dapat menghasilkan ValidationException jika rate limit terlampaui.

Jika user tidak memiliki notify():

text

verify() memvalidasi:

php

[
    'code' => [
        'required',
        'string',
        'digits:6',
    ],
]

Setelah sukses:

text

regenerate session
↓
set SESSION_KEY
↓
redirect intended

Session key:

php

PanelTwoFactorController::SESSION_KEY;

// panel.mfa.email.confirmed_at

`RequireEmailCode`

Middleware ini berbeda dari RequireTwoFactor.

RequireTwoFactor memeriksa:

text

ACCOUNT ENROLMENT

sedangkan RequireEmailCode memeriksa:

text

CURRENT SESSION

Jadi account yang mengaktifkan Email Code tetap mendapatkan challenge per-session meskipun Panel tidak menggunakan:

php

requireTwoFactor()

Middleware menyimpan:

text

url.intended

dan setelah challenge user kembali ke tujuan semula.

`EmailCodeFactor`

php

public static function isEnabledFor(
    ?object $user
): bool;

Membaca:

php

$user
    ->getAttributes()[
        'two_factor_email_confirmed_at'
    ]

secara langsung.

Missing attribute dianggap:

text

false

A non-Eloquent model juga false.

`EmailCodeChallenge`

API:

Method	Return
`issue()`	Plain code atau null
`verify()`	bool
`pending()`	bool
`secondsUntilNextSend()`	int
`forget()`	void

Contoh:

php

$challenge =
    app(
        EmailCodeChallenge::class
    );

$code =
    $challenge->issue(
        $user
    );

if ($code === null) {
    return back()
        ->withErrors([
            'code' =>
                'Try again in '
                . $challenge
                    ->secondsUntilNextSend(
                        $user
                    )
                . 's.',
        ]);
}

$user->notify(
    new TwoFactorCode(
        $code
    )
);

Security constants:

Rule	Value
Code	6 digit
Lifetime	10 menit
Storage	hashed Cache value
Sends	5/jam/user
Guesses	5/menit/user
Single use	Ya

Successful verify juga membersihkan guess limiter.

Notification

php

PandaPanel\Notifications\TwoFactorCode

implements:

php

ShouldQueue

Mail tidak disimpan di Panel notification bell karena ini merupakan credential.

Migration

Package menambahkan:

text

two_factor_email_confirmed_at

ke users.

Publish:

bash

php artisan vendor:publish --tag=panda-panel-migrations
php artisan migrate

Cast:

php

protected function casts(): array
{
    return [
        'two_factor_email_confirmed_at'
            => 'datetime',
    ];
}

Route Reference

Route	Verb	Path	Extra
challenge	GET	`{panel}/two-factor/challenge`	—
send	POST	`{panel}/two-factor/send`	—
verify	POST	`{panel}/two-factor/verify`	—
enable	POST	`{panel}/two-factor/enable`	`RequirePassword`
disable	POST	`{panel}/two-factor/disable`	`RequirePassword`

Testing

Challenge:

php

Notification::fake();

$user =
    User::factory()
        ->create();

$user
    ->forceFill([
        'two_factor_email_confirmed_at'
            => now(),
    ])
    ->save();

$this
    ->actingAs($user)
    ->get('/coded')
    ->assertRedirect(
        route(
            'panel.coded.auth.two-factor.challenge',
            absolute: false
        )
    );

Skip challenge:

php

$this
    ->actingAs($user)
    ->withSession([
        PanelTwoFactorController::SESSION_KEY
            => now()->timestamp,
    ])
    ->get('/admin')
    ->assertOk();

Password confirmation:

php

$this
    ->actingAs($user)
    ->withSession([
        'auth.password_confirmed_at'
            => now()->timestamp,
    ])
    ->post(
        '/admin/two-factor/disable'
    )
    ->assertRedirect();

Rate limiter:

php

RateLimiter::clear(
    'panel.mfa.email.send.'
    . $user->getKey()
);

RateLimiter::clear(
    'panel.mfa.email.attempt.'
    . $user->getKey()
);

Untuk test enrollment TOTP:

php

$user
    ->forceFill([
        'two_factor_secret'
            => encrypt(
                'secret'
            ),

        'two_factor_confirmed_at'
            => now(),
    ])
    ->save();

Hal yang Perlu Diperhatikan

requireTwoFactor() memeriksa enrollment, bukan apakah factor benar-benar dipakai saat login.
TOTP login verification tetap concern Fortify.
Email Code adalah exception karena RequireEmailCode memeriksa current session.
Semua standalone Page saat ini dikecualikan dari RequireTwoFactor.
Sensitive functionality sebaiknya berada di Resource atau diberi check tambahan.
settings(false) dan requireTwoFactor() bertentangan.
Enable Email Code langsung memenuhi current session.
Challenge Page mengirim email sebagai side effect GET jika belum ada pending code.
send() 500 jika model tidak memiliki notify().
Masked address dihitung saat runtime, tidak disimpan.
Security constants Email Code tidak configurable.

Autentikasi Dua Faktor ​

Contoh Minimal ​

Apa yang Dihitung sebagai Second Factor ​

Panel API ​

Settings Requirement ​

Middleware ​

Tempat User Mengaktifkan Factor ​

Email Code Bawaan Panel ​

Enable / Disable ​

Challenge ​

RequireEmailCode ​

EmailCodeFactor ​

EmailCodeChallenge ​

Notification ​

Migration ​

Route Reference ​

Testing ​

Hal yang Perlu Diperhatikan ​

Lihat Juga ​

Autentikasi Dua Faktor

Contoh Minimal

Apa yang Dihitung sebagai Second Factor

Panel API

Settings Requirement

Middleware

Tempat User Mengaktifkan Factor

Email Code Bawaan Panel

Enable / Disable

Challenge

`RequireEmailCode`

`EmailCodeFactor`

`EmailCodeChallenge`

Notification

Migration

Route Reference

Testing

Hal yang Perlu Diperhatikan

Lihat Juga