0034: Define Permission Dependencies in the Authorization Schema#
Status#
Draft
Context#
Before PR #538, authz.policy declared permission dependencies as Casbin g2 rows. For example, g2, act^content_libraries.edit_library_content, act^content_libraries.view_library meant that editing library content requires viewing the library. That PR moved static roles and permissions into the authorization schema (ADR 0017) and removed the policy file, but the schema had no field for dependencies, so new installations no longer load them.
The Custom Roles feature needs these dependencies for two reasons:
When an administrator enables a permission, the UI also selects every permission it depends on. When an administrator disables a permission that other selected permissions depend on, the UI warns first and then also disables those permissions.
The
g2rows must be generated from the schema rather than from a policy file.
ADR 0022 deferred permission implication and listed what a later schema version must define before adding it. This ADR adds permission dependencies and covers those points.
Decision#
1. Syntax#
A permission may declare an optional depends_on list with the complete IDs of the permissions it directly requires. A dependency means that granting the permission also grants the permissions it depends on. For example, granting edit_library_content also grants view_library, because a user cannot edit the content of a library they cannot view.
permissions:
- namespace: content_libraries
name: edit_library_content
display_name: Edit
# ...
scopes:
- lib
depends_on:
- content_libraries.view_library
Only the file that defines a permission declares its dependencies. Role extensions cannot add or remove dependencies.
2. Schema version#
depends_on is allowed only in files that declare schema_version: "1.1". The field stays optional in 1.1, so a 1.1 file that declares no depends_on is valid and means the same as it would in 1.0. Files that declare "1.0" keep their current meaning, and a 1.0 file that declares depends_on is rejected as an unknown field.
1.0 and 1.1 files are a supported combination. The “unsupported combinations of schema versions” check in ADR 0017 does not reject a deployment that loads both, so a file can move to 1.1 without requiring every other file to move with it. For example, library_permissions.yaml can declare 1.1 and depends_on, while library_roles.yaml stays at 1.0.
Version 1.1 has its own JSON Schema file, authz-schema-v1.1.json, next to the existing authz-schema-v1.json. The existing file keeps "const": "1.0" and does not change, so tools that validate 1.0 files continue to work. The 1.1 file accepts everything 1.0 accepts and adds the optional depends_on field. The validator selects the JSON Schema file from the schema_version that each file declares.
3. Validation#
Validation rejects:
a dependency on a permission that is not defined;
a permission that depends on itself, or a dependency cycle;
a dependency whose scope namespaces do not include every scope namespace of the dependent permission; and
a role whose resolved permissions, after role extensions are applied, include a permission but not all of its direct and indirect dependencies.
The last rule means a role always lists every permission it grants, and a remove_permissions extension cannot remove a dependency that another permission on the role still needs. It applies to roles and role extensions in every file, regardless of the schema_version the file declares.
4. Casbin representation#
The renderer creates one g2 row for each direct dependency:
g2, act^content_libraries.edit_library_content, act^content_libraries.view_library
The renderer owns these rows and adds, adopts, and removes them the same way it handles p rows (ADR 0018, ADR 0025). model.conf and its matcher do not change.
For schema roles, the validation in section 3 already makes g2 rows redundant, because every role lists its dependencies. The rows are still rendered because:
Roles that do not pass through schema validation, such as roles stored only in the database and
prows that no schema declares, can still be missing a dependency. Theg2row grants the dependency, so a permission on such a role still works.The matcher already checks
g2, and existing installations already store these rows, so authorization decisions stay the same as before PR #538.The dependencies stay in the Casbin policy, where tools that read the policy, such as the
enforcementmanagement command, can see them.
5. Definition storage#
The loader stores each direct dependency as one row that links a permission definition to the permission it depends on, next to the definition tables from ADR 0025. Each row corresponds to one rendered g2 row, in the same way each stored role-permission grant corresponds to one p row. The row has no scope, because g2 rows have none.
Dependencies do not have their own source records. Only the file that defines a permission declares its dependencies, so a dependency’s source is the permission’s source. Two files that define the same permission with different dependencies are a base-definition conflict, which validation rejects (ADR 0031).
The renderer uses these rows to decide which g2 rows it owns:
A stored
g2row that matches a rendered one, such as a row loaded fromauthz.policybefore PR #538, is adopted without being rewritten.A stored
g2row that no schema declares stays in place and unattributed, like unmanagedprows.When a dependency leaves the schema, or its permission is removed, the renderer removes the dependency row and its
g2row in the same transaction.
6. API#
The role catalog (ADR 0028) returns each permission’s direct depends_on list. Clients compute indirect dependencies when they need them. Because of the role rule in section 3, a role’s listed permissions are the same as the permissions it grants, so the API does not need to separate direct and implied permissions.
7. UI behavior#
The UI uses depends_on in both directions when an administrator edits the permissions of a custom role:
When the administrator selects a permission, the UI also selects every permission it depends on, directly or indirectly.
When the administrator deselects a permission that other selected permissions depend on, the UI warns the administrator before deselecting it. The warning lists the permissions that will also be deselected. If the administrator confirms, the UI deselects the permission and every selected permission that depends on it, directly or indirectly. If the administrator cancels, nothing changes.
The UI computes the permissions that depend on a given permission by reversing the depends_on lists it received from the role catalog (section 6). The role rule in section 3 stays the authoritative check, so a request that leaves a permission selected without its dependencies is rejected by the Custom Roles API regardless of what the UI does.
Consequences#
New installations load library
g2rows again.Schema authors declare dependencies once, on the permission they belong to.
A schema that adds a permission to a role without its dependencies fails validation, including a
1.0file that lists a permission to which a1.1file has addeddepends_on.1.0files, and1.1files that do not usedepends_on, keep their current meaning, and1.0and1.1files can be loaded together.The repository ships a second JSON Schema file for
1.1, which must be kept in sync withauthz-schema-v1.jsonfor the fields they share.Tests check the validation rules and confirm that enforcement results match the explicit role permissions.
The Custom Roles API should apply the same role rule to roles that users create.
Rejected Alternatives#
Top-level permission_dependencies section#
A separate section would let any file add dependencies to a permission it does not own, which would require the override rules that ADR 0031 avoids for base definitions.
Dependencies as display metadata only#
The UI would select dependencies, but Casbin would have no g2 rows. The schema would then not be the full source for the Casbin policy.
Role inheritance#
Inheritance links roles, not permissions. It does not tell the UI which permissions to select together.