Skip to content

Joomla

Jump to bottom
Teo Elmfeldt edited this page Jun 7, 2026 · 1 revision

Joomla

This guide covers adding ScoutID login to a Joomla 5 site using the HQ OIDC plugin — a lightweight, free OIDC plugin built specifically for Keycloak-based identity providers.

Before you start, make sure you have requested a client. Specify that you need a confidential OIDC client for Joomla and provide your redirect URI (see Step 2 below). You will receive a client ID and client secret.

Step 1 — Install the plugin

  1. Download the latest plg_system_hqoidc-x.y.z.zip from the HQ OIDC releases page
  2. In the Joomla admin panel, go to System → Install → Extensions and upload the zip
  3. Go to System → Plugins, find System - HQ OIDC, and enable it

Once installed, the plugin registers itself with Joomla's built-in updater and will notify you of new releases automatically.

Step 2 — Configure the plugin

In Joomla admin → System → Plugins → System - HQ OIDC, set the following:

Setting Value
Issuer URL https://dev.id.scouterna.se/realms/scoutnet
Client ID (from ScoutID)
Client Secret (from ScoutID)
Match field Username (recommended — matches preferred_username)
Provisioning Match only or Auto-create — see note below
Single Logout Yes (recommended)

Provisioning modes:

  • Match only — users must already exist in Joomla with a matching username or email. Safer default.
  • Auto-create — Joomla accounts are automatically created on first login. Auto-created users receive the default Joomla group.

Step 3 — Register your redirect URI

When requesting your client, provide the following as your redirect URI:

https://your-joomla-site.example/index.php?option=hqoidc&task=callback

Also provide your post-logout redirect URI if you want single logout to redirect back to a specific page:

https://your-joomla-site.example/

Step 4 — Add a login button

The plugin does not include a login button — you add a link wherever it fits your site's design:

<a href="/index.php?option=hqoidc&task=login">Sign in with ScoutID</a>

To send the user back to a specific page after login, add a return parameter:

<a href="/index.php?option=hqoidc&task=login&return=/members">Sign in with ScoutID</a>

Logout link (triggers single logout from ScoutID as well, if enabled):

<a href="/index.php?option=hqoidc&task=logout">Sign out</a>

Troubleshooting

Enable Debug log in the plugin settings. Log entries are written to hqoidc.log in Joomla's log folder (configured under Global Configuration → System → Path to Log Folder, typically administrator/logs/).

Common issues:

  • "No matching Joomla account was found" — provisioning is set to match_only and no Joomla user matches the incoming username or email. Either create the Joomla user manually with the correct username, or switch provisioning to auto-create.
  • "Unable to determine state" — the Joomla session was reset between the login start and callback. Check that cookies are not blocked and that the site is served over HTTPS.

Clone this wiki locally