Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:09:11Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:39, 6 July 2026
Line 287:		Line 287:
	* <code>expiry</code> is advisory at the model layer; do not assume the row is automatically deactivated once it passes.		* <code>expiry</code> is advisory at the model layer; do not assume the row is automatically deactivated once it passes.
	* The granted <code>role</code> is written and read through the role specs (<code>RoleCreateSpec</code> / <code>RoleReadSpec</code>), and each role's <code>contexts</code> is bound to the <code>RoleContext</code> enum rather than an open string at the API layer.		* The granted <code>role</code> is written and read through the role specs (<code>RoleCreateSpec</code> / <code>RoleReadSpec</code>), and each role's <code>contexts</code> is bound to the <code>RoleContext</code> enum rather than an open string at the API layer.

			{{Navbox access governance}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:43:52Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=access-governance
|title=Permission Association
|order=5
|introduced=3.0
|model=PermissionAssociation
|reference=References/Base models & conventions
}}

<code>RoleAssociation</code> grants a [[References/Role|<code>RoleModel</code>]] to a [[References/User & Skills|<code>User</code>]] inside a specific context — an organization or facility. A role is a named collection of [[References/Permission|permissions]]; the association scopes that collection to one user in one context. A user can hold many roles across different contexts, one association per grant.

The Django model (<code>care/security/models/permission_association.py</code>) is the storage layer: the <code>user</code>/<code>role</code> foreign keys, the generic <code>context</code>/<code>context_id</code> pair, and <code>expiry</code>. It has no resource spec of its own — it is a platform-internal authorization join, not a client-writable EMR resource. Two sets of Pydantic resource specs surround it: those that govern the [[References/Role|<code>role</code>]] it points at (<code>care/emr/resources/role/spec.py</code>), and the permission-resolution mixins (<code>care/emr/resources/permissions.py</code>) that read these rows to compute a user's effective permissions in a context.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/models/permission_association.py <code>care/security/models/permission_association.py</code>]
* Role spec (the granted role): [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/role/spec.py <code>care/emr/resources/role/spec.py</code>]
* Permission-resolution mixins: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/permissions.py <code>care/emr/resources/permissions.py</code>]
* Role definitions / <code>RoleContext</code>: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/roles/role.py <code>care/security/roles/role.py</code>]
* Permission contexts: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/constants.py <code>care/security/permissions/constants.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>RoleAssociation</code>
| Grants a <code>RoleModel</code> to a <code>User</code> within a named context, with optional expiry
|}

<code>RoleAssociation</code> extends <code>BaseModel</code> — the lightweight Care base providing <code>external_id</code> (UUID), <code>created_date</code>, <code>modified_date</code>, and soft-delete via <code>deleted</code> (the overridden <code>delete()</code> sets <code>deleted=True</code> instead of removing the row). See [[References/Base models & conventions|Base model]].

It does not extend <code>EMRBaseModel</code>, so there are no <code>created_by</code> / <code>updated_by</code> audit fields, no <code>history</code>/<code>meta</code> JSON, and no <code>external_id</code>-routed EMR API. There is no <code>RoleAssociationCreateSpec</code>/<code>...ReadSpec</code>; rows are created and removed through Care's access-control flows, not through a Pydantic serializer.

== <code>RoleAssociation</code> fields ==

=== Subject and role ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=PermissionAssociation|section=Subject and role|name=user|type=FK → User|notes=yes}}
{{Field|model=PermissionAssociation|section=Subject and role|name=role|type=FK → RoleModel|notes=yes}}
|}

=== Context ===

The context identifies where the role applies. Storing it as a type/id pair rather than a typed foreign key lets one table scope roles to any kind of context — organization, facility, and so on. The pair has no DB-level referential integrity, so nothing stops <code>context_id</code> from pointing at a row that no longer exists.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=PermissionAssociation|section=Context|name=context|type=CharField(1024)|notes=yes}}
{{Field|model=PermissionAssociation|section=Context|name=context_id|type=BigIntegerField|notes=yes}}
|}

=== Lifecycle ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=PermissionAssociation|section=Lifecycle|name=expiry|type=DateTimeField|notes=no}}
|}

== Related models ==

The granted role resolves to permissions through the models below. None belong to <code>RoleAssociation</code>, but every effective-permission lookup walks through them.

=== <code>RoleModel</code> ===

The granted role ([[References/Role]]). A named, flat set of permissions; <code>is_system</code> roles are platform-seeded and cannot be edited through the API.

<syntaxhighlight lang="text">name → CharField(1024) # unique among non-deleted rows
description → TextField (default "")
is_system → BooleanField (default False)
is_archived → BooleanField (default False)
temp_deleted→ BooleanField (default False)
contexts → ArrayField[CharField(24)] (default []) # bound to RoleContext in specs</syntaxhighlight>
=== <code>RolePermission</code> ===

Join table linking one <code>RoleModel</code> to one <code>PermissionModel</code>. A role accumulates permissions across many <code>RolePermission</code> rows; lookups exclude <code>temp_deleted=True</code>.

<syntaxhighlight lang="text">role → FK RoleModel (CASCADE, required)
permission → FK PermissionModel (CASCADE, required)
temp_deleted → BooleanField (default False)</syntaxhighlight>
=== <code>PermissionModel</code> ===

The atomic permission a role grants ([[References/Permission]]).

<syntaxhighlight lang="text">slug → CharField(1024) unique, indexed
name → CharField(1024)
description → TextField (default "")
context → CharField(1024) # one of the PermissionContext values
temp_deleted → BooleanField (default False)</syntaxhighlight>
== Enum / value tables ==

<code>RoleAssociation</code> stores plain strings and integers, but these enums constrain the role it points at and the permissions that role resolves to.

=== <code>RoleContext</code> values ===

Each element of the granted role's <code>contexts</code> array is validated against this enum (<code>care/security/roles/role.py</code>). These are the organizational boundary types a role can apply to — distinct from <code>PermissionContext</code>. The free-form <code>RoleAssociation.context</code> column names an entity of one of these boundary types.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>FACILITY</code>
| Role applies within a facility
|-
| <code>GOVT_ORG</code>
| Role applies within a government organization
|-
| <code>ROLE_ORG</code>
| Role applies within a role (user-group) organization
|}

=== <code>PermissionContext</code> values ===

<code>PermissionModel.context</code> / <code>Permission.context</code> takes one of these values (<code>care/security/permissions/constants.py</code>). When computing effective permissions from <code>RoleAssociation</code> rows, the permission-resolution mixins (below) filter a user's grants by these contexts.

{| class="wikitable"
|-
! Value
|-
| <code>GENERIC</code>
|-
| <code>FACILITY</code>
|-
| <code>PATIENT</code>
|-
| <code>QUESTIONNAIRE</code>
|-
| <code>ORGANIZATION</code>
|-
| <code>FACILITY_ORGANIZATION</code>
|-
| <code>ENCOUNTER</code>
|}

=== <code>PermissionEnum</code> (role write field) ===

When a role is written through <code>RoleCreateSpec</code>, its <code>permissions</code> field is typed against <code>PermissionController.get_enum()</code> — a <code>str</code> enum built at runtime from every registered permission <code>name</code> across all permission handlers (for example <code>can_create_patient</code>, <code>can_write_patient</code>, <code>can_list_patients</code>, <code>can_view_clinical_data</code>). The set is deployment-dependent: internal handlers plus any plugin-registered ones, not a fixed list.

=== Built-in (<code>is_system</code>) roles ===

Seeded by <code>RoleController</code> (<code>care/security/roles/role.py</code>). Associations often bind a user to one of these. They cannot be created, updated, or deleted through the API.

{| class="wikitable"
|-
! Role
! Contexts
|-
| <code>Doctor</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Nurse</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Staff</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Volunteer</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Pharmacist</code>
| <code>FACILITY</code>
|-
| <code>Administrator</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Facility Admin</code>
| <code>FACILITY</code>
|-
| <code>Admin</code>
| <code>FACILITY</code>, <code>GOVT_ORG</code>
|-
| <code>Admin</code> (role org)
| <code>ROLE_ORG</code>
|-
| <code>Manager</code> (role org)
| <code>ROLE_ORG</code>
|-
| <code>Member</code> (role org)
| <code>ROLE_ORG</code>
|}

== Resource specs (API schema) ==

<code>RoleAssociation</code> has no dedicated <code>...CreateSpec</code>/<code>...UpdateSpec</code>/<code>...ListSpec</code>/<code>...RetrieveSpec</code> — it is not exposed as an EMR resource. Its Pydantic surface is twofold: the specs that define the role an association grants, and the mixins that consume associations to expose a user's effective permissions on another resource. All extend <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which provides <code>serialize</code> (DB → Pydantic via <code>perform_extra_serialization</code>) and <code>de_serialize</code> (Pydantic → DB via <code>perform_extra_deserialization</code>).

=== Specs for the granted role ===

{| class="wikitable"
|-
! Spec class
! Role
! Fields
|-
| <code>RoleBaseSpec</code>
| shared base (<code>__exclude__ = ["permissions"]</code>)
| <code>id</code>, <code>name</code>, <code>description</code>, <code>is_system</code>, <code>is_archived</code>, <code>contexts</code>
|-
| <code>RoleCreateSpec</code>
| write · create & update
| base fields + <code>permissions: list[PermissionEnum]</code> (≥ 1, de-duplicated)
|-
| <code>RoleReadSpec</code>
| read · detail/list
| base fields + <code>permissions: list[PermissionSpec]</code>
|-
| <code>RoleReadMinimalSpec</code>
| read · minimal/embedded
| base fields only
|-
| <code>PermissionSpec</code>
| nested (read)
| <code>name</code>, <code>description</code>, <code>slug</code> (<code>SlugType</code>), <code>context</code>
|}

<code>RoleBaseSpec.contexts</code> is <code>list[RoleContext]</code> — bound to the <code>RoleContext</code> enum at the API layer even though the model column is an open string array. <code>PermissionSpec.slug</code> is a <code>SlugType</code>: <code>str</code>, length 5–50, pattern <code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code>. Core role validation (<code>RoleCreateSpec.validate_role</code>, mode="after") requires a non-blank unique name (<code>name__iexact</code>), rejects <code>is_system=True</code>, rejects updating a system role, and requires ≥ 1 permission. See [[References/Role]] for the full spec breakdown.

=== Permission-resolution mixins (<code>care/emr/resources/permissions.py</code>) ===

Other resource specs (patient, encounter, facility) inherit these mixins. When <code>serialize</code> runs with an authenticated <code>user</code>, <code>perform_extra_user_serialization</code> walks the user's <code>RoleAssociation</code> rows for that object, resolves the granted roles to permissions, and writes them into <code>mapping["permissions"]</code>. This is the read path that turns stored associations into a permission list on the wire.

{| class="wikitable"
|-
! Mixin
! Resolves (from the user's associations)
! Context filter
! Extra fields
|-
| <code>PermissionsMixin</code>
| base — adds <code>permissions: list[str]</code>
| —
| —
|-
| <code>PatientPermissionsMixin</code>
| roles the user holds on a patient
| <code>permission__context in ("PATIENT", "FACILITY")</code>
| —
|-
| <code>EncounterPermissionsMixin</code>
| roles the user holds on an encounter
| <code>permission__context in ("ENCOUNTER", "PATIENT")</code>
| —
|-
| <code>FacilityPermissionsMixin</code>
| roles on facility root + sub-orgs
| none (root) / child set excludes <code>can_update_facility</code>
| <code>root_org_permissions</code>, <code>child_org_permissions</code>
|}

Permission slugs are resolved via <code>RolePermission.objects.filter(role_id__in=roles, …).values_list("permission__slug", flat=True)</code>, so only active (non-<code>temp_deleted</code>) grants on the resolved roles count.

== Methods & save behaviour ==

<code>RoleAssociation</code> defines no model methods, validators, or <code>save()</code>/<code>delete()</code> overrides of its own. It inherits soft-delete from <code>BaseModel</code>: calling <code>delete()</code> sets <code>deleted=True</code> and persists with <code>save(update_fields=["deleted"])</code>, and the default manager filters out soft-deleted rows.

A source <code>TODO</code> flags a planned composite index on <code>user</code>, <code>context</code>, and <code>context_id</code> that does not yet exist; lookups by those fields are not index-backed today.

<code>expiry</code> is a stored timestamp only — the model does not enforce it. Expiry-based revocation falls to the authorization layer that reads these associations.

<code>RoleAssociation</code> has no <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code>, since it has no spec. The serialization hooks that matter live on the role specs and the permission mixins above.

== API integration notes ==

* <code>RoleAssociation</code> is a platform-maintained authorization record, not a client-writable EMR resource. It is created and removed through Care's access-control flows, not through FHIR, a Pydantic spec, or direct REST writes.
* The <code>context</code> / <code>context_id</code> pair is a generic (non-FK) reference. <code>context</code> is a free-form string naming an entity in one of the <code>RoleContext</code> boundary types, and <code>context_id</code> is that entity's integer PK, not its <code>external_id</code> UUID. Pair the right type string with the matching PK; nothing at the database level enforces it.
* A user may have many <code>RoleAssociation</code> rows, one per (role, context) grant. The <code>permissions</code> mixins compute effective permissions in a given context by unioning the active permission slugs of all resolved roles, filtered by <code>PermissionContext</code>.
* <code>expiry</code> is advisory at the model layer; do not assume the row is automatically deactivated once it passes.
* The granted <code>role</code> is written and read through the role specs (<code>RoleCreateSpec</code> / <code>RoleReadSpec</code>), and each role's <code>contexts</code> is bound to the <code>RoleContext</code> enum rather than an open string at the API layer.

{{Related}}

References/Permission Association - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed