VOOZH about

URL: https://deepwiki.com/auth0/wordpress/2.4-first-login-test

⇱ First Login Test | auth0/wordpress | DeepWiki

Loading...
Loading...
Menu

First Login Test

This document provides instructions for testing the authentication flow after installing and configuring the Auth0 WordPress plugin. It explains how to verify that your installation is working correctly by performing a test login, what to expect during the process, and how to troubleshoot common issues.

For information about configuring the plugin settings before testing, see WordPress Plugin Configuration. For details about the Auth0 application setup required before testing, see Auth0 Application Setup.

Prerequisites

Before testing the authentication flow, ensure the following are complete:

RequirementStatus Check
Plugin installed and activatedNavigate to WordPress Dashboard → Plugins → Installed Plugins
Auth0 Application configuredVerify Domain, Client ID, and Client Secret in Auth0 Dashboard
Plugin configuration savedNavigate to WordPress Dashboard → Auth0 → Options
"Enable Authentication" enabledVerify checkbox is selected in Auth0 → Options
Callback URL configured in Auth0Must include your WordPress site's wp-login.php URL

The plugin validates its readiness by checking for required configuration fields in the Plugin::isReady() method, which verifies the presence of Client ID, Client Secret, Domain, and Cookie Secret.

Sources: src/Plugin.php182-219 README.md100-152

Authentication Flow Overview

The following diagram illustrates the complete authentication flow that will occur during your first login test, showing how WordPress, the plugin, and Auth0 interact:



Sources: src/Actions/Authentication.php433-551 src/Actions/Authentication.php660-724




Step-by-Step Test Procedure


1. Log Out of WordPress


If you are currently logged into WordPress, log out to ensure a clean test:


    

  1. Navigate to your WordPress Dashboard
    2. 

  2. Hover over your username in the top-right corner
    3. 

  3. Click "Log Out"
    4. 



2. Access the Login Page


Navigate to your WordPress login page by appending /wp-login.php to your WordPress site URL:


https://yoursite.com/wp-login.php



Replace yoursite.com with your actual domain.


3. Initiate Authentication


When the plugin is enabled, accessing wp-login.php triggers the Authentication::onLogin() method through the login_form_login hook. The plugin will automatically redirect you to Auth0's Universal Login.


What happens internally:


    

  1. The plugin checks if authentication is enabled via Plugin::isEnabled() src/Plugin.php174-177
    2. 

  2. The plugin verifies configuration readiness via Plugin::isReady() src/Plugin.php182-219
    3. 

  3. The SDK generates an authorization URL via Auth0::login()
    4. 

  4. A redirect is issued to Auth0's Universal Login src/Actions/Authentication.php549
    5. 



4. Authenticate with Auth0


You will be redirected to Auth0's Universal Login page. This is hosted at:


    

  • Your Auth0 domain: https://YOUR_DOMAIN.auth0.com
    • 

  • Or your custom domain if configured: https://login.yoursite.com
    • 



Complete the authentication process using one of the configured connection types (Username/Password, Social Login, Passwordless, etc.).


5. Callback Processing


After successful authentication, Auth0 redirects back to your WordPress site with authorization parameters:


https://yoursite.com/wp-login.php?code=AUTHORIZATION_CODE&state=STATE_TOKEN



The plugin processes this callback in the following sequence:




Sources: src/Actions/Authentication.php433-551 src/Actions/Authentication.php660-724




Verifying Successful Authentication


Visual Confirmation


Upon successful authentication, you should:


    

  1. Be redirected to your WordPress homepage (/)
    2. 

  2. See your username in the WordPress admin bar at the top of the page
    3. 

  3. Be able to access the WordPress Dashboard
    4. 



Database Verification


The plugin stores the connection between your WordPress user and Auth0 identity in the auth0_accounts table. You can verify this by checking your database:







































ColumnDescriptionExample Value
idAuto-incrementing primary key1
siteNetwork ID (for multisite)1
blogBlog ID (for multisite)1
userWordPress user ID5
auth0Auth0 connection identifier (sub claim)auth0|507f1f77bcf86cd799439011


The auth0 column contains the sub claim from the Auth0 ID token, which uniquely identifies the user's identity provider connection.


Sources: src/Database.php101-119 src/Actions/Authentication.php53-88




User Resolution Process


The Authentication::resolveIdentity() method implements the logic for matching or creating WordPress users based on Auth0 authentication. The following diagram maps the code structure:




Configuration Options Affecting User Resolution





































OptionLocationValuesEffect on First Login
accounts.matchingAuth0 → Options → WordPress Users Managementflexible, strictControls whether users can be matched by verified email
accounts.missingAuth0 → Options → WordPress Users Managementcreate, rejectControls whether new users are created automatically
accounts.default_roleAuth0 → Options → WordPress Users ManagementWordPress role nameRole assigned to newly created users
authentication.pair_sessionsAuth0 → Advanced → Authentication0, 1, 2Affects strict matching bypass for admins


Sources: src/Actions/Authentication.php660-724 src/Actions/Configuration.php41-83




Troubleshooting First Login


Common Issues and Solutions


Issue: "Invalid State" Error


Cause: The wp-login.php page is being cached, causing state parameter mismatches.


Solution:


    

  1. Ensure wp-login.php is excluded from all caching (CDN, WordPress caching plugins)
    2. 

  2. The plugin calls nocache_headers() at src/Actions/Authentication.php472
    3. 

  3. Verify cache configuration allows this header to pass through
    4. 



Issue: Redirect Loop


Cause: Configuration mismatch between Auth0 Application and plugin settings.


Verification:


    

  1. Check that auth0_client options are correct src/Plugin.php274-329
    2. 

  2. Verify Allowed Callback URLs in Auth0 Application exactly match: https://yoursite.com/wp-login.php
    3. 

  3. Check WordPress Address and Site Address URLs match protocol (HTTP vs HTTPS)
    4. 



Issue: Access Denied After Successful Auth0 Login


Cause: User resolution returned null due to configuration settings.


Debug Steps:


    

  1. Check accounts.missing setting - if set to reject, new users cannot be created
    2. 

  2. Check accounts.matching setting - if set to strict, email-only matches are rejected
    3. 

  3. Verify the user's email is verified in Auth0 (email_verified claim must be true)
    4. 



Code Reference: src/Actions/Authentication.php660-724


Issue: Token Exchange Failed


Cause: The exchange() method threw an exception during token exchange.


What Happens:


    

  1. Exception is logged via error_log() src/Actions/Authentication.php495
    2. 

  2. Hook auth0_token_exchange_failed is triggered src/Actions/Authentication.php499
    3. 

  3. Default behavior redirects to homepage src/Actions/Authentication.php553-558
    4. 



Debug Steps:


    

  1. Check PHP error logs for the exception message
    2. 

  2. Verify Client Secret is correct in plugin configuration
    3. 

  3. Verify Auth0 Application settings:

      

    • Token Endpoint Authentication Method: Post
      • 

    • Grant Types: Authorization Code enabled
      • 

    

    4. 



Sources: src/Actions/Authentication.php484-501 src/Actions/Authentication.php553-558




Session Pairing Validation


After successful authentication, the plugin continuously validates session pairing on each request via the Authentication::onInit() method. This ensures WordPress and Auth0 sessions remain synchronized.




This validation ensures that if either the WordPress session or Auth0 session becomes invalid, the user is required to reauthenticate, preventing unauthorized access.


Sources: src/Actions/Authentication.php353-431




Next Steps After Successful Test


Once you have successfully tested the authentication flow:


    

  1. Test Logout: Navigate to WordPress Dashboard and log out to verify Auth0's logout redirect works correctly
    2. 

  2. Test Multiple Logins: Log in with different Auth0 connections (social, database) to verify user resolution works as expected
    3. 

  3. Configure Additional Settings: Explore advanced options in Auth0 → Advanced for session management, cookie settings, and back-channel logout
    4. 

  4. Enable Synchronization: Configure user synchronization settings in Auth0 → Sync to keep WordPress and Auth0 user data in sync
    5. 



For detailed information about synchronization, see User Synchronization. For session configuration options, see Configuration Options.


Sources: src/Actions/Configuration.php194-433 README.md156-168