Staff Portal Application Registration

How applications (e.g. registries) self-register their Staff Portal tile, roles and permissions into the IAM Staff service at install time.

1. Overview

The IAM Staff service drives the Staff Portal home screen: the set of application tiles a staff user sees (Registry, MinIO, Superset, Keycloak …), and the roles/permissions that gate access to each.

Historically this catalog was seeded into IAM ahead of time, which had two problems:

• IAM is installed before the applications it points to, so an application URL (e.g. a registry's) had to be hardcoded into IAM before that application even existed.

• An environment may run multiple instances of the same product (e.g. two registries), which a single hardcoded entry cannot represent.

To solve both, an application now registers itself into IAM at install time via a dedicated API. The application pushes its own tile (URL, icon, ordering) together with its roles and permissions. The call is idempotent and keyed by a mnemonic, so re-installs/upgrades simply refresh the entry, and multiple instances coexist by each using a distinct mnemonic.

---

1.1 Key Rule — mnemonic == Keycloak client_id

The application_mnemonic an application registers with must equal its Keycloak client_id. Staff Portal tiles and permissions are gated by the resource_access client-roles in the user's token, so this equality is what lets IAM resolve which tiles a user can open and which permissions a role grants.

For multiple instances of the same product, each instance has its own Keycloak client (e.g. nsr-staff-portal, fr-staff-portal) and registers its catalog under that mnemonic.

---

2. API Reference

2.1 Register / update a Staff Portal application

Upserts an application and its access catalog. Creates the application on first call, updates it on subsequent calls (matched by application_mnemonic).

POST /user-access/staff_portal_applications
Authorization: Bearer <access-token>
Content-Type: application/json

Authentication

The endpoint requires a valid bearer token issued by a login provider IAM trusts (the staff realm). It is guarded by the auth_api_register_staff_portal_application setting; operators can restrict it to a specific role by configuring a required claim (claim_name / claim_values) via IAM_STAFF_AUTH_API_REGISTER_STAFF_PORTAL_APPLICATION__*.

Request body

Field	Type	Description
application_mnemonic	string (required)	Unique identifier; must equal the application's Keycloak client_id.
application_url	string (required)	URL the tile opens (the application's Staff Portal UI).
application_description	string	Display name / description.
icon_base64	string	Base64-encoded tile icon (SVG/PNG).
width	integer	Tile width hint.
order	integer	Tile ordering on the home screen.
active	boolean (default true)	Whether the tile is active/visible.
permissions	array	The application's permission catalog (see below).
roles	array	The application's roles, each granting a set of permissions (see below).

permissions[] item

Field	Type	Description
permission_mnemonic	string (required)	Unique permission key within the application.
permission_description	string	Human-readable description.
active	boolean (default true)	Whether the permission is active.

roles[] item

Field	Type	Description
role_mnemonic	string (required)	Role name; must match the Keycloak client role name.
role_description	string	Human-readable description.
active	boolean (default true)	Whether the role is active.
permissions	array of string	Permission mnemonics granted to this role. Each must appear in the request's permissions array.

Behaviour

• Upsert by application_mnemonic — first call inserts, later calls update in place. The row is flagged as self-registered so the IAM seed loader never overwrites it.

• Permissions and roles are upserted scoped to this application's id.

• Role → permission mappings are rebuilt to exactly match the payload (mappings dropped from the payload are removed).

• A role referencing a permission that is not in the request's permissions list is rejected with 400 Bad Request.

Response

{
  "id": 5,
  "application_mnemonic": "nsr-staff-portal",
  "created": true,
  "permissions_count": 72,
  "roles_count": 11
}

Field	Type	Description
id	integer	The application's id in IAM.
application_mnemonic	string	Echo of the registered mnemonic.
created	boolean	true if newly created, false if an existing row was updated.
permissions_count	integer	Permissions in the payload.
roles_count	integer	Roles in the payload.

Example request

{
  "application_mnemonic": "nsr-staff-portal",
  "application_url": "https://nsr.trial.openg2p.org",
  "application_description": "National Social Registry",
  "icon_base64": "PHN2ZyB3aWR0aD0i...",
  "width": 80,
  "order": 1,
  "active": true,
  "permissions": [
    { "permission_mnemonic": "intakeSubmission:edit", "permission_description": "Edit intake submissions" },
    { "permission_mnemonic": "intakeSubmission:view", "permission_description": "View intake submissions" }
  ],
  "roles": [
    {
      "role_mnemonic": "Intake Officer",
      "role_description": "Handles initial data entry",
      "permissions": ["intakeSubmission:edit", "intakeSubmission:view"]
    }
  ]
}

---

3. How an application registers (install-time)

Registration is driven by the application's own deployment so the correct URL is known at the application's install time. For OpenG2P registries this is a post-install / post-upgrade Helm hook Job in the registry chart that:

1. Waits for the IAM Staff API to be reachable.

2. Obtains an access token (client-credentials using the application's own per-release Keycloak client + secret).

3. Builds the payload — its own application_mnemonic (= <release>-staff-portal) and application_url (its Staff Portal UI host) merged with its packaged roles/permissions catalog.

4. POSTs to /user-access/staff_portal_applications, retrying while the Keycloak client / IAM finish coming up.

Because the call is an idempotent upsert, the hook runs safely on every install and upgrade.

---

4. CORS — manual step

If the application's web UI makes cross-origin browser calls into the IAM Staff API, the browser will block them unless the application's origin is in IAM's CORS allow-list.

That list (IAM_STAFF_CORS_ALLOW_ORIGINS) is read once at IAM startup, so an application installed later is not covered automatically. When installing such an application:

1. Add its origin (scheme + host only, e.g. https://nsr.trial.openg2p.org) to IAM_STAFF_CORS_ALLOW_ORIGINS on the IAM chart.

2. helm upgrade IAM and roll the iam-staff-portal-api pods.

Notes

• * cannot be used — IAM uses auth cookies (credentialed requests), and browsers forbid Access-Control-Allow-Origin: * with credentials. List origins explicitly.

• If the application does not make browser calls into the IAM Staff API (only links out, or talks to IAM server-to-server), no CORS change is needed.

---

5. Uninstall / cleanup

helm uninstall of an application does not touch IAM, so its registered rows (tile + roles + permissions) remain. A stale tile is inert for users who no longer hold its client roles (it renders disabled), but the rows persist.

Clean teardown is handled by the application's uninstall tooling, which removes that application's rows from the IAM database — keyed strictly by its application_mnemonic, so other applications and the built-in singletons (Keycloak / MinIO / Superset) are untouched. (For OpenG2P registries, this is built into the registry uninstall-registry.sh script.)

---

6. Multiple instances of the same product

Two registries of the same product in one environment register independently:

Instance	application_mnemonic	application_url
National Social Registry	nsr-staff-portal	https://nsr.<ns>.openg2p.org
Farmer Registry	fr-staff-portal	https://fr.<ns>.openg2p.org

Each pushes its own (identical) roles/permissions catalog under its own mnemonic, so they appear as separate tiles with independently resolved access.

---