Add Authfu to WordPress

Before you begin

You need a WordPress administrator account and permission to create an app in the Authfu console. Your site must use HTTPS in production.

The plugin computes its callback from the WordPress Site Address. Replace the example host below with your site's exact host and path, if WordPress is installed below the domain root.

https://your-site.example/wp-login.php?authfu=callback

1. Create the WordPress app

   In the Authfu console, choose Create app. Enter a name, set the application type to WordPress, and set Homepage URL to the public URL of your WordPress site.

   Add the exact callback URI shown above to the app's redirect URLs. The scheme, host, optional path, and query string must match your WordPress Site Address.

2. Download the plugin

   Open the app's Quickstart, choose WordPress, then choose Download plugin (.zip). Keep the ZIP intact for the WordPress uploader.

3. Install and activate the plugin

   In WordPress admin, open Plugins → Add Plugin → Upload Plugin. Select the downloaded ZIP, choose Install Now, then Activate Plugin.

4. Connect with the Setup Key

   Return to the app's WordPress Quickstart in the Authfu console. Under Setup Key, choose Reveal setup key, then Copy.

   In WordPress, open Settings → Authfu. Paste the value into Paste Setup Key and choose Save Setup Key. WordPress confirms the connection with “Authfu is configured.”

   Choose Test connection. A working connection reports “OpenID Connect discovery succeeded.”

5. Choose sign-in and role settings

   Leave Default role set to Subscriber unless new or unmapped users need a different WordPress role. Enable Redirect wp-login.php directly to Authfu only when you want to replace the standard WordPress login form. Choose Save Settings.

   Leave replacement disabled while testing. The normal login page then keeps the WordPress form and adds a Sign in with Authfu button.

6. Complete the first sign-in

   Sign out of WordPress and open /wp-login.php. Choose Sign in with Authfu, enter an eligible email address, and use the single-use link sent by Authfu.

   After authorization, Authfu returns to the registered callback. The plugin creates or updates the matching WordPress user, sets the mapped role, establishes the WordPress session, and sends the user to WordPress admin.

Role mapping and existing users

A WordPress app accepts one of the five standard WordPress role slugs. The plugin uses the first supported role in the Authfu claim; when no supported role is present, it uses the WordPress Default role.

administrator → Administrator
editor        → Editor
author        → Author
contributor   → Contributor
subscriber    → Subscriber

On sign-in, the plugin looks up the WordPress user by email. If a user already exists, the plugin signs in that account and replaces its current WordPress role with the mapped Authfu role. If there is no match, the plugin creates a WordPress user with that email and a generated password.

Troubleshooting

The Setup Key is rejected

“Enter a Setup Key.” means the submitted field was empty. “The Setup Key is invalid.” means the value could not be decoded into the issuer, client ID, and client secret expected by the plugin. Copy a fresh key from the same app's WordPress Quickstart and paste the complete value without added spaces.

The Authfu button does not appear

Confirm the plugin is active and Settings → Authfu shows a masked Setup Key. The button is hidden until the issuer, client ID, and client secret are all configured. If Replace default login is enabled, visiting wp-login.php redirects immediately instead of showing the button.