Extend 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. To learn more, read the Contributing section in the ReadMe in the plugin’s GitHub repository.

WordPress Actions

WordPress Actions run custom code at specific points during processing. To learn more about WordPress Actions, read WordPress Plugin Handbook: Actions on wordpress.org. You can also see examples in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. To learn more about filters, read WordPress Plugin Handbook: Filters on wordpress.org. You can also see examples in the GitHub repository.

auth0_create_user_data

This filter can be used to modify the user data array when creating a new user in WordPress from an incoming Auth0 user. It receives 2 parameters:

• $user_data is the user data parsed from the Auth0 profile.
• $userinfo is the Auth0 user profile.

This filter should always return an array of data that will be passed to the core wp_insert_user() function. You can see an example in the GitHub repository.

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). You can see an example in the GitHub repository.

If the filter returns null, it will look up by email. To learn more, read Integrate with WordPress.

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). You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

wp_auth0_get_option

This filter is used by option-getting functions and methods to modify the output value. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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 (WP_Auth0_UsersRepo::create()). You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

auth0_nonce_cookie_name

Use this filter to modify the cookie name used for nonce validation. See the auth0_state_cookie_name filter below for an example. You can see an example in the GitHub repository.

auth0_state_cookie_name

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. You can see an example in the GitHub repository. To learn more about the state parameter, read Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters. 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: ( ) < > @ , ; : \ " / ? = { }.

To learn more about the Set-Cookie HTTP response header, read Set-Cookie in MDN Web Docs.

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 the Auth0 plugin is loaded so it needs to be located in an MU plugin. You can see an example in the GitHub repository. To learn more about MU plugins, read Must Use Plugins on wordpress.org.

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. To learn more about how these parameters are used, read Authentication API Explorer: Login. You can see an example in the GitHub repository.

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. To learn more about how this URL is used, read Authentication API Explorer: Login. You can see an example in the GitHub repository.

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). You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

auth0_logout_url

This filter lets you override the Auth0 logout URL. To learn more about how this is used, read Logout. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

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. You can see an example in the GitHub repository.

auth0_jwt_max_age

This filter lets you adjust the max_age URL parameter sent on the authorize URL. You can see an example in the GitHub repository.

auth0_authorize_state

This filter lets you filter the state data before being encoded and used for login. This data will be verified after a successful login and provided as-is for use. You can see an example in the GitHub repository.

Use case

You can see an example of using actions with filters in the GitHub repository.

Learn more

• Integrate with WordPress
• Install Login by Auth0
• Configure Login by Auth0
• Troubleshoot WordPress Plugin Invalid State Errors