Skip to content

marko/admin-auth

Admin authentication and role-based authorization --- manages admin users, roles, permissions, and access control for the admin panel. The package provides an AdminUserProvider that integrates with the authentication system, a PermissionRegistry for declaring and matching permissions (including wildcards), role and permission entities with repository interfaces, and AdminAuthMiddleware that enforces #[RequiresPermission] checks on controller classes and methods. Super admin roles bypass all permission checks.

Terminal window
composer require marko/admin-auth

Then create the tables:

Terminal window
marko db:migrate

The package ships no migration files. Its tables come from its entities, which db:migrate discovers in vendor/marko/admin-auth/src/Entity like any other module’s. In development (or with --generate) the command generates a migration for them in database/migrations/ and applies it; commit that file and deploy it like your own migrations. See database for how migrations are generated.

TableEntityHolds
rolesRoleRoles and the is_super_admin flag (unique slug)
permissionsPermissionPermission keys, labels and groups (unique key, index on group)
role_permissionsRolePermissionRole to permission assignments (unique role_id, permission_id; index on permission_id)
admin_usersAdminUserAdmin users (unique email), with the remember-me token hash and its remember_token_expires_at
admin_user_rolesAdminUserRoleUser to role assignments (unique user_id, role_id; index on role_id)
remember_tokensRememberTokenOne remember-me token per device: guard, user ID, unique selector, validator_hash, expires_at (indexed), user_agent

Both pivots cascade: deleting a role, permission or admin user deletes its assignment rows.

The module binds RememberTokenStorageInterface to RememberTokenRepository, so remember-me tokens live in the remember_tokens table, one row per device. Logging in with “remember me” on a second browser no longer logs the first one out, and logging out deletes only that browser’s row. The binding covers every session guard in the app, not just admin; the guard column keeps each guard’s tokens apart. See Per-Device Tokens for how the cookie is checked and rotated.

Run marko db:migrate after upgrading to create the table, before deploying the new code: remember-me logins write to it. Admins remembered through the old admin_users.remember_token column stay signed in; their next visit moves them onto a device row and clears the column. Schedule marko auth:clear-tokens to purge rows that expired on devices that never came back.

The admin area authenticates on its own guard, never the application’s default guard. The package merges this guard into authentication config:

vendor/marko/admin-auth/config/authentication.php
return [
'guards' => [
'admin' => ['driver' => 'session', 'provider' => 'admins'],
],
'providers' => [
'admins' => ['class' => AdminUserProvider::class],
],
];

admin-auth.guard names the guard the admin area uses (admin by default):

config/admin-auth.php
return [
'guard' => 'admin',
];

AdminAuthMiddleware, the admin panel login and logout, and the admin API resolve that guard by name through AdminGuardResolver (AuthManager::guard($config->getGuardName())). Because the admin guard has its own provider and its own session key (auth_admin_user_id), the admin and frontend logins are separate: a customer logged in on the frontend is a guest in the admin area, and an admin login never logs into the frontend. The package does not bind UserProviderInterface, so your frontend provider binding stays in place. See User Providers.

AdminUserProvider checks admin passwords through PasswordVerifierInterface, the same single password check the rest of the framework uses. A login for an unknown or inactive admin, or with a password that isn’t a string, still pays for one dummy hash check, so response timing doesn’t reveal which admin accounts exist. Rebinding PasswordVerifierInterface changes how admin logins are checked too.

Resolve the admin guard in your own admin code the same way:

ReportController.php
use Marko\AdminAuth\AdminGuardResolver;
readonly class ReportController
{
public function __construct(
private AdminGuardResolver $adminGuard,
) {}
public function index(): Response
{
$admin = $this->adminGuard->guard()->user();
// ...
}
}

To serve the admin area through a token guard instead, for example a headless admin on marko/admin-api, define a token guard on the admins provider and point admin-auth.guard at it:

config/authentication.php
return [
'guards' => [
'admin-api' => ['driver' => 'token', 'provider' => 'admins'],
],
];
config/admin-auth.php
return [
'guard' => 'admin-api',
];

In tests, authenticate an admin on the admin guard with the HTTP test client: actingAs($admin, guard: 'admin').

Add AdminAuthMiddleware to controller methods or classes to require authentication:

CatalogController.php
use Marko\AdminAuth\Middleware\AdminAuthMiddleware;
use Marko\Routing\Attributes\Get;
use Marko\Routing\Attributes\Middleware;
class CatalogController
{
#[Get('/admin/catalog/products')]
#[Middleware(AdminAuthMiddleware::class)]
public function index(): Response
{
// Only authenticated admin users reach here
}
}

When no admin is logged in, AdminAuthMiddleware does one of two things:

  • Redirects to {prefix}/login (/admin/login by default) when the guard is stateful (the session guard) and the request does not want JSON.
  • Throws a 401 UnauthenticatedException (an HttpException from marko/authentication) in every other case: when the request wants JSON (Request::wantsJson(): an Accept header with application/json or a +json type), and always when the guard is stateless (StatelessGuardInterface, such as the token guard), whatever the Accept header, because an API client can’t follow a login redirect. On a stateless guard the 401 carries the guard’s WWW-Authenticate challenge (Bearer for the token guard), the same response AuthMiddleware sends.

AdminAuthMiddleware uses the admin guard (admin-auth.guard), so when that guard is a token guard, such as a headless admin served through marko/admin-api, it never redirects.

A user the admin guard authenticates that is not an AdminUserInterface gets a 403 on every admin route, whether or not the route requires a permission.

The routing pipeline renders the thrown 401 through ExceptionRenderer, so it looks like every other HTTP error in the application:

{"message": "Unauthorized."}

Use #[RequiresPermission] to enforce specific permissions on a route. AdminAuthMiddleware reads the attribute from the matched controller method, or from the controller class when the method has none, and throws a 403 HttpException when the authenticated user lacks the required permission, or is not an admin user at all. Super admin roles bypass this check. A role is a super admin role when its is_super_admin flag (roles.is_super_admin) is set; there is no config key for it (the admin-auth.super_admin_role key earlier versions shipped was never read and has been removed).

ExceptionRenderer renders the 403 as JSON for requests that ask for it and as the application’s HTML error page otherwise:

{"message": "Forbidden."}

The required permission is never sent to the client. It is only in the exception’s context, for logs. To render admin denials differently (a branded page, another JSON shape), replace ExceptionRenderer with a #[Preference]; see Custom error pages. Admin denials go through it like any other HTTP error.

ProductController.php
use Marko\AdminAuth\Attributes\RequiresPermission;
use Marko\AdminAuth\Middleware\AdminAuthMiddleware;
use Marko\Routing\Attributes\Get;
use Marko\Routing\Attributes\Middleware;
class ProductController
{
#[Get('/admin/catalog/products')]
#[Middleware(AdminAuthMiddleware::class)]
#[RequiresPermission(permission: 'catalog.products.view')]
public function index(): Response
{
// Only admin users with 'catalog.products.view' permission
}
}

Put #[RequiresPermission] on the controller class to protect every action at once. A method-level attribute replaces the class-level one for that action, it does not add to it:

SettingsController.php
use Marko\AdminAuth\Attributes\RequiresPermission;
use Marko\AdminAuth\Middleware\AdminAuthMiddleware;
use Marko\Routing\Attributes\Get;
use Marko\Routing\Attributes\Middleware;
#[Middleware(AdminAuthMiddleware::class)]
#[RequiresPermission(permission: 'settings.manage')]
class SettingsController
{
#[Get('/admin/settings')]
public function index(): Response
{
// Requires 'settings.manage'
}
#[Get('/admin/settings/summary')]
#[RequiresPermission(permission: 'settings.view')]
public function summary(): Response
{
// Requires only 'settings.view'
}
}

The usual way to declare a permission is #[AdminPermission] on an admin section class (see marko/admin):

app/catalog/src/Admin/CatalogSection.php
use Marko\Admin\Attributes\AdminPermission;
use Marko\Admin\Attributes\AdminSection;
use Marko\Admin\Contracts\AdminSectionInterface;
#[AdminSection(id: 'catalog', label: 'Catalog')]
#[AdminPermission(id: 'catalog.products.view', label: 'View Products')]
#[AdminPermission(id: 'catalog.products.edit', label: 'Edit Products')]
class CatalogSection implements AdminSectionInterface
{
// ...
}

You don’t register these yourself. marko/admin-auth’s boot callback registers every #[AdminPermission] on the #[AdminSection] classes that marko/admin discovers. It uses the same section list as marko/admin: one scan per boot, or the discovery cache in production. Each permission’s group is the first segment of its key (catalog for catalog.products.view). Boot fails with an AdminAuthException when:

  • a key isn’t in the permission key format (the message names the key and the section class);
  • two section classes declare the same key (the message names both classes);
  • a key declared by #[AdminPermission] was already registered by hand. Remove the manual register() call.

For a permission that doesn’t belong to a section, call PermissionRegistryInterface::register() from your module’s boot callback:

app/catalog/module.php
use Marko\AdminAuth\Contracts\PermissionRegistryInterface;
return [
'boot' => function (PermissionRegistryInterface $permissionRegistry): void {
$permissionRegistry->register(
key: 'catalog.reports.export',
label: 'Export Reports',
group: 'catalog',
);
},
];

Both ways register in memory only, and boot never touches the database. Roles are assigned permissions from the permissions table. After deploying code that adds, changes or removes permissions, write them to the table as described in Syncing Permissions to the Database.

marko/admin-auth binds PermissionRegistryInterface to PermissionRegistry as a shared singleton, so you don’t bind it yourself. Every class that injects the interface gets the same instance: the boot callback, your own boot code, AdminAuthMiddleware and marko/admin-api’s SectionController. A permission registered through one of them is visible to all of them.

To replace the registry, put a #[Preference] on a class that implements the interface, and have it replace the interface rather than PermissionRegistry. The container checks preferences for the type being injected, which is the interface, so a Preference on the concrete class is never used. The replacement is still shared:

app/admin/src/AppPermissionRegistry.php
use Marko\AdminAuth\Contracts\PermissionRegistryInterface;
use Marko\AdminAuth\PermissionRegistry;
use Marko\Core\Attributes\Preference;
#[Preference(replaces: PermissionRegistryInterface::class)]
class AppPermissionRegistry extends PermissionRegistry
{
// Override register(), all(), getByGroup() or matches() as needed
}
Terminal window
marko admin-auth:permissions:sync

The command calls PermissionRepositoryInterface::syncFromRegistry(), which writes in one transaction:

  • It inserts every registered permission that isn’t in the table yet.
  • It updates the label and group of an existing row when the #[AdminPermission] (or register() call) changed them.
  • It renames a row whose key differs from a registered key only in letter case (Posts.Edit stored, posts.edit registered) to the registered key, and reports it as updated. The row keeps its id and role assignments. Without this, the insert would fail on MySQL/MariaDB’s case-insensitive unique index and add a second row on PostgreSQL. If several case variants are stored (only possible on PostgreSQL), the one with the lowest id is renamed and the others are reported as unregistered.
  • It reports every row whose key is no longer registered (a removed or renamed permission, or an uninstalled module) and how many roles still hold it.
  • It deletes nothing.
Synced 12 registered permission(s): 1 created, 1 updated, 10 unchanged.
2 permission(s) in the database are no longer registered:
legacy.reports.export (held by 3 role(s))
legacy.reports.view (held by 0 role(s))
Re-run with --prune to delete them and their role assignments.
Wildcard grants kept: catalog.*

A stale row still grants its key: users with a role that holds it keep the permission, and a later module that registers the same key would hand its new meaning to those roles. Remove stale rows with --prune:

Terminal window
marko admin-auth:permissions:sync --prune

--prune deletes the unregistered permissions and their role_permissions rows in one transaction(), then lists what it removed. It deletes the role assignments explicitly, so the result doesn’t depend on the foreign key’s ON DELETE CASCADE.

Keys containing * are wildcard grants such as catalog.* or * (see Wildcard Permissions). #[AdminPermission] never registers them, so they are never reported as stale and never pruned. They are listed as “Wildcard grants kept”.

Pruning changes what roles can do, so it follows the destructive command policy of marko/database, opted in to run in production:

Environment--prune
development, dev, local, testing, testRuns; asks for confirmation first when someone can answer
Everything else, including production and an unset environmentRefused with exit code 1 unless you also pass --force. With --force, asks for confirmation when someone can answer, and runs when nobody can (deploy scripts, --no-interaction)

Declining the confirmation cancels the prune with exit code 0; the sync itself has already been written. A deploy script that prunes passes both flags:

Terminal window
APP_ENV=production marko admin-auth:permissions:sync --prune --force --no-interaction

When nothing is stale, --prune prints No unregistered permissions to prune. and needs no --force. The plain sync never deletes anything, so running it on every deploy is safe: a deploy that temporarily disables a module doesn’t strip its permissions from roles.

Every run dispatches PermissionsSynced.

Permission keys, role slugs and admin emails are unique columns. MySQL and MariaDB compare them with the server’s default collation, which ignores case (and accents), while PostgreSQL and PHP compare them exactly (see String Comparison and Collation). So that posts.edit and Posts.Edit mean the same thing on every driver, admin-auth enforces one canonical form in PHP, before any SQL runs:

ValueFormatEnforced by
Permission keyLowercase segments of a-z, 0-9, _ and - separated by dots (catalog.products.view). Segments after the first may contain * (catalog.*, catalog.products.ed*), and * alone grants everythingPermissionRegistryInterface::register(), #[AdminPermission] discovery, PermissionRepository::save()/insertBatch() throw AdminAuthException::invalidPermissionKey(); findByKey() returns null
Role slugLowercase segments of a-z, 0-9, _ and - separated by dots (content-editor), no *RoleRepository::save()/insertBatch() and isSlugUnique() throw AdminAuthException::invalidRoleSlug(); findBySlug() returns null
Admin emailLowercased with mb_strtolower()AdminUserRepository::save()/insertBatch() store it lowercased and findByEmail() looks it up lowercased

The patterns are IdentifierFormat::PERMISSION_KEY_PATTERN and IdentifierFormat::ROLE_SLUG_PATTERN; check a value with IdentifierFormat::isPermissionKey() or IdentifierFormat::isRoleSlug().

Because emails are lowercased, an admin signs in with [email protected] or [email protected] alike on every driver, and saving a second admin whose email differs only in case throws UniqueConstraintViolationException on every driver.

Permissions support wildcard matching. A role with catalog.* can access any catalog. permission:

use Marko\AdminAuth\Contracts\PermissionRegistryInterface;
$permissionRegistry->matches('catalog.*', 'catalog.products.view'); // true
$permissionRegistry->matches('catalog.*', 'catalog.products.edit'); // true
$permissionRegistry->matches('*', 'anything.here'); // true
$permissionRegistry->matches('catalog.products.*', 'catalog.orders'); // false

AdminUserInterface provides methods for checking permissions and roles:

OrderService.php
use Marko\AdminAuth\Entity\AdminUserInterface;
use Marko\Routing\Exceptions\HttpException;
class OrderService
{
public function cancel(
AdminUserInterface $adminUser,
int $orderId,
): void {
if (!$adminUser->hasPermission('orders.cancel')) {
throw HttpException::forbidden('Cannot cancel orders.');
}
if ($adminUser->hasRole('super-admin')) {
// super admin bypass
}
}
}

AdminUser implements AdminUserInterface and integrates with the authentication system:

DashboardController.php
use Marko\AdminAuth\AdminGuardResolver;
use Marko\AdminAuth\Entity\AdminUserInterface;
readonly class DashboardController
{
public function __construct(
private AdminGuardResolver $adminGuard,
) {}
public function index(): Response
{
$user = $this->adminGuard->guard()->user();
if ($user instanceof AdminUserInterface) {
$name = $user->getName();
$roles = $user->getRoles();
$permissions = $user->getPermissionKeys();
}
}
}

RoleRepository and AdminUserRepository dispatch RoleCreated, RoleUpdated, RoleDeleted, AdminUserCreated and AdminUserUpdated after a save or delete. AdminUserDeleted is available for your own code to dispatch. Each event exposes getTimestamp(), which is a required constructor argument: the events never read the clock themselves. The repositories pass the current instant from the marko/database repository (Repository::now(), in UTC), the same instant source used for #[Timestamps].

admin-auth:permissions:sync dispatches PermissionsSynced once per run, after the sync and any prune, with the time from the injected ClockInterface. It fires even when --prune is refused or cancelled, because the sync has already been written; getPrunedCount() is then 0. Observe it to audit permission changes:

app/admin/src/Observers/AuditPermissionSync.php
use Marko\AdminAuth\Events\PermissionsSynced;
use Marko\Core\Attributes\Observer;
use Marko\Log\Contracts\LoggerInterface;
#[Observer(event: PermissionsSynced::class)]
readonly class AuditPermissionSync
{
public function __construct(
private LoggerInterface $logger,
) {}
public function handle(
PermissionsSynced $event,
): void {
$this->logger->info('Admin permissions synced', [
'registered' => $event->getTotalCount(),
'created' => $event->getCreatedCount(),
'updated' => $event->getUpdatedCount(),
'unregistered' => $event->getUnregisteredCount(),
'pruned' => $event->getPrunedCount(),
'at' => $event->getTimestamp()->format(DATE_ATOM),
]);
}
}
GetterReturns
getTotalCount()The number of registered permissions
getCreatedCount()Permissions inserted
getUpdatedCount()Existing permissions whose label or group changed
getUnregisteredCount()Rows no longer registered, wildcard grants excluded
getPrunedCount()Rows deleted by --prune (0 without it, or when it was refused or cancelled)
interface AdminUserInterface extends AuthenticatableInterface
{
public function getEmail(): string;
public function getName(): string;
public function setRoles(
array $roles,
array $permissionKeys = [],
): void;
public function getRoles(): array;
public function getPermissionKeys(): array;
public function hasPermission(string $key): bool;
public function hasRole(string $slug): bool;
}
interface PermissionRegistryInterface
{
public function register(
string $key,
string $label,
string $group,
): void;
public function all(): array;
public function getByGroup(string $group): array;
public function matches(
string $pattern,
string $permissionKey,
): bool;
}

register() throws AdminAuthException::invalidPermissionKey() for a key outside the permission key format and AdminAuthException::duplicatePermission() for a key that is already registered.

public function registerFromDefinitions(array $definitions): void;
public function discoverFromClass(string $className): void;

registerFromDefinitions() registers the #[AdminPermission] entries of the given AdminSectionDefinitions, grouped by the first segment of each key. The boot callback calls it with marko/admin’s DiscoveredAdminSections::all(). discoverFromClass() parses one #[AdminSection] class and registers its permissions.

ExceptionThrown when
AdminAuthException::invalidPermissionKey()A declared key is outside the permission key format (the message names the key and the section class). Nothing is registered
AdminAuthException::duplicatePermission()Two section classes declare the same permission key (the message names both classes)
AdminAuthException::permissionAlreadyRegistered()A key declared by #[AdminPermission] was already registered by hand
CommandDescription
admin-auth:permissions:syncInserts missing permissions, updates changed labels and groups, and lists permissions that are no longer registered with how many roles hold each. Deletes nothing
admin-auth:permissions:sync --pruneAlso deletes the unregistered permissions and their role assignments in one transaction. Never deletes a key containing *. Outside development and testing, needs --force; asks for confirmation when someone can answer
auth:clear-tokensFrom marko/authentication: deletes expired rows from remember_tokens (--force deletes every row). See Remember-Me Tokens
#[RequiresPermission(permission: 'section.action')]

Targets classes and methods. A method-level attribute replaces a class-level one.

class AdminAuthMiddleware implements MiddlewareInterface
{
public function handle(
Request $request,
callable $next,
): Response;
}

Throws Marko\Authentication\Exceptions\UnauthenticatedException with status 401 for an unauthenticated request that wants JSON or whose guard is stateless (with the guard’s WWW-Authenticate challenge when the guard is stateless), or Marko\Routing\Exceptions\HttpException with status 403 for a user that is not an AdminUserInterface or lacks the required permission. An unauthenticated request on a stateful guard that doesn’t want JSON gets a redirect response to {prefix}/login; a stateless guard never redirects.

Permission enforcement relies on the router attaching route context to the request before middleware runs (see marko/routing --- Request::withRoute()). If no route context is present, #[RequiresPermission] is not evaluated and the request passes through authenticated.

interface AdminUserRepositoryInterface extends RepositoryInterface
{
public function findByEmail(string $email): ?AdminUser;
public function getRolesForUser(int $userId): array;
public function syncRoles(
int $userId,
array $roleIds,
): void;
}
interface RoleRepositoryInterface extends RepositoryInterface
{
public function findBySlug(string $slug): ?Role;
public function getPermissionsForRole(int $roleId): array;
/** @return array<Permission> */
public function getPermissionsForRoles(array $roleIds): array;
public function syncPermissions(
int $roleId,
array $permissionIds,
): void;
public function isSlugUnique(
string $slug,
?int $excludeId = null,
): bool;
}
interface PermissionRepositoryInterface extends RepositoryInterface
{
public function findByKey(string $key): ?Permission;
public function findByGroup(string $group): array;
public function syncFromRegistry(PermissionRegistryInterface $registry): PermissionSyncResult;
/** @return list<UnregisteredPermission> */
public function findUnregistered(PermissionRegistryInterface $registry): array;
/** @return list<UnregisteredPermission> */
public function pruneUnregistered(PermissionRegistryInterface $registry): array;
}

findByEmail() lowercases the email before the lookup. findBySlug() and findByKey() return null for a slug or key outside the canonical format without querying, and isSlugUnique() throws AdminAuthException::invalidRoleSlug() for one, since save() would reject it.

syncFromRegistry() inserts the registered permissions that are missing from the table, updates the label and group of rows that changed and renames rows whose key differs from a registered key only in case, in one transaction. It deletes nothing. It returns a PermissionSyncResult:

readonly class PermissionSyncResult
{
public int $registeredCount;
public array $created; // list<string>: keys inserted
public array $updated; // list<string>: keys whose label or group changed, or whose case was repaired
public array $unregistered; // list<UnregisteredPermission>: rows no longer registered
public array $wildcardKeys; // list<string>: keys containing `*`, kept
public function createdCount(): int;
public function updatedCount(): int;
public function unregisteredCount(): int;
}
readonly class UnregisteredPermission
{
public int $id;
public string $key;
public string $label;
public string $group;
public int $roleCount; // distinct roles holding the permission
}

findUnregistered() returns the rows whose key is not registered, sorted by key. pruneUnregistered() deletes those rows and their role_permissions rows in one transaction() (a savepoint inside your own transaction) and returns what it removed. Neither ever includes a key containing *. The deletes are SQL statements, so no EntityDeleting or EntityDeleted events fire for the removed rows. The admin-auth:permissions:sync command calls syncFromRegistry(), and pruneUnregistered() with --prune.

getPermissionsForRoles() returns the deduplicated permission set across all given role IDs in a single query. Empty input returns an empty array without issuing a query.

syncPermissions() replaces a role’s permissions and syncRoles() replaces an admin user’s roles. Each deletes the existing rows and inserts the new set in batches, all inside one transaction(). A failure part-way through rolls the whole sync back, so a role is never left half-synced and a user keeps their previous roles when an id is unknown or repeated (the foreign key or the unique index rejects it). Called inside your own transaction, the sync runs in a savepoint. If it fails, only the sync’s changes are undone, and you can catch the exception and still commit the rest of your transaction.

readonly class AdminGuardResolver
{
public function guard(): GuardInterface; // AuthManager::guard(admin-auth.guard)
}
interface AdminAuthConfigInterface
{
public function getGuardName(): string;
}