> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> How to configure WordPress as an application with Auth0

# 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](/docs/customize/integrations/cms/wordpress-plugin/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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  You will need to be logged into your Auth0 account before starting the steps below. If you don't have one yet, [create one](https://auth0.com/signup).
</Callout>

## Auth0 configuration

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](/docs/get-started/auth0-overview/create-tenants). To learn more about connections, read [Identity Providers](/docs/authenticate/identity-providers).

### Application setup

1. Create an Application for your WordPress site:

* **If you're troubleshooting the Setup Wizard**, navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/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](https://manage.auth0.com/#/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:

<Warning>
  The Callback URL here **must not** be cached, or you might see an "Invalid state" error during login. To learn more, read [Troubleshoot WordPress Plugin Invalid State Errors](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-wordpress-plugin-invalid-state-errors).
</Warning>

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)

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Make sure to match your site's protocol (http or https) and use the home URL as a base, found in **wp-admin > Settings > General > WordPress Address (URL)** for all URL fields above.
</Callout>

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**.

### Authorize the Application for the Management API

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 <Tooltip tip="Management API: A product to allow customers to perform administrative tasks." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>. 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](https://manage.auth0.com/#/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 Connection setup

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 <Tooltip tip="Passwordless: Form of authentication that does not rely on a password as the first factor." cta="View Glossary" href="/docs/glossary?term=passwordless">passwordless</Tooltip>, social, or enterprise logins only.

1. If you used the wizard during setup, navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/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.

### Social Connection setup

To learn how to activate and configure this login method, read [Social Identity Providers](/docs/authenticate/identity-providers/social-identity-providers).

### Enterprise Connection setup

To learn how to activate and configure this login method, read [Enterprise Identity Providers](/docs/authenticate/identity-providers/enterprise-identity-providers).

## WordPress configuration

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/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**.

## PHP constant setting storage

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 <Tooltip tip="Client Secret: Secret used by a client (application) to authenticate with the Authorization Server; it should be known to only the client and the Authorization Server and must be sufficiently random to not be guessable." cta="View Glossary" href="/docs/glossary?term=client+secret">client secret</Tooltip>, 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](https://developer.wordpress.org/advanced-administration/security/hardening/)).

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](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/). 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](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)). All plugin options can be overridden and their keys can be found in the `WP_Auth0_Options::defaults()` method.

**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 <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

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.

## Plugin settings

### Basic

* **Domain:** The Domain copied from the Application settings in your dashboard. Option name is `domain`.
* **<Tooltip tip="Custom Domain: Third-party domain with a specialized, or vanity, name." cta="View Glossary" href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip>:** The Custom Domain for your tenant, if one is configured. To learn more, read [Custom Domains](/docs/customize/custom-domains). Option name is `custom_domain`.
* **<Tooltip tip="Client ID: Identification value given to your registered resource from Auth0." cta="View Glossary" href="/docs/glossary?term=Client+ID">Client ID</Tooltip>:** 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`.
* **<Tooltip tip="JSON Web Token (JWT): Standard ID Token format (and often Access Token format) used to represent claims securely between two parties." cta="View Glossary" href="/docs/glossary?term=JWT">JWT</Tooltip> Signature Algorithm** The algorithm used for signing tokens from the Advanced Application Settings, <Tooltip tip="OAuth 2.0: Authorization framework that defines authorization protocols and workflows." cta="View Glossary" href="/docs/glossary?term=OAuth">OAuth</Tooltip> 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**.

### Features

* **<Tooltip tip="Universal Login: Your application redirects to Universal Login, hosted on Auth0's Authorization Server, to verify a user's identity." cta="View Glossary" href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page:** Redirects the `wp-login.php` page to the Universal Login Page for <Tooltip tip="Single Sign-On (SSO): Service that, after a user logs into one applicaton, automatically logs that user in to other applications." cta="View Glossary" href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (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`.

### Embedded

Options here do not affect the Universal Login Page (To learn about customization options, read [Auth0 Universal Login](/docs/authenticate/login/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](/docs/libraries/lock/lock-configuration). 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 <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+providers">identity providers</Tooltip> you want to allow users to login with. If left blank, all enabled providers will be allowed. (To learn more, read [Lock UI Customization](/docs/libraries/lock/lock-ui-customization).) Option name is `lock_connections`.

  <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
    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](https://github.com/auth0/lock-passwordless#socialoptions-callback).
  </Callout>

### Advanced

* **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 Timeout](/docs/manage-users/sessions/session-lifetime-limits)docs/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`.

  <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
    If registrations are allowed in WordPress, new users will be created regardless of this setting.
  </Callout>
* **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](https://manage.auth0.com/#). To learn more about the migration process, read [User Migration in Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0). 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`.

## Learn more

* [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Troubleshoot Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0)
* [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)