Mapper permissions & roles: capability layer with dual Keycloak/Django support

[paynejd]

Replace the hardcoded Mapper group checks with a permission/capability layer that behaves identically in standalone (Django-only) and Keycloak-integrated deployments. OCL supports both permanently — this is not a migration.

Today the Mapper is gated by group names in code: mapper-approved/mapper-waitlist (oclapi2/core/concepts/views.py:1041,1064), isInWaitlist() (oclmap/src/common/utils.js:1125), mapper_ai_assistant (ocl-ai-assistant/core/match/views.py:101,194). Roles and tiers must be data, so new roles need no code change.

ACs

• Permissions defined: mapper.use, mapper.ai_assistant, mapper.custom_algorithms, mapper.org_projects. Roles bundle permissions; roles assign to groups and users.
• Code checks permissions only — no role or group names in oclapi2, oclmap or ocl-ai-assistant
• Standalone: administered in Django admin. Keycloak-integrated: defined in Keycloak and replicated into Django.
• Replication must not silently drop assignments. core/common/backends.py:69,80 calls user.set_groups(claims.get('groups', [])) on every OIDC login, replacing the whole Django group set — verify and document the real behaviour before anything relies on it.
• Every account receives the default preview role: Keycloak default + Django on user creation + a re-runnable backfill for existing accounts
• GET /user/ exposes the capability set (consumed by the Mapper UI and the usage page)
• is_mapper_approved / is_mapper_waitlisted group checks retired

To decide during implementation

• Replication mechanism and conflict rule: login claims vs sync job vs admin events; whether role→permission mappings and cap values replicate, or only membership. Proposed: Keycloak authoritative when integrated, Django authoritative standalone.
• Default-access mechanism in both modes

Out of scope: TBv3 permissions, tier roles, per-repo/per-project permissions (#2763).

Approach doc: ocl-workspace/mapper/2026-09-15-mapper-public-preview-approach.md (WP1). Caps and ledger: #2762 · epic OpenConceptLab/ocl_online#133

[paynejd]

Auth-group audit — what actually gates the Mapper today (2026-09-16)

Code investigation across oclapi2, oclmap, ocl-ai-assistant, ocl-scispacy-loinc and oclweb3. This widens the scope of this ticket: the group checks to retire live in three services, not one.

The gates that exist

Group	Prod members	What it actually controls
mapper-approved	14	The only Mapper access gate. Exactly two call sites: $match (oclapi2/core/concepts/views.py:1041) and $rerank (:1064). Read nowhere else — not in oclmap, not in ai-assistant.
mapper-waitlist	416	Denylist, checked independently of approval. Gates the oclmap route (src/components/app/App.jsx:40) and disqualifies on the API — a user in both groups still gets 403, because the waitlist check comes first.
mapper_ai_assistant	8	Much broader than its name. Gates every ai-assistant endpoint ($invoke, match/recommend, models, prompt templates/versions), the scispacy-LOINC algorithm (ocl-scispacy-loinc/core/match/views.py:17), all AI features in the Mapper UI (MapProject.jsx:515), and bridge matching in the external premium bundle.
core_user	7	Not an access gate — a privilege bundle: lexical variants in $match (views.py:864, variants_repo resolved only if is_core_user), custom encoder models in $rerank (:1075), AI model/prompt-template/output-locale selection in the Mapper UI, "generate comment" in oclweb3 ConceptForm.jsx:459, prompt $invoke as an alternative to mapper_ai_assistant, and ~6x higher match throttles (1000/min · 30k/day vs 300/min · 5k/day — core/common/throttling.py:74,88, rates at core/settings.py:208).

Dead groups — no code reads them

premium_user (5 members) and standard_user (6 members) appear only in the AUTH_GROUPS whitelist in core/users/constants.py, which just validates names assigned via PUT /users/<username>/ (core/users/serializers.py:254-262). Nothing branches on either.

The "standard" throttle tier is the fallback for any authenticated non-core user, not a group lookup: ThrottleUtil.get_throttles_by_user_plan checks superuser → guest → is_core_group → standard. So premium_user members are throttled identically to everyone else, and standard_user membership changes nothing. early_access_ngo is likewise unused. (guest_user is live and lowers limits to 400/min.)

Recommendation: treat premium_user, standard_user and early_access_ngo as removable once this capability layer lands, rather than mapping them to roles. Nothing depends on them today.

Scope additions for this ticket

1. Retiring group-name checks spans three repos: oclapi2 (is_mapper_approved/is_mapper_waitlisted/is_core_group), ocl-ai-assistant (check_auth_group(MAPPER_AI_ASSISTANT_GROUP) at 5 call sites), and ocl-scispacy-loinc (check_auth_group in its own BaseAPIView). oclmap/oclweb3 read auth_groups client-side via hasAuthGroup.
2. core_user is a privilege bundle the permission model must absorb — lexical variants, custom encoders, model/prompt selection, and the higher throttle tier are four separate capabilities riding one group name. Grandfathering (Grandfather existing Mapper users into unlimited Mapper access #2781) covers access only, not these.
3. Client-side hasAuthGroup does substring matching — oclmap/src/common/utils.js:449 and oclweb3/src/common/utils.js:497 use group.includes(groupName), so a future group whose name contains an existing one silently matches. Worth tightening to equality while touching this code.
4. Project CRUD is not gated by any Mapper group. MapProjectListView uses CanEditConceptDictionary, so any authenticated user can already create projects and upload spreadsheets — only $match/$rerank reject them. That is the silent-failure path in Mapper preview: front-end experience (access, quota UI, error handling) #2773.

Full write-up: ocl-workspace/mapper/2026-09-15-mapper-public-preview-approach.md

[ocl-automation]

Automated Triage — 2026-09-16

Dimension	Score
Complexity	5
Scope	5
Clarity	4
Dependency	3
Risk	4

Decision: decision/human-review
Type: type/feature
Signals: signal/high-risk, signal/large-scope, signal/well-specified, signal/has-dependencies

Architectural redesign replacing hardcoded group checks with a permission layer across three services (oclapi2, oclmap, ocl-ai-assistant), supporting dual Keycloak/Django modes. Well-specified with clear acceptance criteria, but complex replication and conflict resolution decisions remain. High risk due to authentication/authorization changes affecting user access.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).

[paynejd]

Decision (2026-09-23): Keycloak is authoritative when integrated

This settles the "replication mechanism and conflict rule" item.

• Keycloak deployments:
  • All groups, roles and permissions are managed and defined in Keycloak, and must not be defined in Django by a user.
  • OCL syncs from Keycloak into Django, so anything user-defined in Django is ignored or overwritten.
  • That makes update_user → set_groups(claims['groups']) on every authenticated request correct behaviour. It also recomputes is_staff/is_superuser from staff_user/superadmin_user.
• Standalone: Django is authoritative, and group membership is admin-only. Capabilities, Permissions and Groups + Mapper preview oclapi2#900 currently lets any user PUT /user/ into any group; the fix is requested there.
• Interim for the preview: group → permission mappings and limit values come from deployment config (OCL_GROUPS_CONFIG, OpenConceptLab/oclinfrastructure#7). They're synced into Django at startup, with the config as the source of truth. Whether permissions later become Keycloak roles replicated into Django remains open.