fix(keycloak): reconcile the admin-ui device grant so the CLI works on prod

`proxy-smart login --url https://api.proxy-smart.com` fails at the first
step:

  400 {"error":"unauthorized_client",
       "error_description":"Client is not allowed to initiate OAuth 2.0
                            Device Authorization Grant."}

The CLI has no browser and no client secret, so it authenticates with the
RFC 8628 device flow against admin-ui. With the grant disabled there is
no way in at all — and Keycloak's own admin console is not reachable on
production either, because the WAF blocks /admin. So prod had no CLI and
no console.

All three realm exports already declare
`oauth2.device.authorization.grant.enabled: "true"` on admin-ui. It was
still unset on production, for the same reason as every other drift in
kc-system-provisioning.ts: --import-realm is IGNORE_EXISTING, so a realm
that already exists never picks up anything added to the export
afterwards. Beta has it only because .github/scripts/deploy-beta-remote.sh
reconciles it at deploy time (lines 546-591) and production does not run
that script.

Reconciling it at startup alongside the other system clients makes it
true in every environment by construction, rather than in whichever one
happened to run a shell script. Idempotent and non-fatal, like its
neighbours.

The tests assert the reconcile rather than the export, because an export
declaring something is not evidence that it is set anywhere — that
assumption is precisely what hid this.

Author: quotentiroler

backend/src/init.ts

@@ -13,6 +13,7 @@ import {
   ensureIntrospectionClientConfig,
   ensureResourceServerClients,
   ensureResourceIndicatorsScope,
+  ensureAdminUiDeviceGrant,
 } from './lib/kc-system-provisioning'
 import KcAdminClient from '@keycloak/keycloak-admin-client'
 
@@ -959,6 +960,8 @@ async function ensureSystemClients(): Promise<void> {
   await ensureResourceServerClients(admin)
   // After the resource clients — the scope's mappers name them as audiences.
   await ensureResourceIndicatorsScope(admin)
+  // Lets  work without a browser or a client secret.
+  await ensureAdminUiDeviceGrant(admin)
 }
 
 export async function initializeServer(): Promise<void> {

backend/src/lib/kc-system-provisioning.ts

@@ -29,6 +29,9 @@ export const RESOURCE_AUDIENCE_CLIENT_IDS = ['fhir-resource-server', 'mcp-resour
  */
 const RESOURCE_URL_ATTR = 'resource_url'
 
+/** Keycloak client attribute gating RFC 8628 device authorization. */
+const DEVICE_GRANT_ATTR = 'oauth2.device.authorization.grant.enabled'
+
 /**
  * Non-login "resource server" client that exists only to hold a `resource_url`.
  *
@@ -353,3 +356,53 @@ export async function ensureShlExchangeClient(admin: KcAdminClient): Promise<voi
     })
   }
 }
+
+/**
+ * Ensure the admin webapp client may start the RFC 8628 device authorization grant.
+ *
+ * This is how `proxy-smart login` works: the CLI has no browser and no client
+ * secret, so it starts a device flow against the admin-ui client and polls. With
+ * the grant disabled Keycloak refuses at the first step:
+ *
+ *   HTTP 400 {"error":"unauthorized_client",
+ *             "error_description":"Client is not allowed to initiate OAuth 2.0
+ *                                  Device Authorization Grant."}
+ *
+ * ALL THREE realm exports already declare the attribute — and it still was not
+ * set on production. Same reason as every other drift in this file:
+ * `--import-realm` is IGNORE_EXISTING, so a realm that already exists never picks
+ * up anything added to the export afterwards. Beta only had it because
+ * .github/scripts/deploy-beta-remote.sh reconciles it at deploy time, and
+ * production does not run that script. Reconciling here makes it true in every
+ * environment by construction rather than in whichever one happened to run a
+ * shell script.
+ */
+export async function ensureAdminUiDeviceGrant(admin: KcAdminClient): Promise<void> {
+  const clientId = config.keycloak.adminUiClientId
+  if (!clientId) return
+
+  try {
+    const existing = await admin.clients.find({ clientId, max: 1 })
+    if (existing.length === 0) {
+      logger.keycloak.debug('Admin UI client not found — skipping device-grant reconcile', { clientId })
+      return
+    }
+
+    const client = existing[0]
+    if (client.attributes?.[DEVICE_GRANT_ATTR] === 'true') return
+
+    await admin.clients.update(
+      { id: client.id! },
+      { clientId, attributes: { ...(client.attributes ?? {}), [DEVICE_GRANT_ATTR]: 'true' } },
+    )
+    logger.keycloak.info('Enabled device-authorization grant on the admin UI client', {
+      clientId,
+      previous: client.attributes?.[DEVICE_GRANT_ATTR] ?? '(unset)',
+    })
+  } catch (error) {
+    logger.keycloak.warn('Failed to reconcile admin-ui device-authorization grant', {
+      clientId,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+}

backend/test/admin-ui-device-grant.test.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: Max Health Inc.
+// SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Commercial
+
+/**
+ * `proxy-smart login` needs the device grant on the admin UI client.
+ *
+ * THE BUG THIS GUARDS. All three realm exports declare
+ * `oauth2.device.authorization.grant.enabled: "true"` on admin-ui, and it still
+ * was not set on production, so the CLI could not authenticate there at all:
+ *
+ *   HTTP 400 {"error":"unauthorized_client",
+ *             "error_description":"Client is not allowed to initiate OAuth 2.0
+ *                                  Device Authorization Grant."}
+ *
+ * `--import-realm` is IGNORE_EXISTING: a realm that already exists never picks up
+ * anything added to the export afterwards. Beta had it only because
+ * .github/scripts/deploy-beta-remote.sh reconciles it at deploy time, and
+ * production does not run that script — the same shape as the resource-indicators
+ * drift in resource-server-clients.test.ts.
+ *
+ * Declaring it in an export is therefore not evidence that it is set anywhere.
+ * These tests assert the runtime reconcile, which is what actually makes it true.
+ */
+import { describe, it, expect } from 'bun:test'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { ensureAdminUiDeviceGrant } from '@/lib/kc-system-provisioning'
+
+const DEVICE_GRANT_ATTR = 'oauth2.device.authorization.grant.enabled'
+const REPO = join(import.meta.dir, '..', '..')
+
+interface RealmExport {
+  clients?: { clientId?: string; attributes?: Record<string, string> }[]
+}
+
+/** A stand-in for the Keycloak admin client, recording what would be written. */
+function fakeAdmin(existing: Record<string, string> | null) {
+  const updates: { id: string; attributes?: Record<string, string> }[] = []
+  return {
+    updates,
+    clients: {
+      find: async () =>
+        existing === null ? [] : [{ id: 'internal-uuid', clientId: 'admin-ui', attributes: existing }],
+      update: async (
+        where: { id: string },
+        body: { attributes?: Record<string, string> },
+      ) => {
+        updates.push({ id: where.id, attributes: body.attributes })
+      },
+    },
+  }
+}
+
+describe('every realm export declares the attribute', () => {
+  // Not the thing that makes it true, but if an export ever drops it the runtime
+  // reconcile becomes the only source — worth knowing.
+  for (const path of [
+    'keycloak/realm-export.json',
+    'deploy/beta/realm-export.json',
+    'deploy/prod/realm-export.json',
+  ]) {
+    it(`${path} sets it on admin-ui`, () => {
+      const realm = JSON.parse(readFileSync(join(REPO, path), 'utf8')) as RealmExport
+      const adminUi = (realm.clients ?? []).find((c) => c.clientId === 'admin-ui')
+      expect(adminUi?.attributes?.[DEVICE_GRANT_ATTR]).toBe('true')
+    })
+  }
+})
+
+describe('ensureAdminUiDeviceGrant', () => {
+  it('enables the grant when the live client has it disabled', async () => {
+    // Production's actual state: the attribute present and false.
+    const admin = fakeAdmin({ [DEVICE_GRANT_ATTR]: 'false', 'pkce.code.challenge.method': 'S256' })
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await ensureAdminUiDeviceGrant(admin as any)
+
+    expect(admin.updates).toHaveLength(1)
+    expect(admin.updates[0].attributes?.[DEVICE_GRANT_ATTR]).toBe('true')
+    // Unrelated attributes must survive the merge.
+    expect(admin.updates[0].attributes?.['pkce.code.challenge.method']).toBe('S256')
+  })
+
+  it('enables the grant when the attribute is absent entirely', async () => {
+    const admin = fakeAdmin({})
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await ensureAdminUiDeviceGrant(admin as any)
+
+    expect(admin.updates).toHaveLength(1)
+    expect(admin.updates[0].attributes?.[DEVICE_GRANT_ATTR]).toBe('true')
+  })
+
+  it('writes nothing when it is already enabled', async () => {
+    // Idempotent: this runs on every boot.
+    const admin = fakeAdmin({ [DEVICE_GRANT_ATTR]: 'true' })
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await ensureAdminUiDeviceGrant(admin as any)
+
+    expect(admin.updates).toHaveLength(0)
+  })
+
+  it('does nothing when the client does not exist', async () => {
+    const admin = fakeAdmin(null)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await ensureAdminUiDeviceGrant(admin as any)
+
+    expect(admin.updates).toHaveLength(0)
+  })
+
+  it('never throws — a failed reconcile must not stop the server booting', async () => {
+    const admin = {
+      clients: {
+        find: async () => { throw new Error('Keycloak unreachable') },
+        update: async () => {},
+      },
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(ensureAdminUiDeviceGrant(admin as any)).resolves.toBeUndefined()
+  })
+})