Agency Pass

Self-service emergency login for agency staff on client WordPress sites.

Description

Agency Pass adds a magic-link login flow to the WordPress login screen. Staff with whitelisted email addresses can request a temporary login link that creates a time-limited user with a restricted admin role. No external infrastructure required — the entire solution is self-contained.

Requirements

• PHP 8.1+
• WordPress 6.2+

Installation

1. Upload the agency-pass directory to /wp-content/plugins/
2. Activate the plugin through the "Plugins" screen in WordPress
3. On activation, a mu-plugin loader is installed to guarantee early loading

Configuration

Add constants to wp-config.php:

Required

define( 'AGENCY_PASS_EMAIL_PATTERN', '/^.+@youragency\.de$/' );

Optional

define( 'AGENCY_PASS_TOKEN_TTL', 900 );    // Magic link validity in seconds (default: 15 min)
define( 'AGENCY_PASS_USER_TTL', 86400 );   // Temporary user lifetime in seconds (default: 24 h)

How it works

1. A "Agency Pass" button appears on the WordPress login form
2. Clicking it reveals an email input field
3. If the email matches the configured pattern, a single-use magic link is sent via wp_mail()
4. Clicking the link creates a temporary user with the agency_pass_admin role and logs them in
5. Expired users are cleaned up automatically via WP-Cron

Custom role

The agency_pass_admin role has all administrator capabilities except:

• edit_users, delete_users, create_users
• list_users, promote_users, remove_users

Extensibility

add_filter( 'agency_pass_email_allowed', function ( bool $allowed, string $email ): bool {
    // Custom validation logic here
    return $allowed;
}, 10, 2 );

Audit hooks

• agency_pass_link_requested — fired when a magic link is requested
• agency_pass_login — fired on successful emergency login
• agency_pass_user_cleanup — fired when an expired user is removed

Development

composer install
composer cs              # Run PHPCS
composer cs:fix          # Fix PHPCS violations
composer analyse         # Run PHPStan
composer test            # Run all tests
composer test:unit       # Run unit tests only

Local WordPress Environment

ddev start && ddev orchestrate

Git Hooks

git config core.hooksPath .githooks

Template Sync

git remote add template https://github.com/apermo/template-wordpress.git
git fetch template
git checkout -b chore/sync-template
git merge template/main --allow-unrelated-histories

License

GPL-2.0-or-later