Install Login by Auth0

In order to install or customize plugins, you must use a self-hosted WordPress.org site. Using a WordPress.com site does not allow installing plugins. To learn more about the differences, read WordPress.com and WordPress.org on wordpress.com.

This plugin can be added to your WordPress site using the Plugins screen in the wp-admin:

  1. Log in to an existing WordPress site as an administrator.

  2. Go to Plugins > Add New in the admin menu on the left.

  3. Search for "Login by Auth0"

  4. For the Login by Auth0 plugin, click Install Now, then Activate.

To learn more about this process, read WordPress.com and WordPress.org on wordpress.com.

As soon as the plugin is activated, you are redirected to the start of the Setup Wizard.

If you don't already have an Auth0 account, sign up for free to create one before proceeding.

Auth0 will not replace your login forms until a Domain, Client ID, and Client Secret have been added to the Basic tab of the settings page.

Multisite setup

The Login by Auth0 plugin is compatible with WordPress multisite networks. The plugin can be network activated to automatically protect network sites (once configuration is complete) or activated only on a sub-set of the network.

There are a few ways that a network of sites can be set up in Auth0:

  1. All sites can share both an Application and a database connection

    1. Run the Setup Wizard steps to completion for the main site.

    2. Configure all other sites manually using the Domain, Client ID, and Client Secret from the main site in the Basic tab of the Auth0 settings page.

    3. Update the Application's Allowed Callback URLs, Allowed Web Origins, and Allowed Logout URLs to include each site (wildcards can be used if your network uses subdomains).

  2. Each site can have its own Application and share a database connection

    1. Run the Setup Wizard steps to completion for the main site.

    2. Next, manually create an Application for each site and add each one to the previously-created database connection.

    3. Add the Domain, Client ID, and Client Secret values to the Basic tab of the Auth0 settings page for each site.

  3. Each site can have its own Application and its own database connection. In this case, Run the Setup Wizard steps to completion for each site.

Each of the options above has trade-offs. Option 1 has the least number of different entities to manage in Auth0 but, if your network has hundreds of sites and you're not using subdomains, you might run into limitations with the number of callback URLs. Option 2 will require managing many different Applications but will allow you to configure each site's Application differently.

As always, if you have any questions about this configuration process, create a post in our Community and tag it "wordpress".

Setup Wizard

The Setup Wizard will attempt to create all the necessary components needed to use Auth0 on your WordPress site. If you have an existing Application or Database Connection you want to use, please see the Manual Setup steps below.

Option 1: Standard Setup

This will create and configure an Application and a Database Connection for this site.

First, generate a Management API token. Once the token is generated, make a note of the domain name used in the Identifier field under the Settings tab. For example, if your Identifier is https://tenant-name.auth0.com/api/v2/, then the tenant domain is tenant-name.auth0.com. To learn more about tenant domains, read Create Tenants.

Back in the WordPress admin's Setup Wizard, click Standard. In the modal that appears, click Start Standard Setup.

Enter the tenant domain and API token from above. This token is only used for the setup process and will not be saved in the database.

If the first part of the setup successfully completes, you'll see the "Configure your social connections" screen. Click Next to continue the setup process by migrating your administrator account.

This step connects your WordPress user with an Auth0 user that authorizes you to log in. You can choose the same password as your admin account or a different one, but make sure it conforms to the password strength policies for the database Connection being used. To learn more, read Password Strength in Auth0 Database Connections: Password Policies.

The Setup Wizard must run to completion for your site to be configured correctly. If the Wizard fails for any reason before the "setup successful" screen, check the plugin error log at wp-admin > Auth0 > Error Log and the steps below to determine the issue.

To start the process over completely, delete any Applications or Database Connections that were created in the Auth0 Dashboard. In WordPress, go to Auth0 > Settings > Basic, delete the Domain, Client ID, and Client Secret fields, and click Save. Now, click Setup Wizard in the admin menu to start the process over again.

If you're still not able to install, post a thread in our Community with the error messages you're seeing in the Error Log, and we'll be happy to help!

Option 2: User Migration Setup

This will create and configure an Application and a database connection plus data migration from your WordPress database. This requires an inbound connection from Auth0 servers and cannot be changed later without losing data. To learn more, read User Migration in Login by Auth0 WordPress Plugin.

::: warning If you have more than one custom database connection in Auth0, you'll need to make sure that the user IDs are namespaced to avoid conflicts. This is done automatically for sites installing version 3.11.0 or later. If your connections are/were being created with an earlier version, read the troubleshooting steps in User Migration in Login by Auth0 WordPress Plugin. :::

Once the configuration process is complete, log out of your WordPress site and attempt to log back in using your existing WordPress credentials in the Auth0 login form. This should create an Auth0 user linked to your WordPress account.

Option 3: Manual Setup

This will skip the automatic setup and allow you to create and configure your own Application and database connection (see below). This should be used if you want this site to use an existing Application or database connection.

Option 4: Import Setup

The site can also be set up by importing settings from another site. This is useful if you're migrating between environments or have a similar WordPress site that is already configured.

Setup complete

When you see the "Done" screen, Auth0 is enabled and ready to accept logins and, if configured, signups.

This is a good time to confirm that the basics are working for your site before changing any of the default settings:

  1. Log out of WordPress and confirm that the Auth0 form now appears at /wp-login.php.

  2. Log in with the Auth0 user created above.

  3. Log out and try creating an account with a different email address (if you have "Anyone can register" turned on in your General WordPress settings).

  4. Try logging in using a social connection (if you've turned those on).

Now you're ready to configure the application.

Manual setup

The plugin can be configured using the built-in Setup Wizard (covered below) or manually by creating an Application and assigning connections. The completely manual setup process can be used if you're having trouble with the wizard, have been through the setup process before, or want to share a database connection between Applications.

  1. Go to Auth0 Dashboard > Applications > Applications, and select Create.

  2. Give your application a descriptive name, select Regular Web Applications, then select Create.

  3. Configure the application for your WordPress installation. To learn how to configure the application, read Configure Login by Auth0 and follow all sections through "Update Auth0 settings in WordPress".

Once the steps above are complete, your site will be configured and ready to use.

Learn more