How Auth0 Integrates 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 rather than the initial action taken. In other words, logging in via Auth0 can create a WordPress account and signing up via Auth0 can match an existing WordPress account.

The process runs as follows:

  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.
  • If login or signup with a username + password or with Passwordless fails, an error message will appear on Lock.
  • If it is successful, the process continues below.
  1. 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.
  2. The actual login process differs whether you are using the Authentication Code flow or the Implicit Login flow ("Implicit Login Flow" on the Advanced tab of the plugin settings is turned off [default] for the former, on for the latter):
  • For Authentication Code grant 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 (see the Troubleshooting page for more information on state validation).
    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 a Client Credentials grant.
  • For Implicit Grant 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.
  1. At this point, the Auth0 authentication process is complete and the plugin attempts to match the profile data with a user in WordPress.
  2. 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.
  • If the site requires an email address and the incoming user does not provide an email address (some social identity providers, like Twitter, do not include an email address), the login process stops with an error message stating "This account does not have an email associated."
  • 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 will continue to show until the user successfully verifies their email address.
  • 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.
  1. 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):
  • If a user is found that has the incoming user ID then the login process continues.
  • If a user was not found with the incoming Auth0 user ID, the plugin will look for an email address matching the incoming user:
    • If a match is found, that user is selected and the login process continues.
    • If a match is not found, the plugin check if registration is turned on for the WordPress site:
      • If registration is turned off, the login process stops with an error message stating Could not create user. The registration process is not available.
      • If registration is turned on, a new user is created and the login process continues.
  1. The found or created user is updated with the incoming Auth0 profile data, including their Auth0 user ID.
  2. The user is logged into their WordPress account with wp_set_auth_cookie and the core do_login action fires.
  3. Finally, the user is redirected to a page on the site (this could be the default one 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.

Data Migration

If you enable data migration, the plugin will expose two secure endpoints that allow Auth0 authenticate the users. These endpoints are secured with a secret token and only available to IP addresses associated with Auth0. You can change this in the Auth0 Dashboard's Application Advanced Settings page.

The login flow is as follows:

  1. The user accesses your WordPress site's login page and provides their credentials.
  2. Auth0 can't find a user associated with the provided credentials, so it proceeds to call the migration endpoint.
  3. The plugin finds a user in your WordPress database with the provided username/email, so it verifies the password.
  4. Auth0 creates the user in your Auth0 account, authenticates the user, and logs them in.

Keep Reading

More information on the Login by Auth0 WordPress plugin: