Authentication in Joomla

1. The Basics

1.1 What is an Authentication Plugin?

An authentication plugin answers one question: "are these credentials valid?" When a visitor submits the login form, Joomla does not check the password itself. It fires an event and lets every enabled authentication plugin look at the credentials. Each plugin replies with success, failure, or "this is not my job".

This design is the reason you can add Google login, LDAP, single sign-on, or your own custom method to Joomla without ever editing the core. You write a plugin, it joins the chain, and Joomla starts asking it too.

1.2 Two Separate Plugin Groups

Joomla ships authentication plugins in two different groups, and beginners often confuse them:

Both groups answer the same event name, but they run in different applications. The authentication group guards the human login form. The api-authentication group guards machine-to-machine API calls. Enabling one has no effect on the other.

1.3 The One Event That Matters

Every authentication plugin in both groups subscribes to the same event: onUserAuthenticate. Joomla fires it with the submitted credentials, and each plugin fills in a shared response object that says yes or no. That single event is the heart of this whole article.

3. Authentication - Joomla (the Default)

3.1 What It Does

The Authentication - Joomla plugin (plg_authentication_joomla) is the one that checks the normal username and password against the database. It is enabled on every site, and you should keep it that way. Disable it and nobody can log in with a password again.

Its logic is short and careful. In plain terms, it does this:

1. If the password is empty, fail immediately.
2. Look up the username in #__users and read the stored hash.
3. Verify the typed password against that hash.
4. Match    → STATUS_SUCCESS, fill in email/name/language.
   No match → STATUS_FAILURE.

3.2 How Passwords Are Stored

Joomla never stores a plain-text password. It saves a salted bcrypt hash in the password column of #__users, created with PHP's native password hashing functions. A stored value looks like this:

$2y$10$Ux3...   (algorithm, cost, salt, and hash in one string)

The plugin verifies with UserHelper::verifyPassword(), which also re-hashes on login. If the stored hash uses an older algorithm or a lower cost than the current setting, Joomla transparently rewrites it with the stronger version while you log in. Your credentials get safer over time without anyone doing a thing.

3.3 A Small but Clever Security Detail

When the username does not exist, the plugin still runs a password hash before returning failure. This looks wasteful, but it is deliberate. It makes a login for a real-but-wrong password take the same time as a login for a username that does not exist. An attacker cannot measure the response time to learn which usernames are valid. This is called timing-attack mitigation.

3.4 It Stops the Chain on Success

When this plugin succeeds, it calls stopPropagation() on the event. That tells Joomla not to bother the remaining authentication plugins, because the answer is already a clear yes. A failure does not stop the chain, so a later plugin (for example LDAP) still gets its turn.

5. Authentication - LDAP (External Directory)

5.1 When You Need It

The Authentication - LDAP plugin (plg_authentication_ldap) checks credentials against an external LDAP or Active Directory server instead of the Joomla database. Organisations use it so staff log in to Joomla with the same account they use for email and the network. It is disabled by default, because most sites do not need it.

5.2 Two Ways to Connect

The plugin offers two strategies through its auth_method parameter:

A successful bind is the proof: if the LDAP server accepts the user's DN and password, the credentials are valid, and the plugin returns STATUS_SUCCESS.

5.3 Key Parameters

Always use tls or ssl in production. A plain LDAP connection sends the password across the network unencrypted.

7. API Authentication - Basic

7.1 What It Does

The Web Services Basic plugin (plg_api-authentication_basic) lets a client send a username and password with each API request, using standard HTTP Basic authentication. Joomla reads the credentials, checks them against the #__users table with the same UserHelper::verifyPassword() call the login form uses, and returns success or failure.

curl -u myusername:mypassword \
     https://example.test/api/index.php/v1/users

7.2 Use It With Care

Basic authentication sends the real account password on every request. That has two consequences. First, you must only ever use it over HTTPS, or the password travels in the clear. Second, a script that stores a working password is a serious liability if it leaks. For most integrations the token plugin is the safer choice, because a token can be revoked without changing the user's password.

9. Under the Hood (Developer View)

9.1 The Tables Involved

9.2 The Authentication Service

The plugins do not run themselves. A small service class, Joomla\CMS\Authentication\Authentication, drives the whole chain. When the login form (or your own code) asks it to authenticate, it loads the enabled plugins, fires the event, collects every response, and returns the final verdict:

use Joomla\CMS\Authentication\Authentication;

$authentication = Authentication::getInstance();
$response       = $authentication->authenticate($credentials, $options);

if ($response->status === Authentication::STATUS_SUCCESS) {
    // the credentials are valid
}

You rarely call this yourself, because $app->login() does it for you. But knowing the class exists explains where the onUserAuthenticate event comes from and why the status constants live on it. Each enabled plugin is one strategy the service consults in turn.

9.3 The Shape of a Plugin

A modern authentication plugin is a small namespaced class. It declares the event it answers and does its work in a matching method:

namespace Joomla\Plugin\Authentication\Example\Extension;

use Joomla\CMS\Authentication\Authentication;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;

final class Example extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onUserAuthenticate' => 'onUserAuthenticate'];
    }

    public function onUserAuthenticate($event): void
    {
        $credentials = $event->getArgument('credentials');
        $response    = $event->getAuthenticationResponse();

        if ($this->isValid($credentials)) {
            $response->status = Authentication::STATUS_SUCCESS;
            $response->email  = '...';
            $event->stopPropagation();
        } else {
            $response->status = Authentication::STATUS_FAILURE;
        }
    }
}

This same pattern is how real single sign-on integrations are built. An OAuth 2.0, SAML, Keycloak, Microsoft Entra ID, or Okta login is just an authentication plugin that checks the credentials against an external identity provider instead of #__users, then fills in the same response object. The core never changes.

When a plugin matches a user, it loads the full account with the modern UserFactoryInterface rather than the old static Factory::getUser(). Inside a plugin you reach it through $this->getUserFactory()->loadUserById($id):

$user = $this->getUserFactory()->loadUserById($id);

$response->email    = $user->email;
$response->fullname = $user->name;

The factory is injected through the plugin's service provider, so the code supports dependency injection, stays testable, and avoids static calls. This is the standard way to load a user in Joomla 6.

9.4 Why You Should Not Block on Failure

A well-behaved plugin sets STATUS_SUCCESS and calls stopPropagation() only when it is sure. On failure it should leave the door open for the next plugin by setting STATUS_FAILURE (or STATUS_UNKNOWN if the credentials are simply not its concern) and returning quietly. This is how the Joomla, Cookie, and LDAP plugins live together: each tries in turn, and the first confident yes wins.

9.5 The Folder Layout

plugins/authentication/joomla/
├─ services/provider.php              (DI container wiring)
├─ src/Extension/Joomla.php           (the plugin class)
└─ joomla.xml                         (manifest, parameters)

The api-authentication plugins follow the same layout under plugins/api-authentication/. The only real difference is the application they run in.

11. Common Mistakes and Pitfalls

11.1 Disabling the Authentication - Joomla Plugin

Symptom: nobody can log in with a username and password, anywhere.

Fix: re-enable the Authentication - Joomla plugin. If you are locked out of the backend, set enabled = 1 for it directly in the #__extensions table.

11.2 Remember Me Never Works

Symptom: the Remember Me checkbox shows on the frontend login, but nobody stays logged in.

Fix: enable the Authentication - Cookie plugin. The checkbox does nothing without it. Remember that it never applies to the backend by design.

11.3 Confusing the Two Plugin Groups

Symptom: you enable a plugin to fix API access, but the website login changes instead, or the other way round.

Fix: the authentication group serves the login form; the api-authentication group serves the Web Services API. Enable the plugin in the group that matches the problem. To see exactly which plugins are on in both groups at once, query the database:

SELECT name, folder, enabled FROM #__extensions
WHERE folder IN ('authentication', 'api-authentication');

11.4 The API Token Returns 401 Even Though It Is Correct

Symptom: a valid token is rejected with an unauthorised error.

Fix: check three things. The API Authentication - Token plugin must be enabled, the user must belong to a group listed in allowedUserGroups, and the account must not be blocked or pending activation.

11.5 LDAP Over a Plain Connection

Symptom: LDAP login works, but passwords travel unencrypted across the network.

Fix: set the encryption parameter to tls or ssl and confirm the server's certificate is trusted. Never run production LDAP with encryption set to none.

11.6 Using Basic Auth Where a Token Belongs

Symptom: an integration script stores a real account password to call the API.

Fix: switch to the token plugin. A token can be revoked on its own without forcing a password change, and it limits the damage if the script leaks.

13. Quick Reference

GROUPS          authentication       login form (HTML, session)
                api-authentication   Web Services API (REST, no session)

EVENT           onUserAuthenticate   answered by every auth plugin

LOGIN PLUGINS   Joomla   password check against #__users (keep enabled)
                Cookie   Remember Me, frontend only, #__user_keys
                LDAP     external directory, bind or search, use TLS

API PLUGINS     Token    Authorization: Bearer / X-Joomla-Token header
                Basic    curl -u user:pass  (HTTPS only)

STATUS          STATUS_SUCCESS  valid, continue
                STATUS_FAILURE  wrong credentials
                STATUS_DENIED   blocked / inactive / reset required
                STATUS_UNKNOWN  "not my job", try the next plugin

TABLES          #__users          username + bcrypt password hash
                #__user_keys      Remember Me token + series
                #__user_profiles  API token seed (joomlatoken.token)
                #__extensions     where each plugin is enabled

API SETUP       enable User - Joomla API Token + API Auth Token plugin
                generate token on the user profile, copy it once
                widen allowedUserGroups carefully

DIAGNOSE        SELECT name, folder, enabled FROM #__extensions
                WHERE folder IN ('authentication','api-authentication');