# Joomla 6 Keycloak OIDC SSO plugin (`plg_system_keycloak`)

Native OIDC SSO against Keycloak for Joomla 6, with RBAC group
mapping and an env-toggleable local-form fallback at
`/administrator?fallback=local` (Modus 3 per requirement 013).

## Build

The plugin's PHP dependencies (`jumbojett/openid-connect-php`) are
vendored at deploy time inside the Joomla container. Composer is
baked into the role's custom image by `roles/web-app-joomla/files/Dockerfile`.
The role-side `tasks/08_oidc_plugin.yml` copies the plugin source
into the container, runs `composer install --no-dev`, and installs
the plugin via the Joomla CLI:

```
php cli/joomla.php extension:install --path=/tmp/plg_system_keycloak
```

The repository working tree stays clean (no `vendor/` checked in)
and the host MUST NOT need a PHP or Composer installation.

## Configuration (env)

The plugin reads its runtime config from the Joomla container's
environment, so the same plugin code works against any Keycloak
realm without manual reconfiguration through the Joomla admin UI.

| Variable                       | Purpose                                                                                                | Default                                          |
|--------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------------------|
| `JOOMLA_OIDC_ISSUER_URL`       | Keycloak realm issuer URL.                                                                             | (required)                                       |
| `JOOMLA_OIDC_CLIENT_ID`        | OIDC client ID in the realm.                                                                           | (required)                                       |
| `JOOMLA_OIDC_CLIENT_SECRET`    | OIDC client secret.                                                                                    | (required)                                       |
| `JOOMLA_OIDC_REDIRECT_URI`     | Callback URL `https://<joomla>/index.php?option=keycloak&task=callback`.                               | (required)                                       |
| `JOOMLA_OIDC_FALLBACK_ENABLED` | If `false`, the local-form fallback at `/administrator?fallback=local` is disabled (Modus 1 in effect). | `true`                                           |
| `JOOMLA_OIDC_GROUP_ADMIN`      | Keycloak group path that maps onto Joomla's `Super Users` (id 8).                                      | `/roles/web-app-joomla/administrator`            |
| `JOOMLA_OIDC_GROUP_EDITOR`     | Keycloak group path that maps onto Joomla's `Editor` (id 4).                                           | `/roles/web-app-joomla/editor`                   |
| `JOOMLA_OIDC_GROUP_USER`       | Keycloak group path that maps onto Joomla's `Registered` (id 2).                                       | `/roles/web-app-joomla`                          |
| `JOOMLA_OIDC_END_SESSION_URL`  | RP-initiated logout endpoint at Keycloak.                                                              | `<issuer>/protocol/openid-connect/logout`        |

A user whose Keycloak `groups` claim matches none of the three
mapped paths is refused. This is the documented RBAC gate per
requirement 013. The Joomla account is created on first login if it
does not already exist. Subsequent logins re-sync the group
memberships from Keycloak.

## Routes the plugin claims

| URL                                       | Purpose                                  |
|-------------------------------------------|------------------------------------------|
| `/index.php?option=keycloak&task=login`   | Start the OIDC authorization-code flow.  |
| `/index.php?option=keycloak&task=callback`| OIDC callback endpoint.                  |
| `/index.php?option=keycloak&task=logout`  | RP-initiated logout against Keycloak.    |
| `/index.php?fallback=local`               | Local Joomla form-login (Modus 3 hatch). |

## Watch points

- The plugin trusts the Keycloak-issued ID token. The
  `jumbojett/openid-connect-php` library validates the JWT signature
  against the realm's JWKS, so the issuer URL MUST be reachable
  from the Joomla container at the time the user authenticates.
- The plugin lives in the `system` plugin group so it can intercept
  every request via `onAfterInitialise`. It MUST run BEFORE the
  Joomla local form-login plugin in the system event chain so the
  redirect short-circuits any local-account authentication attempt.
  System plugins are ordered alphabetically. `keycloak` ranks
  before `users`, which is the typical local-form gate.
- The local-form fallback at `?fallback=local` is documented as an
  emergency hatch. For high-security deployments, set
  `JOOMLA_OIDC_FALLBACK_ENABLED=false` to disable it (Modus 1
  effective).