Docs

Extending the Login by Auth0 WordPress Plugin

WordPress plugins can be extended to fit your specific requirements by using actions and filters to run custom code at specific points during runtime. This document outlines the existing hooks in the Login by Auth0 plugin. We're happy to review and approve new filters and actions that help you integrate even further in this plugin. Please see the Contributing section on the GitHub repo readme for this plugin.

Actions

Actions in WordPress run custom code at specific points during processing. Learn more about actions here. These examples are maintained here.

auth0_before_login

This action runs in WP_Auth0_LoginManager after a user has been authenticated successfully but before they have been logged into WordPress. It can be used to stop the login process if needed using wp_die() or throwing an exception.

Example:

auth0_user_login

This action runs in WP_Auth0_LoginManager after a user has been authenticated successfully and logged into WordPress. It can be used to set specific meta values, send notifications, or ping other services.

Example:

wpa0_user_created

This action runs in WP_Auth0_Users just after a WordPress user is successfully created. It can be used to change user values, set additional user metas, or trigger other new user actions.

Example:

Filters

Filters in WordPress also run custom code at specific points during processing but always return a modified value of the same type that was passed in. Learn more about filters here. These examples are maintained here.

auth0_get_wp_user

This filter is called after the plugin finds the related user to login (based on the auth0 user_id) and is used to override the default behavior with custom matching rules (for example, always match by email).

If the filter returns null, it will lookup by email as described in the How does it work? document.

Example:

auth0_verify_email_page

This filter runs in WP_Auth0_Email_Verification to change the HTML rendered when a user who is logging in needs to verify their email before gaining access to the site. Note that this HTML is passed to wp_die() where it is modified before being displayed (see the _default_wp_die_handler() definition in core for more information).

Example:

auth0_get_auto_login_connection

This filter is used in WP_Auth0_LoginManager to modify what connection is used for the auto-login process. The setting in wp-admin is pulled and then passed through this filter.

Example:

wp_auth0_get_option

This filter is used by option-getting functions and methods to modify the output value.

Example:

auth0_migration_ws_authenticated

This filter is used in WP_Auth0_Routes to alter the WP_User object that is JSON-encoded and returned to Auth0 during a user migration.

Example:

wpa0_should_create_user

This filter is used in WP_Auth0_Users when deciding whether a user should be created. The initial value passed in is TRUE. If FALSE is returned for any reason, registration will be rejected and the registering user will see an error message (see WP_Auth0_UsersRepo::create()).

Example:

auth0_login_css

This filter is used to modify the CSS on the login page, including the login widget itself. This filter runs before CSS is retrieved from the wp-admin settings page.

Example:

auth0_login_form_tpl

Filters the template used for the Auth0 login form. This should return a path to a file containing HTML that replaces what is in wp-content/plugins/auth0/templates/auth0-login-form.php. The standard Lock initiation JS looks for an ID attribute of auth0-login-form to instantiate the login form so make sure that's present or replace the wp-content/plugins/auth0/assets/js/lock-init.js file with your own.

auth0_settings_fields

This filter is used to modify an existing form field or to add a new one. This should return a modified $options array with your changes or additions. New fields must have a field callback, as shown below.

auth0_auth_scope

This filter allows developers to add or change the scope requested during login. This can be used to add custom claims or request a Refresh Token.

Use this filter to modify the cookie name used for nonce validation. See the auth0_state_cookie_name filter below for an example.

Use this filter to modify the cookie name used for the state parameter value. This can add a prefix or suffix or replace the string entirely. Make sure to use valid characters in any modifications made:

A <cookie-name> can be any US-ASCII characters except control characters (CTLs), spaces, or tabs. It also must not contain a separator character like the following: ( ) < > @ , ; : \ " / [ ] ? = { }.

Read more about the Set-Cookie HTTP response header at the MDN's Set-Cookie documentation.

auth0_settings_constant_prefix

Use this filter to change the prefix for the constant used to override plugin settings. Please note that this filter must run before WP_Auth0::init() so it should be located in an MU plugin.

auth0_authorize_url_params

This filter allows developers to adjust the /authorize endpoint parameters as needed. The function must return a dictionary-type array of URL parameters. See the Login section of the Authentication API docs for more information on how these parameters are used.

auth0_authorize_url

This filter allows developers to adjust the complete /authorize URL before use. The function must return a valid URL as a string. See the Login section of the Authentication API docs for more information on how this URL is used.

auth0_die_on_login_output

This filter lets you modify or replace the HTML content passed to wp_die() when there is an error during login. This filter does not affect the verify email content (see auth0_verify_email_page).

auth0_sso_auth0js_url

This filter lets you override the default CDN URL for Auth0.js when doing a Single Sign-on (SSO) check on the wp-login.php page.

auth0_coo_auth0js_url

This filter lets you override the default CDN URL for Auth0.js when loading the COO fallback page.

auth0_slo_return_to

This filter lets you override the default returnTo URL when logging out of Auth0.

auth0_use_management_api_for_userinfo

This filter determines whether or not user profile data retrieved from the Management API should when you're not using the Implicit Login Flow. Return a boolean true (default) to use the API, false to use the ID token.

auth0_lock_options

This filter can be used to modify the options for the embedded Lock login form used in shortcodes, widgets, and on the wp-login.php page when Features > Universal Login Page is turned off.

auth0_jwt_leeway

This filter lets you adjust the leeway time used to validate ID tokens and should return a number of seconds as an integer.

Additional Extensions

Additional examples can be found here.

Keep Reading

More information on the Login by Auth0 WordPress plugin: