Admin

name	type	size	perms	modified	actions
[parent directory]
azure-env-variables.md	file	11,032 B	0664	2026-09-06 02:16:10	edit
azure-pipelines.md	file	12,541 B	0664	2026-08-26 04:59:14	edit
keycloak-cms-web.md	file	16,862 B	0664	2026-09-02 13:46:30	edit
savings-pockets.md	file	43,592 B	0664	2026-09-06 03:11:29	edit

editing: keycloak-cms-web.md

# cms-web on Keycloak

cms-web signs in with Keycloak (Authorization Code + PKCE) and calls **both**
main-api and savings-api with that one access token. This is the runbook for the
parts that live outside the codebase, plus what to check on the way in.

## What changed in code

**main-api** — can now verify a Keycloak access token, which it previously could
not do at all.

| Piece | Path |
| --- | --- |
| JWKS verification (signature, `typ`, `aud`/`azp`, `iss`, expiry) | `app/Services/Keycloak/KeycloakTokenVerifier.php` |
| Verifier contract + claims DTO | `app/Contracts/AccessTokenVerifier.php`, `app/DTOs/AuthenticatedUser.php` |
| The `keycloak` guard (subject → `users` row) | `app/Auth/KeycloakUserResolver.php`, registered in `app/Providers/AuthServiceProvider.php` |
| Guard declaration | `config/auth.php` |
| Verification settings | `config/keycloak.php` |
| Route groups now `auth:keycloak,api` | `routes/api.php` |
| Admin decision: realm role first, DB fallback | `app/Auth/AdminAccess.php`, `app/Support/VerifiedIdentity.php` |
| Admin/active checks read the guard user instead of `api_token` | `app/Http/Middleware/CheckAdminPermission.php`, `CheckUserActive.php` |
| Admin gates enabled on 57 routes | `routes/api.php` |
| Signature verification added to the main-web middlewares | `app/Http/Middleware/CheckWebApiUserActive.php`, `CheckWebApiAdminPermission.php` |
| Admin linking command | `app/Console/Commands/LinkAdminToKeycloak.php` |

`auth:keycloak,api` accepts **either** credential, so reseller-web, shop-web and
mobile-app keep working on their opaque `users.api_token` while cms-web moves.
Drop `api` from those groups once nothing sends one.

**cms-web** — password login and the `localStorage` token are gone.

| Piece | Path |
| --- | --- |
| Keycloak adapter + shared token accessor | `src/lib/keycloak.ts` |
| Session owner (Keycloak init + profile query) | `src/context/AuthContext.tsx` |
| Profile fetch / distribution logout | `src/services/auth.ts` |
| SSO login screen | `src/pages/LoginPage.tsx` |
| Token on outbound requests | `src/lib/axios.ts`, `src/lib/axios-distribution.ts` |
| Silent SSO iframe target | `public/silent-check-sso.html` |

`src/lib/auth-storage.ts` and `src/services/auth-distribution.ts` were deleted.
Tokens now live in memory only.

## How admin access is decided

Two sources, in order, in [AdminAccess](../apps/main-api/app/Auth/AdminAccess.php):

1. **The realm role on the verified token** — `KEYCLOAK_ADMIN_ROLE`, default
   `admin`. Part of what the signature covers, so it costs no query and is the
   same role savings-api's `EnsureKeycloakAdmin` gates on.
2. **`users.role` / `users.roles`** — the fallback. Needed because the realm
   grants `admin` to a single account today while the `users` table has had
   admins for years, and because a caller on the legacy opaque `api_token`
   carries no claims at all.

It is an OR, and a migration posture rather than the end state. It is strictly no
weaker than what main-api enforced before (the DB check was the only check), and
it honours the realm immediately. **Every fallback logs
`Admin access granted from the database fallback`** — when those stop appearing
after `keycloak:link-admin --all --commit --assign-role`, drop step 2 and the
check becomes savings-api's exactly.

cms-web mirrors the same OR (`ADMIN_REALM_ROLE ||  profile.roles`) so the UI and
the API cannot disagree, with `VITE_KEYCLOAK_ADMIN_ROLE` matching the API's
`KEYCLOAK_ADMIN_ROLE`.

### Page permissions are a restriction, not a grant

`users.permissions` is honoured exactly when non-empty, and an empty list means
"no restriction recorded" — so an admin gets every page until somebody
deliberately narrows them. Resolved once in `AuthContext` via
`effectivePermissions()` (`src/lib/permissions.ts`), so ProtectedRoute, the
Sidebar and the login redirect cannot disagree.

Before this, admin access and page access disagreed in a way that read as a
broken login: main-api served an admin whose `permissions` column was empty
while cms-web could not name one page to route them to, so it re-rendered the
sign-in card. **Every admin in the dev database is in exactly that state** — all
5 of them — which is why the empty case had to mean "unrestricted" rather than
"nothing".

Narrowing an admin deliberately still works and is unchanged:
`php artisan cms:grant-admin <email> --permissions=vouchers,settings --commit`.

Verified by execution, not just types:

| `users.permissions` | admin? | keys in force | lands on |
| --- | --- | --- | --- |
| `[]` | yes | 26 (all) | `/dashboard` |
| `null` | yes | 26 (all) | `/dashboard` |
| `['vouchers']` | yes | 1 | `/vouchers` (settings closed) |
| `[]` | no | 0 | nowhere — no session |

### Gates are now on

`check_admin_permission` was commented out on every route group; it is applied
now, covering 57 routes across users, orders, entrusted-orders, products,
vouchers, referrals, settings, banners and `PUT /configs/{id}`.

`/api/users/auth/*` is deliberately **not** gated — it is the profile endpoint
every client uses, cms-web's session check included. Public and reseller flows
(`POST /api/orders`, `/api/vouchers/check/{code}`, `/api/users/check_referral_all`)
sit outside the authenticated group and are untouched.

Audited before enabling: only cms-legacy and cms-web call routes in those groups.
reseller-web, shop-web and main-web use the public routes; mobile-app only calls
`/status`.

**A non-admin now gets `403`, where the old middleware answered `401`.** That is
the correct code and what cms-web expects, but cms-legacy's error handling was
written against `401` — worth a look if it starts showing raw errors instead of
redirecting.

## Keycloak realm setup

Nothing below can be done from the repo — it is console work.

1. **Create a public client for cms-web** (e.g. `qurbanplus-cms-web-dev`):
   - Client authentication: **off** (public — a browser client must hold no secret)
   - Standard flow: on. Direct access grants: off.
   - Valid redirect URIs: the CMS origin(s), e.g. `http://localhost:5200/*`,
     `https://cms.teamqurbanplus.id/*`
   - Web origins: the same origins (not `*`)
   - Valid post logout redirect URIs: the same origins
2. **Grant the `admin` realm role** to each staff account that should reach the
   CMS. savings-api's `EnsureKeycloakAdmin` already gates on exactly this role
   name, and main-api's `users.roles` uses the same word.
3. **Add an audience mapper** on the cms-web client naming *both* APIs:
   Client scopes → `<client>-dedicated` → Add mapper → By configuration →
   Audience → Included client audience → the API's client id. Repeat for the
   second API.

Until this exists, both APIs fall back to matching `azp`, which says which
   client *minted* the token rather than which API it is *for*. Once every
   environment has the mapper, set `KEYCLOAK_REQUIRE_AUDIENCE=true` on both APIs
   — and verify a fresh token carries them in `aud` **before** flipping it, since
   turning it on early rejects every token.

## Environment

**main-api**

```
KEYCLOAK_BASE_URL=…                  # already set — KeycloakService's host, unchanged
KEYCLOAK_REALM=…                     # already set
KEYCLOAK_ISSUER_BASE_URL=https://sso.muhajirproject.com
KEYCLOAK_ACCEPTED_CLIENT_IDS=qurbanplus-client-dev,qurbanplus-v2
KEYCLOAK_REQUIRE_AUDIENCE=false
KEYCLOAK_ADMIN_ROLE=admin
```

**Why the issuer host is separate.** This realm answers on *two* hostnames —
`sso.muhajirproject.com` and `dev.sso.muhajirproject.com` — with identical
signing keys, and it stamps `iss` with whichever one the client used. main-api's
`KEYCLOAK_BASE_URL` has historically pointed at `dev.sso.`, while savings-api,
main-app and cms-web all use `sso.`, so verifying against `KEYCLOAK_BASE_URL`
would reject every SPA token with `token issuer mismatch`. `KEYCLOAK_ISSUER_BASE_URL`
governs verification only (issuer comparison + JWKS fetch) and defaults to
`KEYCLOAK_BASE_URL`; `KeycloakService`'s admin REST and password-grant calls keep
using `KEYCLOAK_BASE_URL` untouched. **Keep it equal to savings-api's
`KEYCLOAK_BASE_URL`.**

`KEYCLOAK_ACCEPTED_CLIENT_IDS` defaults to `KEYCLOAK_CLIENT_ID` alone, so an
environment that is not told about the SPAs will reject their tokens. Empty in
production means **every** token is rejected — deliberately, because the
alternative is accepting any client in the realm.

**savings-api** — append the cms-web client to the existing list:

```
KEYCLOAK_CLIENT_ID=qurbanplus-client-dev,qurbanplus-main-app-dev,qurbanplus-cms-web-dev
```

**cms-web**

```
VITE_KEYCLOAK_URL=https://dev.sso.muhajirproject.com
VITE_KEYCLOAK_REALM=muhajir-dev
VITE_KEYCLOAK_CLIENT_ID=qurbanplus-cms-web-dev
VITE_KEYCLOAK_ADMIN_ROLE=admin
```

With any of the three missing the app still renders and says so, and login is
disabled — it does not break on load.

## Link the admins

An admin whose `users.keycloak_id` is null holds a valid token that main-api
cannot resolve to anybody: 401 on every request. Report first, then commit:

```bash
php artisan keycloak:link-admin --all
php artisan keycloak:link-admin --all --commit
```

Single account, also granting the realm role:

```bash
php artisan keycloak:link-admin admin@example.com --commit --assign-role
```

The command refuses to link when Keycloak has no account with exactly that
address, or when another `users` row already holds the subject — two rows sharing
one subject is a state the guard refuses to authenticate, so creating it would
lock both accounts out rather than one.

## Cutover order

1. main-api deployed with the verifier, `KEYCLOAK_ACCEPTED_CLIENT_IDS` set. No
   client behaviour changes yet — `auth:keycloak,api` still accepts old tokens.
2. Realm client + roles + mappers in place.
3. `keycloak:link-admin --all --commit`.
4. cms-web deployed with its `VITE_KEYCLOAK_*` values.

Rolling back step 4 alone is enough to restore password login **only if** the
previous cms-web build is redeployed; main-api needs no rollback, since it still
accepts both credentials.

## Bootstrapping an admin

```bash
php artisan cms:grant-admin <email>            # dry run
php artisan cms:grant-admin <email> --commit   # adds `admin` to users.roles + all 26 permission keys
```

Only needed to give someone DB-side admin (which cms-legacy and the legacy
`api_token` clients still read). An account holding the Keycloak realm role
alone now reaches the CMS without it, since an empty `permissions` column no
longer restricts.

## Middleware aliases live in bootstrap/app.php

`app/Http/Kernel.php` still declares a `$routeMiddleware` array and **nothing
reads it** — Laravel 11 builds the kernel from `bootstrap/app.php`, so the class
is dead code from the upgrade. An alias named only there does not exist, and the
first request to a route using it is a 500 (`Target class [alias] does not
exist`).

Two routes were in that state:

- `check_admin_permission` — every admin route, the moment the gates were enabled.
- `check_hook_token` — **`POST /api/hook/payment` has been 500ing on every call
  since the Laravel 11 upgrade.** The payment gateway's callback could not have
  been processed by any environment running that code.

Both aliases are registered in `bootstrap/app.php` now, and `Kernel.php` carries
a header saying it is inert. One thing is still lost from it: the `api` group
there lists `throttle:60,1`, which is **not** applied — API rate limiting is
currently off. Re-add it in `bootstrap/app.php` if it is wanted; left alone here
because switching rate limiting on is a behaviour change for every client.

## The payment hook failed open

Registering that alias exposed a second bug in what it re-enabled.
`CheckHookToken` compared the request's `hook_token` against
`env('HOOK_TOKEN', null)` with a loose `!=`. Both sides are null when the secret
is unset — and `env()` returns null inside a middleware once `config:cache` has
run, whatever the `.env` says — so `null != null` was false and the call passed.
That endpoint marks orders paid.

It now reads `config('services.payment_hook.token')`, compares with
`hash_equals`, and **fails closed**: no configured secret means every call is
refused and logged as critical. Set `HOOK_TOKEN` per environment or the webhook
stays shut.

Verified against a running server: no token → 401, wrong token → 401, correct
token → 200, unset secret → 401.

## If the dev server errors after pulling this

Adding `keycloak-js` re-hoists workspace packages, which invalidates Vite's
pre-bundled dep cache and shows up as
`ENOENT … node_modules/@tanstack/react-query/build/modern/index.js`:

```bash
rm -rf apps/cms-web/node_modules/.vite
```

Then reload. The path in the error is stale, not missing — the package moved to
the repo root's `node_modules`.

## Known gaps

- **SSE depends on a cookie, not the token.** `src/lib/sseClient.ts` uses
  `EventSource`, which cannot send an `Authorization` header. It relies on the
  `distribution_token` cookie that distribution-api sets *after* validating a
  bearer token, so at least one ordinary distribution-api request must succeed
  first. Pre-existing, unchanged by this work.
- **distribution-api needs no change** — it forwards the bearer to main-api's
  `GET /api/users/auth/`, which now accepts JWTs. Its cached session is 1h, which
  outlives the access token by design.
- **The monitoring API is untouched.** `src/lib/axios-monitoring.ts` keeps its own
  Sanctum token and its own login.
- **`users.status` does not gate an admin.** `User::isActiveForAccess()` returns
  true for anyone holding the admin role before it looks at `status`, so
  deactivating an admin does not remove their CMS access and the status branch in
  `CheckAdminPermission` is dead weight on admin routes. Pinned by
  `testAnInactiveAdminIsStillAllowed`. All 5 admins are `active`, so tightening
  it would lock nobody out — but that is a policy change, not a fix.
- **A 401 cannot distinguish "bad token" from "no linked account".** Laravel's
  `Authenticate` middleware answers both the same way, so the login screen names
  the likelier cause rather than knowing it. Fixing it properly means a route
  that verifies a token without requiring a `users` row, the way savings-api's
  `EnsureKeycloakIdentity` does.
- **A blocked silent-SSO iframe can leave the app on its loading state, and
  main-app is exposed to it.** When the realm answers the iframe with
  `frame-ancestors 'self'` — exactly what a client whose Web origins omit the app
  looks like — keycloak-js reports `Timeout when waiting for 3rd party check
  iframe message`, and the init chain was observed not settling within the time
  it took to matter. (Some of those observations were in a backgrounded tab,
  where browsers throttle timers, so treat the exact failure mode as unconfirmed;
  the backstop is cheap either way.)
  cms-web guards against it with a 4s grace period (`INIT_GRACE_MS` in
  `src/context/AuthContext.tsx`) that shows the login button regardless, plus a
  3s `messageReceiveTimeout`. main-app has neither: its `init()` chain is the
  only thing that clears its loading state, so a realm misconfiguration or a
  browser blocking third-party cookies leaves it on a spinner. Worth porting
  both settings.

## Verified locally

Reproduced against the real dev realm (`sso.muhajirproject.com`, `muhajir-dev`),
borrowing main-app's `qurbanplus-v2` client:

- cms-web's authorize request is correct — `response_type=code`,
  `code_challenge_method=S256`, `response_mode=fragment`,
  `scope=openid profile email`.
- Keycloak rejects it with **`Invalid parameter: redirect_uri`**, and nothing
  else. `qurbanplus-v2` whitelists only `http://localhost:5300` (main-app), so the
  handshake is right and the realm simply does not know this app yet. Creating the
  cms-web client above is the whole remaining gap.
- No token is persisted. `localStorage` holds nothing after a plain load; during
  a login redirect keycloak-js writes transient `kc-callback-<state>` entries
  (state, nonce, PKCE verifier — no tokens) and prunes them on the callback.
  Access and refresh tokens stay in memory.
- An unauthenticated `/dashboard` lands on `/login`; with `VITE_KEYCLOAK_*` unset
  the screen renders and says what is missing instead of breaking.

- A **real access token from the live realm** verifies through main-api's
  verifier: signature against the published JWKS, `typ`, `azp`, and issuer all
  pass. The same token is rejected with `token issuer mismatch` when the issuer
  host is left at `dev.sso.` — which is exactly the trap the separate variable
  exists to avoid.

Not verifiable here: the profile call and the guard's subject lookup, both of
which need a reachable MySQL (none locally) and a deployed main-api.

cancel