Configure Login by Auth0

Login by Auth0 can be configured using the Setup Wizard in the plugin or manually for more control over the process. To learn more, read Install Login by Auth0. The instructions below can also be used if the Setup Wizard did not complete or as part of troubleshooting login issues.

Your Auth0 tenant must be configured to accept login requests from your WordPress site and source user identities from at least one Connection, whether that's an Auth0 database, a social connection, or a business directory. To learn more about tenants, read Create Tenants. To learn more about connections, read Identity Providers.

1. Create an Application for your WordPress site:

• If you're troubleshooting the Setup Wizard, navigate to Auth0 Dashboard > Applications > Applications, and look for an Application that is similar to your WordPress site name. If you don't find one, it means that an Application was not created by the Wizard. Restart the Setup Wizard in WordPress or follow the step just below to create an Application manually.

• If you're configuring manually, navigate to Auth0 Dashboard > Applications > Applications, and select Create. Enter a name for the Application, select Regular Web Applications, and select Create.

1. Select the Settings view for the Application. You will see your Domain, Client ID, and Client Secret, which are used in wp-admin > Auth0 > Settings to connect to Auth0.

2. Application Type must be set to Regular Web Application and Token Endpoint Authentication Method must be set to Post

3. Scroll down to Allowed Callback URLs and provide the WordPress site URL with ?auth0=1 appended:

1. Enter your WordPress site's WordPress Address (URL) (where the WordPress site appears publicly) and, if different, the Site Address (URL) (where wp-admin is served from) in the Allowed Web Origins field. Both of these values are found on your WordPress site's general settings screen.

2. Enter your WordPress site's login URL in the Allowed Logout URLs field

3. Leave the Allowed Origins (CORS) field blank (it will use the Allowed Callback URLs values from above)

1. Scroll down and select Show Advanced Settings, then select the OAuth view and make sure JsonWebToken Signature Algorithm is set to RS256. If this needs to be changed later, it should be changed here as well as in wp-admin (see Settings > Basic below).

2. Turn on OIDC Conformant.

3. Click the Grant Types tab and select at least Authorization Code and Client Credentials.

4. Click Save Changes.

In order for your WordPress site to perform certain actions on behalf of your Auth0 tenant, you'll need to authorize the Application created above to access the Management API. This is not required but will enable retrieving complete user data on login (including user_metadata and app_metadata), email and password changes for users, and email verification re-sending when verified emails are required.

1. Make sure your Application allows the Client Credentials grant (step 10 in the section above).

2. Navigate to Auth0 Dashboard > Applications > APIs.

3. Select Auth0 Management API, then the Machine to Machine Applications view.

4. Look for the WordPress Application and select Unauthorized to grant access.

5. In the panel that appears, select only the read:users and update:users scopes, then select Update (you can search using the Filter scopes field).

Database Connections enable username and password login with user records stored at Auth0. This type of Connection is not required and can be skipped if you're using passwordless, social, or enterprise logins only.

1. If you used the wizard during setup, navigate to Auth0 Dashboard > Authentication > Database and look for a Connection that has a similar name to the Application setup above. Otherwise, you can create a new Connection, use an existing Connection, or use the default Username-Password-Authentication. Select an existing Connection name to view settings or select Create DB Connection and follow the steps.

2. Select the Applications view and activate the Application created above.

To learn how to activate and configure this login method, read Social Identity Providers.

To learn how to activate and configure this login method, read Enterprise Identity Providers.

1. Go to Auth0 Dashboard > Applications > Applications and select the Application created above.

2. In a new tab/window, log in to wp-admin for your WordPress site and go to wp-admin > Auth0 > Settings.

3. Copy Domain, Client ID, and Client Secret from your Auth0 Application page to your WordPress settings using the Copy to Clipboard buttons next to each field.

4. Scroll down and select Save Changes.

Plugin settings can be saved to the database (default) or they can be set using a specifically named PHP constant. This will allow for sensitive data like the client secret, API token, and migration token to be stored more securely (assuming that file they are defined in is stored securely; to learn more, read Hardening WordPress on wordpress.org).

The constant must be defined before the plugin is loaded or it will not be used. This should happen in your wp-config.php file or in a must-use plugin. To learn more, read Must Use Plugins on wordpress.org. If the constant is defined in your theme's functions.php or in a plugin that loads after Auth0, the value will be ignored.

The PHP constants are defined like so:

The default constant name should be AUTH0_ENV_ followed by the option name to override in all caps (the prefix can be modified with the auth0_settings_constant_prefix filter; to learn more, read Extend Login by Auth0 WordPress Plugin). All plugin options can be overridden and their keys can be found in the WP_Auth0_Options::defaults() method. To see which options are available, view WordPress Auth0 Lock Options in our GitHub repository.

Note: The migration_token value is generated by the plugin when user migration is turned on. If there is already a value in the admin, make sure to set the constant to the same value. If that value needs to change, it also must be changed in the custom scripts for the database Connection being used in the Auth0 dashboard.

The settings field will change its display based on this new value and show the constant being used for reference. This value will be used everywhere in the plugin automatically.

Important: Saving the settings page after setting a constant value will validate the constant-set values (but not change them) and delete them from the options array being saved to the database. If you are just testing this functionality, do not save settings in the WordPress admin page until you're ready to delete that value.

All sites in a WordPress multi-site network will use the same constant value making this an easy way to setup a network using a single Application and database Connection.

• Domain: The Domain copied from the Application settings in your dashboard. Option name is domain.

• Custom Domain: The Custom Domain for your tenant, if one is configured. To learn more, read Custom Domains. Option name is custom_domain.

• Client ID: The Client ID copied from the Application settings in your dashboard. Option name is client_id.

• Client Secret: The Client Secret copied from the Application settings in your dashboard. Option name is client_secret.

• JWT Signature Algorithm The algorithm used for signing tokens from the Advanced Application Settings, OAuth tab; default is RS256. Option name is client_signing_algorithm.

• JWKS Cache Time (in minutes): How long the JWKS information should be stored when using the RS256 JWT Signature Algorithm. Option name is cache_expiration.

• Original Login Form on wp-login.php: Provides ways to access or block the core WordPress login page. Option name is wordpress_login_enabled. Login page code option name is wle_code.

  • Never will not allow the core WordPress login form to display.

  • Via a link under the Auth0 form will display a link to the WordPress core login form directly below the Auth0 embedded one on wp-login.php. The login page can also be accessed directly by adding ?wle to the login URL.

  • When "wle" query parameter is present will allow the login page to be accessed directly by adding ?wle to the login URL. This will bypass the Universal Login Page redirect.

  • When "wle" query parameter contains specific code will allow the login page to be accessed directly by adding ?wle= plus a code to the login URL. The code is generated automatically and will be shown below the controls for this setting. This will bypass the Universal Login Page redirect.

• Allow Signups: User signup will be available only if the WordPress Anyone can register option is enabled. You can find this setting under Settings > General > Membership.

• Universal Login Page: Redirects the wp-login.php page to the Universal Login Page for Single Sign-on (SSO) authentication using all active Connections for this Application. Option name is auto_login.

• Auto Login Method: A single, active connection to use for authentication when Universal Login Page is turned on. Leave this blank to show all active Connections on the Universal Login Page. Option name is auto_login_method.

• Auth0 Logout: Enable this option to log out of Auth0 when logging out of WordPress. Option name is singlelogout.

• Override WordPress Avatars: Forces WordPress to use Auth0 avatars. Option name is override_wp_avatars.

Options here do not affect the Universal Login Page (To learn about customization options, read Auth0 Universal Login).

• Passwordless Login: Enable this option to turn on Passwordless login on all embedded Auth0 login forms. Passwordless connections are managed in the Auth0 dashboard and at least one must be active and enabled on this Application for this to work. Option name is passwordless_enabled.

• Icon URL: Sets the icon above the embedded Auth0 login form. Option name is icon_url.

• Form Title: Sets the title of the embedded Auth0 login form. Option name is form_title.

• Enable Gravatar Integration: When user enters their email, their associated Gravatar picture is displayed in the embedded Auth0 login form. Option name is gravatar.

• Login Name Style: Selecting Email will require users to enter their email address to login. Set this to Username if you do not want to force a username to be a valid email address. Option name is username_style. Option name is client_secret_b64_encoded.

• Primary Color: To learn more about this setting, read Lock Configuration Options. Option name is primary_color.

• Extra Settings: A valid JSON object that includes options to call Lock with. This overrides all other options set above. For a list of available options, see the Lock: User configurable options (e.g.: {"disableResetAction": true }). Option name is extra_conf.

• Use Custom Lock JS URL: When turned off, WordPress will use the latest tested version of Lock (Auth0 embedded login form) automatically. When turned on, administrators can provide a custom Lock URL to use. Option name is custom_cdn_url.

• Custom Lock JS URL: A valid URL pointing to a version of Lock. This field will be automatically hidden when Use Custom Lock JS URL is turned off. Option name is cdn_url.

• Connections to Show: List here each of the identity providers you want to allow users to login with. If left blank, all enabled providers will be allowed. (To learn more, read Lock UI Customization.) Option name is lock_connections.

  If you have enabled Passwordless login, you must list here all allowed social identity providers. To learn more, read .social(options, callback) in our GitHub repository.

• Require Verified Email: If set, requires the user to have a verified email to log in. This can prevent some Connections from working properly if they do not provide an email address or an email_verified flag in the user profile data. Option name is requires_verified_email.

• Skip Strategies: If Require Verified Email is turned on, this setting will display. This field accepts strategy names to skip the verified email requirement on login and account association. This should only be used for strategies that do not provide an email_verified flag.

• Remember User Session: By default, user sessions live for two days. Enable this setting to keep user sessions live for 14 days. Option name is remember_users_session.

  • This setting must be less than or equal to your tenant's Inactivity Timeoutdocs/manage-users/sessions/session-lifetime-limits setting to ensure that the user's session is properly maintained.

• Login Redirection URL: If set, redirects users to the specified URL after login. This does not affect logging in via the [auth0] shortcode. Option name is default_login_redirection. To change the redirect for the shortcode, add a redirect_to attribute, like so:

  [auth0 redirect_to="http://yourdomain.com/redirect-here"]

• Force HTTPS Callback: Enable this option if your site allows HTTPS but does enforce it. This will force Auth0 callbacks to HTTPS in the case where your home URL is not set to HTTPS. Option name is force_https_callback.

• Auto Provisioning: Should new users from Auth0 be stored in the WordPress database if new registrations are not allowed? This will create WordPress users that do no exist when they log in via Auth0 (for example, if a user is created in the Auth0 dashboard). Option name is auto_provisioning.

  If registrations are allowed in WordPress, new users will be created regardless of this setting.

• User Migration: Enabling this option will expose the Auth0 migration web services. However, the Connection will need to be manually configured in the Auth0 Dashboard. To learn more about the migration process, read User Migration in Login by Auth0 WordPress Plugin. The Generate New Migration Token button can be used to replace the saved token with a new one. Make sure to have your database Connection configuration page open to the Custom Database tab so you can replace the existing token with the new one in both scripts. Option name is migration_ws. Migration token option name is migration_token.

• Migration IPs AllowList: Only requests from listed IPs will be allowed access to the migration webservice. Option name is migration_ips_filter.

• Valid Proxy IP: List the IP address of your proxy or load balancer to enable IP checks for logins and migration web services. Option name is valid_proxy_ip.

• Auth0 Server Domain: The Auth0 domain, it is used by the setup wizard to fetch your account information. Option name is auth0_server_domain.

• Integrate with WordPress
• Install Login by Auth0
• Troubleshoot Login by Auth0 WordPress Plugin
• Extend Login by Auth0 WordPress Plugin