# Add Two-Factor Authentication to a Filament Admin Panel

Yes. An agent turns on Filament's built-in app authentication for your panel, adds the user columns and model contract, writes Pest tests, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-two-factor-auth/filament/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how people sign in today. In an app shaped like filamentphp/demo, `composer.json` requires `filament/filament` `^5.0` on Laravel 12 with PHP `^8.1`, and `composer.lock` pins Filament at a 5.x release, which ships multi-factor authentication in the core package. `app/Providers/Filament/AdminPanelProvider.php` sets a custom `Login` page from `app/Filament/Pages/Auth/Login.php`, which prefills the demo credentials in `mount()`, turns on `->databaseNotifications()`, `->spa()` and global search, and calls neither `->profile()` nor `->multiFactorAuthentication()`. `app/Models/User.php` implements `FilamentUser` and `HasTenants` and casts only `email_verified_at`; the `2021_12_13_000001_create_users_table.php` migration has `name`, `email`, `password` and `remember_token`. `tests/Pest.php` binds `RefreshDatabase` and signs in a factory user before every test under `tests/Filament`, and `.github/workflows/tests.yml` runs `composer test:pest`, which is `pest --parallel`, on PHP 8.4 with SQLite.

It adds the feature the way Filament documents it, with no third-party plugin. A new migration adds two nullable `text` columns to `users`, `app_authentication_secret` and `app_authentication_recovery_codes`. `User` implements Filament's `HasAppAuthentication` and `HasAppAuthenticationRecovery` contracts with the getter and setter each one asks for, casts the secret as `encrypted` and the recovery codes as `encrypted:array`, and adds both to `$hidden` so they never serialise. `AdminPanelProvider` gains `->multiFactorAuthentication([AppAuthentication::make()->recoverable()])` and, because the set-up and removal actions live on the profile page, `->profile()`, which the panel does not yet enable. The `AppPanelProvider` for the tenant panel is left alone unless asked, since its users register themselves and the prompt names the admin panel.

Enforcement is a choice, so the agent makes it visible. With the default, a user who has set up an authenticator app is challenged after the password; one who has not signs in as before and sees the set-up action on the profile page. The prompt can ask for `isRequired: true`, in which case every user is sent to set it up on their next sign-in, which for the demo seeder's `admin@filamentphp.com` means the prefilled `Login` page leads straight into enrolment. The agent documents both in `README.md` and notes that `DatabaseSeeder` needs no change because the new columns are nullable.

Tests go under `tests/Filament/Auth/` in the style of `ManageAuthorsTest.php`: one case renders the profile page for the signed-in factory user and asserts the set-up action is present; one gives a factory user a secret through the model's setter, posts the login form through `Livewire::test` on the panel's `Login` page and asserts the response leads to the challenge rather than the dashboard; one asserts a user with no secret still reaches the dashboard. The agent runs `composer test:pest` and `composer test:phpstan` at level 8 as `phpstan.neon` sets, plus `npm run build` since `tests.yml` builds the Vite theme first, and signs in to the running app in its own browser to walk through enrolment with a TOTP code it generates from the secret.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "codex",
  "input": "Add two-factor authentication to the admin panel of this Filament app using Filament's built-in multi-factor authentication and open a pull request. Read composer.json, composer.lock for the filament/filament version, app/Providers/Filament/AdminPanelProvider.php, app/Providers/Filament/AppPanelProvider.php, app/Filament/Pages/Auth/Login.php, app/Models/User.php, database/migrations/2021_12_13_000001_create_users_table.php, database/seeders/DatabaseSeeder.php, tests/Pest.php, tests/Filament/Resources/Blog/Authors/Pages/ManageAuthorsTest.php, phpstan.neon and .github/workflows/tests.yml first. Add a migration with nullable text columns app_authentication_secret and app_authentication_recovery_codes on users. Make User implement Filament's HasAppAuthentication and HasAppAuthenticationRecovery contracts, cast the secret as encrypted and the codes as encrypted:array, and hide both. In AdminPanelProvider add multiFactorAuthentication with AppAuthentication::make()->recoverable() and enable profile() so the set-up action has a page. Leave AppPanelProvider unchanged. Do not install any package. Add Pest tests under tests/Filament/Auth in the style of ManageAuthorsTest: the profile page shows the set-up action, a user with a secret is challenged after the password, a user without one reaches the dashboard. Run npm run build, composer test:pest and composer test:phpstan, sign in in a browser and complete enrolment with a generated TOTP code, and paste the output in the pull request. Document the optional isRequired flag in README.md.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with one new migration under `database/migrations/`, the two contracts, casts and hidden attributes on `app/Models/User.php`, two chained calls in `app/Providers/Filament/AdminPanelProvider.php`, a `tests/Filament/Auth/` directory with three Pest cases, and a README section. `composer.json` and `composer.lock` are unchanged, since the feature is in the Filament package the app already has. The description pastes the Pest and PHPStan output from the sandbox and screenshots of the set-up modal with its QR code and of the challenge screen.

The `tests` workflow runs `composer test:pest` on PHP 8.4 for the pull request after `npm run build`, and the `phpstan` workflow runs the level 8 analysis, so both have passed before a reviewer opens it. The agent pushes one commit for the migration and model, one for the panel provider, and one for the tests and README.

A reviewer checks that both columns are nullable so existing users and the seeder are unaffected, that the secret and codes are encrypted and hidden, that the profile page is reachable from the user menu now that `->profile()` is on, that a user without a secret is not blocked unless `isRequired` was asked for, and that the tenant panel is untouched. Then they merge, run the migration, and decide when to flip enforcement on.

## Run it on every panel going to production

A team with several Filament panels starts one run per repository with `POST /o/{org}/sessions`, this prompt and the repository in `resources`. Each run reads that panel's provider and user model, so a panel that already has `->profile()` or a custom profile page gets a smaller diff and one whose users table already carries the columns gets no migration, and each ends in its own pull request. A `request_id` in the body makes a retried call return the run it already started.

The key's `webhook_url` receives `run.completed` for each run it starts, with `session_url` for the result, so a script can post the pull request links to the team channel as they land and flag any run that ended without one.

## Why run it on Rush?

Turning on second-factor sign-in is a few lines, and the things that go wrong are around them: a column that is not nullable, a secret stored in plain text, a set-up action with no page to live on, a seeder that breaks. In a Rush sandbox the agent runs the migration and the parallel Pest suite, analyses with PHPStan at the project's level, and walks through enrolment in its own browser with a real TOTP code, keeping the screenshots beside the test output.

Nothing has to be installed on the reader's laptop, no package is added, and the result passes the repository's own two workflows before a reviewer opens it. The same request works for any Filament 4 or 5 panel whose users sign in with a password.

## Frequently asked questions

### Does it need a plugin?

No. Filament 4 moved multi-factor authentication into the core package, with an authenticator-app factor and an email factor, and Filament 5 keeps it. The agent configures `AppAuthentication` on the panel and adds the contracts to the user model; `composer.json` does not change.

### Will existing users be locked out?

Not by default. The new columns are nullable, a user with no secret signs in exactly as before, and enrolment is an action on the profile page. Passing `isRequired: true` changes that to forced set-up at the next sign-in, which is why the agent documents it as a separate decision rather than switching it on.

### Where are the recovery codes stored?

In `app_authentication_recovery_codes` on `users`, cast as `encrypted:array` so they are encrypted at rest with the app key and decoded only when Filament checks one. Both new attributes are in `$hidden`, so a `User` serialised to JSON never includes them.

### What about the tenant App panel?

It is left as it is because its users register themselves and the prompt names the admin panel. The same two chained calls on `AppPanelProvider` would enable it there too, and the user model changes already cover both panels, so that is a one-file follow-up.

## More Filament jobs

- [Add a User Profile Page to a Filament Panel](https://getrush.ai/run/add-user-profile-page/filament/)
- [Write an Architecture Overview of a Filament Admin Panel](https://getrush.ai/run/architecture-overview/filament/)
- [Dockerize a Filament App](https://getrush.ai/run/dockerize-app/filament/)

## The same job on other stacks

- [Add Two-Factor Authentication to an Express and Mongoose API](https://getrush.ai/run/add-two-factor-auth/mongoose/)
- [Add Two-Factor Authentication to a Symfony App](https://getrush.ai/run/add-two-factor-auth/symfony/)

## More jobs like this: Hand off a long task

- [Add mypy Type Checking to a Python Project's CI](https://getrush.ai/run/add-type-checking/python/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
