mdm-ordinis/docs-internal/keycloak-admin-setup.md

# Keycloak Admin client setup for UserDisplayService Phase 2

`KeycloakAdminUserResolver` resolves a JWT `sub` against the Keycloak Admin
REST API on cache miss, so users that never hit ordinis still get a
display name in audit / reviews / changelog / events / history. Without
this, only users who personally made an authenticated request show up
with a real name (the "ток мой UUID отображается" pain).

This is a per-environment one-time setup. Disabled by default — flip on
once the Keycloak client + vault secret exist.

## Step 1: Create service-account client in Keycloak

Realm: `nstart`. Path: Clients → Create client.

| Field | Value |
|---|---|
| Client type | OpenID Connect |
| Client ID | `ordinis-admin-client` |
| Client authentication | **On** (confidential) |
| Authorization | Off |
| Standard flow | Off |
| Direct access grants | Off |
| Service accounts roles | **On** |

Save. On the created client → **Service accounts roles** tab → **Assign
role** → Filter by clients → `realm-management` → check **`view-users`**
→ Assign.

(`view-users` is the minimum scope needed for `GET /admin/realms/{realm}/users/{id}`.
Don't assign `manage-users` — read-only is enough.)

Then **Credentials** tab → copy the `Client secret` (long random string).

## Step 2: Store secret in Vault

The cluster-domain matters here — staging is `265.local`, prod is
`altum.local`. Both have separate Vault instances.

Staging (cluster.265, namespace `config`):
```bash
kubectl -n config exec -it vault-0 -- sh -c '
  vault login <root-or-admin-token>
  vault kv put secret/ordinis/cuod/keycloak-admin \
    client_id=ordinis-admin-client \
    client_secret=<paste-from-keycloak>
'
```

Prod (altum, namespace `vault`):
```bash
ssh root@192.168.100.142 'kubectl -n vault exec -it vault-0 -- sh -c "
  vault login <prod-root-token>
  vault kv put secret/ordinis/cuod/keycloak-admin \
    client_id=ordinis-admin-client \
    client_secret=<paste-from-keycloak>
"'
```

⚠️ Different secret per environment — staging and prod have separate
Keycloak clients (and certainly separate secrets).

## Step 3: Wire into ordinis-app deployment

Add to `ordinis-app` helm chart annotations (vault agent injector
template) — same pattern as `secret-postgres` / `secret-kafka` already
present in the chart:

```yaml
vault.hashicorp.com/agent-inject-secret-keycloak-admin: secret/data/ordinis/cuod/keycloak-admin
vault.hashicorp.com/agent-inject-template-keycloak-admin: |
  {{- with secret "secret/data/ordinis/cuod/keycloak-admin" -}}
  export ORDINIS_KEYCLOAK_ADMIN_CLIENT_ID="{{ .Data.data.client_id }}"
  export ORDINIS_KEYCLOAK_ADMIN_CLIENT_SECRET="{{ .Data.data.client_secret }}"
  {{- end }}
```

Add env vars to the deployment:

```yaml
env:
  - name: ORDINIS_KEYCLOAK_ADMIN_ENABLED
    value: "true"
  - name: ORDINIS_KEYCLOAK_ADMIN_URL
    value: "https://auth.nstart.space"   # both envs use the same Keycloak
  - name: ORDINIS_KEYCLOAK_ADMIN_REALM
    value: "nstart"
  # CLIENT_ID + CLIENT_SECRET arrive via the vault-injected
  # /vault/secrets/keycloak-admin file sourced before java starts.
```

## Step 4: Verify

After redeploy, check the pod log on startup:

```
KeycloakAdminUserResolver active — base=https://auth.nstart.space realm=nstart client=ordinis-admin-client
```

End-to-end:

```bash
# Find a sub that's NOT in the JVM cache (e.g. a user who never logged in).
# Hit the display endpoint as an admin user:
curl -s -H "Authorization: Bearer $TOKEN" \
  https://ordinis.k8s.265.nstart.cloud/api/v1/admin/users/<uuid>/display | jq
# Expect 200 with username/name/email even on cold cache, instead of 404.
```

Then check the DB — the row was persisted from the on-demand resolve:

```sql
SELECT sub, preferred_username, source, synced_at
  FROM user_display_cache
 WHERE sub = '<uuid>';
-- source = KEYCLOAK_ON_DEMAND
```

## Step 5: Phase 3 (later — scheduled bulk sync)

When ready to refill the table proactively (avoids the per-user
on-demand latency for fresh subs), add a Spring `@Scheduled` task that
calls `GET /admin/realms/{realm}/users` paginated and writes via
`UserDisplayService.upsertFromKeycloak`. Recommended every 6h. Not
included in this MR — depends on observed cache miss rate.

## Failure modes

- **Service-account client missing `view-users`** → 403 on lookup,
  resolver throws RuntimeException, UserDisplayService logs warn,
  caller falls back to short UUID. No outage, just no resolve.
- **Keycloak unreachable** → connect timeout / 502. Same fallback as
  above. Cached entries (DB tier) keep working.
- **client_secret rotated in Keycloak but vault not updated** → 401 on
  token request → resolver wipes cached token and surfaces
  RuntimeException. Update vault secret and the next attempt succeeds.