Skip to content

Adam Greenwell

Custom Login Integration

Guard Dog exposes a small public API for sites that use a custom login surface instead of the default WordPress login form.

The intended ownership split is:

  • The custom login plugin or theme owns primary password validation, request nonces, form state, and final redirect policy.
  • Guard Dog owns 2FA method discovery, 2FA code delivery, 2FA code verification, passkey login markup, passkey login assets, and passkey AJAX authentication.
  • Templates should call Guard Dog helper functions instead of reading Guard_Dog()->features or feature internals directly.

2FA Helpers

Use these after primary credentials have been validated by the custom login flow:

guard_dog_is_login_2fa_available();
guard_dog_get_login_2fa_status( $user );
guard_dog_send_login_email_2fa_code( $user );
guard_dog_verify_login_2fa_code( $user, $code, $method );

guard_dog_get_login_2fa_status() returns:

array(
    'available'          => true,
    'requires_2fa'       => true,
    'has_app_2fa'        => true,
    'has_email_2fa'      => false,
    'has_recovery_codes' => true,
    'user_id'            => 123,
);

The $method value for guard_dog_verify_login_2fa_code() should be one of app, email, or recovery.
The $user value may be a user ID, WP_User object, username, or email address.

Passkey Helpers

Use these on custom login templates that want to offer passkey sign-in:

guard_dog_is_passkey_login_available();
guard_dog_get_passkey_login_button_markup( $args );
guard_dog_enqueue_passkey_login_assets( $args );

Example:

if ( guard_dog_is_passkey_login_available() ) {
    echo guard_dog_get_passkey_login_button_markup(
        array(
            'button_class' => 'btn btn-outline-secondary w-100',
            'show_icon'    => false,
        )
    );

    guard_dog_enqueue_passkey_login_assets(
        array(
            'username_selector' => '#email',
            'redirect_to'       => home_url( '/dashboard/' ),
        )
    );
}

Passkey authentication AJAX is routed early on admin_init so logged-out requests to wp-admin/admin-ajax.php can complete before generic admin guards run.

For shortcode and block-based login pages, the same login button is available as a primitive surface:

echo do_shortcode( '[guard_dog_passkey_login username_selector="#email" redirect_to="/dashboard/"]' );

The matching dynamic block is guard-dog/passkey-login.

Supported shortcode attributes:

Attribute Default Purpose
username_selector #user_login CSS selector for the username or email field the passkey flow should read before requesting authentication options.
redirect_to empty URL to send the user to after successful passkey authentication. Leave empty to use Guard Dog's default redirect behavior.
wrapper_class guard-dog-passkey-login Wrapper class list for custom theme styling.
button_class button button-secondary guard-dog-passkey-login__button Button class list for custom theme styling.
status_class guard-dog-passkey-login__status Status message class list for custom theme styling.
show_icon true Shows the Dashicons passkey icon when truthy.

The standalone login surface emits unique button/status IDs and data attributes for each instance, so it can safely sit beside the full Guard Dog login form or another custom login module.

2FA Styling

Use this helper when a custom login surface renders Guard Dog-compatible 2FA forms:

guard_dog_enqueue_login_2fa_assets();

Frontend Account Security

Use primitive shortcodes when a custom template wants to place each account-security module independently:

echo do_shortcode( '[guard_dog_two_factor]' );
echo do_shortcode( '[guard_dog_passkeys]' );
echo do_shortcode( '[guard_dog_sessions]' );

The legacy [guard_dog_2fa] shortcode remains supported. For new templates, prefer [guard_dog_two_factor] when you only want 2FA controls.

Available frontend surfaces:

Surface Shortcode Dynamic block Notes
Login form [guard_dog_login_form] guard-dog/login-form Public Guard Dog-managed login form.
Passkey login [guard_dog_passkey_login] guard-dog/passkey-login Public passkey sign-in button for logged-out visitors.
2FA management [guard_dog_two_factor] guard-dog/two-factor-auth Logged-in app 2FA, email 2FA, and recovery-code management.
Passkey management [guard_dog_passkeys] guard-dog/passkeys Logged-in passkey registration, rename, and deletion. Returns no output when passkeys are disabled.
Session management [guard_dog_sessions] guard-dog/sessions Logged-in active-session review and termination.
Account security [guard_dog_account_security] guard-dog/account-security Composite wrapper for the account-security modules.

The account-management primitives support style="default", style="minimal", and style="compact". Primitive and composite surfaces are instance-safe; they generate unique DOM IDs so block themes, account dashboards, and shortcode-heavy templates can render more than one module on the same page without duplicate IDs.

Use the composite account-security shortcode on logged-in account or dashboard pages that should expose Guard Dog-managed 2FA, passkeys, and active sessions together:

echo do_shortcode( '[guard_dog_account_security show_passkeys="true" show_sessions="true"]' );

Set show_2fa="false" when a custom template only wants the passkey and/or session-management pieces inside its own account-security layout.

Composite shortcode attributes:

Attribute Default Purpose
style default Visual style: default, minimal, or compact.
show_2fa true Render the 2FA management module.
show_passkeys true Render passkey management when passkeys are enabled.
show_sessions false Render active-session management when session tracking is enabled.

Matching dynamic blocks are available for block-based themes:

guard-dog/two-factor-auth
guard-dog/passkeys
guard-dog/sessions
guard-dog/account-security

If the template renders the shortcode after wp_head, prime assets before the header prints:

if ( function_exists( 'guard_dog_enqueue_account_security_assets' ) ) {
    add_action( 'wp_enqueue_scripts', function() {
        guard_dog_enqueue_account_security_assets(
            array(
                'show_2fa'      => true,
                'show_passkeys' => true,
                'show_sessions' => true,
            )
        );
    } );
}

← Frontend Shortcodes and Blocks | Documentation Home | Troubleshooting →