Authenticatie in Joomla

1. De basis

1.1 Wat is een authenticatie-plugin?

Een authenticatie-plugin beantwoordt een enkele vraag: "zijn deze inloggegevens geldig?" Wanneer een bezoeker het loginformulier verstuurt, controleert Joomla het wachtwoord niet zelf. Het roept een event aan en laat elke ingeschakelde authenticatie-plugin naar de inloggegevens kijken. Elke plugin antwoordt met succes, mislukking, of "dit is niet mijn taak".

Dit ontwerp is de reden dat je inloggen via Google, LDAP, single sign-on of je eigen aangepaste methode aan Joomla kunt toevoegen zonder ooit de core te bewerken. Je schrijft een plugin, hij voegt zich in de keten, en Joomla begint het ook aan hem te vragen.

1.2 Twee aparte plugin-groepen

Joomla levert authenticatie-plugins in twee verschillende groepen, en beginners halen ze vaak door elkaar:

Beide groepen beantwoorden dezelfde eventnaam, maar ze draaien in verschillende applicaties. De authentication-groep bewaakt het loginformulier voor mensen. De api-authentication-groep bewaakt API-aanroepen tussen machines. Het inschakelen van de een heeft geen effect op de ander.

1.3 Het ene event dat ertoe doet

Elke authenticatie-plugin in beide groepen abonneert zich op hetzelfde event: onUserAuthenticate. Joomla roept het aan met de verstuurde inloggegevens, en elke plugin vult een gedeeld response-object in dat ja of nee zegt. Dat ene event is de kern van dit hele artikel.

3. Authentication - Joomla (de standaard)

3.1 Wat het doet

De plugin Authentication - Joomla (plg_authentication_joomla) is degene die de normale gebruikersnaam en het wachtwoord tegen de database controleert. Hij is op elke site ingeschakeld, en dat moet je zo houden. Schakel je hem uit, dan kan niemand meer met een wachtwoord inloggen.

Zijn logica is kort en zorgvuldig. In gewone woorden doet hij dit:

1. Als het wachtwoord leeg is, meteen mislukken.
2. Zoek de gebruikersnaam op in #__users en lees de opgeslagen hash.
3. Controleer het getypte wachtwoord tegen die hash.
4. Match    → STATUS_SUCCESS, vul email/naam/taal in.
   Geen match → STATUS_FAILURE.

3.2 Hoe wachtwoorden worden opgeslagen

Joomla slaat nooit een wachtwoord in platte tekst op. Het bewaart een gesalte bcrypt-hash in de kolom password van #__users, aangemaakt met de eigen wachtwoord-hashfuncties van PHP. Een opgeslagen waarde ziet er zo uit:

$2y$10$Ux3...   (algoritme, kosten, salt en hash in een string)

De plugin controleert met UserHelper::verifyPassword(), die ook opnieuw hasht bij het inloggen. Als de opgeslagen hash een ouder algoritme of lagere kosten gebruikt dan de huidige instelling, herschrijft Joomla hem stilletjes met de sterkere versie terwijl je inlogt. Je inloggegevens worden in de loop van de tijd veiliger zonder dat iemand iets hoeft te doen.

3.3 Een klein maar slim beveiligingsdetail

Wanneer de gebruikersnaam niet bestaat, voert de plugin toch een wachtwoord-hash uit voordat hij mislukking teruggeeft. Dit lijkt verspilling, maar het is opzettelijk. Het zorgt ervoor dat een login met een echt-maar-fout wachtwoord even lang duurt als een login met een gebruikersnaam die niet bestaat. Een aanvaller kan de reactietijd niet meten om te ontdekken welke gebruikersnamen geldig zijn. Dit heet timing-attack-mitigatie.

3.4 Hij stopt de keten bij succes

Wanneer deze plugin slaagt, roept hij stopPropagation() aan op het event. Dat vertelt Joomla de overige authenticatie-plugins niet meer lastig te vallen, want het antwoord is al een duidelijk ja. Een mislukking stopt de keten niet, dus een latere plugin (bijvoorbeeld LDAP) krijgt nog steeds zijn beurt.

5. Authentication - LDAP (externe directory)

5.1 Wanneer je het nodig hebt

De plugin Authentication - LDAP (plg_authentication_ldap) controleert inloggegevens tegen een externe LDAP- of Active Directory-server in plaats van de Joomla-database. Organisaties gebruiken het zodat medewerkers in Joomla inloggen met hetzelfde account dat ze voor e-mail en het netwerk gebruiken. Het is standaard uitgeschakeld, omdat de meeste sites het niet nodig hebben.

5.2 Twee manieren om te verbinden

De plugin biedt twee strategieen via zijn parameter auth_method:

Een geslaagde bind is het bewijs: als de LDAP-server de DN en het wachtwoord van de gebruiker accepteert, zijn de inloggegevens geldig en geeft de plugin STATUS_SUCCESS terug.

5.3 Belangrijke parameters

Gebruik in productie altijd tls of ssl. Een gewone LDAP-verbinding stuurt het wachtwoord onversleuteld over het netwerk.

7. API Authentication - Basic

7.1 Wat het doet

De plugin Web Services Basic (plg_api-authentication_basic) laat een client bij elk API-verzoek een gebruikersnaam en wachtwoord meesturen, met standaard HTTP Basic-authenticatie. Joomla leest de inloggegevens, controleert ze tegen de tabel #__users met dezelfde aanroep UserHelper::verifyPassword() die het loginformulier gebruikt, en geeft succes of mislukking terug.

curl -u mijngebruikersnaam:mijnwachtwoord \
     https://example.test/api/index.php/v1/users

7.2 Gebruik het met zorg

Basic-authenticatie stuurt het echte accountwachtwoord bij elk verzoek mee. Dat heeft twee gevolgen. Ten eerste mag je het alleen over HTTPS gebruiken, anders reist het wachtwoord onversleuteld mee. Ten tweede is een script dat een werkend wachtwoord opslaat een serieus risico als het lekt. Voor de meeste integraties is de token-plugin de veiligere keuze, omdat een token kan worden ingetrokken zonder het wachtwoord van de gebruiker te wijzigen.

9. Onder de motorkap (ontwikkelaarsblik)

9.1 De betrokken tabellen

9.2 De authenticatieservice

De plugins draaien zichzelf niet. Een kleine serviceklasse, Joomla\CMS\Authentication\Authentication, stuurt de hele keten aan. Wanneer het loginformulier (of je eigen code) hem vraagt te authenticeren, laadt het de ingeschakelde plugins, roept het event aan, verzamelt elke response, en geeft het eindoordeel terug:

use Joomla\CMS\Authentication\Authentication;

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

if ($response->status === Authentication::STATUS_SUCCESS) {
    // de inloggegevens zijn geldig
}

Je roept dit zelden zelf aan, omdat $app->login() het voor je doet. Maar weten dat deze klasse bestaat verklaart waar het event onUserAuthenticate vandaan komt en waarom de statusconstanten erop leven. Elke ingeschakelde plugin is een strategie die de service om de beurt raadpleegt.

9.3 De vorm van een plugin

Een moderne authenticatie-plugin is een kleine namespaced klasse. Hij declareert het event dat hij beantwoordt en doet zijn werk in een bijbehorende methode:

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;
        }
    }
}

Dit zelfde patroon is hoe echte single-sign-on-integraties worden gebouwd. Een login via OAuth 2.0, SAML, Keycloak, Microsoft Entra ID of Okta is gewoon een authenticatie-plugin die de inloggegevens controleert tegen een externe identity provider in plaats van #__users, en daarna hetzelfde response-object invult. De core verandert nooit.

Wanneer een plugin een gebruiker vindt, laadt hij het volledige account met de moderne UserFactoryInterface in plaats van het oude statische Factory::getUser(). Binnen een plugin bereik je het via $this->getUserFactory()->loadUserById($id):

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

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

De factory wordt geinjecteerd via de service provider van de plugin, zodat de code dependency injection ondersteunt, testbaar blijft en statische aanroepen vermijdt. Dit is de standaardmanier om een gebruiker te laden in Joomla 6.

9.4 Waarom je bij een mislukking niet moet blokkeren

Een nette plugin stelt STATUS_SUCCESS in en roept stopPropagation() alleen aan wanneer hij zeker is. Bij een mislukking moet hij de deur openlaten voor de volgende plugin door STATUS_FAILURE in te stellen (of STATUS_UNKNOWN als de inloggegevens simpelweg niet zijn zaak zijn) en stilletjes terug te keren. Zo bestaan de Joomla-, Cookie- en LDAP-plugins naast elkaar: elk probeert om de beurt, en het eerste zekere ja wint.

9.5 De mapindeling

plugins/authentication/joomla/
├─ services/provider.php              (DI-container-bedrading)
├─ src/Extension/Joomla.php           (de plugin-klasse)
└─ joomla.xml                         (manifest, parameters)

De api-authentication-plugins volgen dezelfde indeling onder plugins/api-authentication/. Het enige echte verschil is de applicatie waarin ze draaien.

11. Veelvoorkomende fouten en valkuilen

11.1 De plugin Authentication - Joomla uitschakelen

Symptoom: niemand kan ergens met een gebruikersnaam en wachtwoord inloggen.

Oplossing: schakel de plugin Authentication - Joomla opnieuw in. Als je buiten de backend bent gesloten, zet dan enabled = 1 voor hem rechtstreeks in de tabel #__extensions.

11.2 Onthoud mij werkt nooit

Symptoom: het vinkje Onthoud mij verschijnt op de frontend-login, maar niemand blijft ingelogd.

Oplossing: schakel de plugin Authentication - Cookie in. Zonder hem doet het vinkje niets. Onthoud dat het opzettelijk nooit voor de backend geldt.

11.3 De twee plugin-groepen door elkaar halen

Symptoom: je schakelt een plugin in om API-toegang te repareren, maar in plaats daarvan verandert de website-login, of andersom.

Oplossing: de authentication-groep bedient het loginformulier; de api-authentication-groep bedient de Web Services API. Schakel de plugin in de groep in die bij het probleem hoort. Om precies te zien welke plugins in beide groepen tegelijk aanstaan, bevraag je de database:

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

11.4 De API-token geeft 401 terwijl hij klopt

Symptoom: een geldige token wordt geweigerd met een niet-geautoriseerd-fout.

Oplossing: controleer drie dingen. De plugin API Authentication - Token moet ingeschakeld zijn, de gebruiker moet in een groep zitten die in allowedUserGroups staat, en het account mag niet geblokkeerd of in afwachting van activatie zijn.

11.5 LDAP over een onversleutelde verbinding

Symptoom: LDAP-login werkt, maar wachtwoorden reizen onversleuteld over het netwerk.

Oplossing: zet de parameter encryption op tls of ssl en bevestig dat het certificaat van de server vertrouwd is. Draai LDAP in productie nooit met encryption op none.

11.6 Basic Auth gebruiken waar een token thuishoort

Symptoom: een integratiescript slaat een echt accountwachtwoord op om de API aan te roepen.

Oplossing: stap over op de token-plugin. Een token kan op zichzelf worden ingetrokken zonder een wachtwoordwijziging af te dwingen, en hij beperkt de schade als het script lekt.

13. In het kort

GROEPEN         authentication       loginformulier (HTML, sessie)
                api-authentication   Web Services API (REST, geen sessie)

EVENT           onUserAuthenticate   beantwoord door elke auth-plugin

LOGIN-PLUGINS   Joomla   wachtwoordcontrole tegen #__users (aan laten)
                Cookie   Onthoud mij, alleen frontend, #__user_keys
                LDAP     externe directory, bind of search, gebruik TLS

API-PLUGINS     Token    Authorization: Bearer / X-Joomla-Token header
                Basic    curl -u gebruiker:wachtwoord  (alleen HTTPS)

STATUS          STATUS_SUCCESS  geldig, ga verder
                STATUS_FAILURE  foute inloggegevens
                STATUS_DENIED   geblokkeerd / inactief / reset vereist
                STATUS_UNKNOWN  "niet mijn taak", probeer de volgende plugin

TABELLEN        #__users          gebruikersnaam + bcrypt-wachtwoordhash
                #__user_keys      Onthoud-mij-token + serie
                #__user_profiles  API-tokenzaadje (joomlatoken.token)
                #__extensions     waar elke plugin is ingeschakeld

API-SETUP       schakel User - Joomla API Token + API Auth Token-plugin in
                genereer token op het gebruikersprofiel, kopieer hem een keer
                verbreed allowedUserGroups voorzichtig

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