Integrate with WordPress

The Login by Auth0 plugin handles login and account creation flows automatically by creating or matching user accounts with incoming Auth0 profile data. The login process and the signup process are similar and an account will be created or matched based on the data in your WordPress database. Logging in via Auth0 creates a WordPress account, and sign up via Auth0 matches an existing WordPress account.

If you are using the User Migration setting in the plugin, the login flow will be slightly different from what is explained below. To learn more, read User Migration in Login by Auth0 WordPress Plugin.

Below are the steps in the process:

  1. The user accesses the WordPress site's login page. This could be the main login page at [SITE URL]/wp-login.php or a page containing a widget or shortcode.

  2. The user provides their username and password, clicks on a social icon to use another identity provider, or completes the Passwordless process in the Auth0 login form, Lock.

  3. Auth0 attempts to authenticate the user with the method selected.

    1. If login or signup with a username + password or with Passwordless fails, an error message appears on Lock.

    2. If it is successful, the process continues.

  4. The user is redirected to the /authorize endpoint with a login ticket and a state value generated by the plugin. Once this is complete, the Auth0 user record has been created and the rest of the process happens on the WordPress site.

  5. The actual login process differs whether you are using the Authorization Code Flow or the Implicit Flow:

    1. For Authorization Code Flow logins:

      1. The user is redirected back to a callback URL, SITE URL/index.php?auth0=1 with an authorization code and the same state value in URL parameters.

      2. The state value is validated. If validation does not pass, an "Invalid state" error is shown and the login process stops. To learn more about state validation, read Troubleshoot Login by Auth0 WordPress Plugin.

      3. The ID token is validated to make sure nothing was modified during transit. If the ID token is invalid, an error message is shown and the login process stops (see the Troubleshooting page for more information on ID token validation)

      4. The user profile data is retrieved via the Management API using the Machine-to-Machine Flow. To learn more, read Machine-to-Machine Flow.

    2. For Implicit Flow logins:

      1. The user is redirected back to a callback URL, SITE URL/wp-login.php?auth0=implicit with an ID token and the same state value in an anchor link.

      2. This anchor link is parsed in JS and then POSTed back to a callback URL SITE URL/index.php?auth0=implicit with those 2 same values in URL parameters.

      3. The ID token is validated to make sure nothing was modified during transit. If the ID token is invalid, an error message is shown and the login process stops (see the Troubleshooting page for more information on ID token validation)

      4. The information in the valid ID token is used as the user profile data.

  6. The Auth0 authentication process is complete and the plugin attempts to match the profile data with a user in WordPress.

  7. The plugin checks whether the site requires an email address (plugin settings Advanced tab) and if the incoming profile has an email_verified flag set.

    1. If the site requires an email address and the incoming user does not provide an email address (some social identity providers, like X, do not include an email address), the login process stops with an error message stating "This account does not have an email associated."

    2. If the site requires an email address and the incoming user does not have the email_verified flag set to true, the login process stops with an error message stating "This site requires a verified email address" and a link to re-send the verification email. This continues to show until the user successfully verifies their email address.

    3. If the site does not require an email address or the incoming user has the email_verified flag set to true, then the login process continues.

  8. The plugin checks to see if there is a user in the WordPress database with a usermeta value that matches the incoming Auth0 user ID (meaning that the user has signed up or logged in with Auth0 before):

    1. If a user is found that has the incoming user ID then the login process continues.

    2. If a user is not found with the incoming Auth0 user ID, the plugin looks for an email address matching the incoming user:

      1. If a match is found, that user is selected and the login process continues.

      2. If a match is not found, the plugin checks if registration is turned on for the WordPress site:

        1. If registration is turned off, the login process stops with an error message stating "Could not create user. The registration process is not available".

        2. If registration is turned on, a new user is created and the login process continues.

  9. The found or created user is updated with the incoming Auth0 profile data, including their Auth0 user ID.

  10. The user is logged into their WordPress account with wp_set_auth_cookie and the core do_login action fires.

  11. The user is redirected to a page on the site, which could be the default set in the plugin settings Advanced tab or the original login URL if a shortcode or widget was used or a different one provided during the login process.

The user is now logged into Auth0 and their WordPress account with the two associated by their Auth0 user ID.

Learn more