Configuring User Authorization
ĀYŌDÈ controls access through realms, roles, and privileges. Realms organize administrative boundaries, roles collect privileges for a responsibility, and users receive those privileges through role membership. Each privilege specifies an operation and the conditions under which it applies.
To configure access, begin with what a person needs to do and where they need to do it. Translate that requirement into memberships and privileges, then verify both the intended access and its boundaries using a representative account. This guide explains that process for institutional IT teams responsible for staff and student access.
- Authentication and authorization
- The terms used in access configuration
- Separate the realm choices
- Configure access from a concrete requirement
- Diagnose unexpected access
Authentication and authorization
Authentication establishes who is signed in. Authorization determines whether that person may perform a particular operation against a particular resource. A successful sign-in does not establish permission to view student files, manage a section, or change another user’s access.
The terms used in access configuration
| Term | Meaning |
|---|---|
| Principal | The authenticated user whose access is being evaluated. |
| Realm | An administrative boundary in a hierarchy, such as a district, school, or class section. |
| Root realm | A realm with no parent. This is a property of the hierarchy. |
| Topmost realm | The highest realm in a branch where a particular user has membership. Different users can have different topmost realms. |
| Realm membership | The association between a user and a realm. It is separate from membership in a role. |
| Role | A named collection of privilege associations for a responsibility. Its name alone grants no access. |
| Role membership | The association that gives a user the privileges attached to a role. |
| Privilege action | A specific operation, such as reading a file or adding a role member. |
| Privilege definition | An action combined with a target realm, depth, scope, and predicate. A realm owns this definition. |
| Privilege association | The attachment of a privilege to a role, with an access rule of allow or deny. |
| Scope | The operation’s supported access category: none, self, or realm. |
| Predicate | An additional condition that must be satisfied, such as membership in the relevant team. |
| Asserted realm | The realm context in which the user is acting for a request. |
| Effective access | The result after considering the user’s applicable role privileges and the conditions of the operation. |
flowchart TD
user["Principal<br/>The signed-in user"]
realm["Realm<br/>Administrative boundary"]
role["Role<br/>A responsibility"]
association["Privilege association<br/>Allow or deny"]
privilege["Privilege definition"]
action["Action<br/>What operation?"]
reach["Target realm and depth<br/>Where, and how far below it?"]
scope["Scope<br/>Self, realm, or none"]
predicate["Predicate<br/>What additional condition?"]
evaluation["Effective access<br/>For this operation and resource"]
user -->|realm membership| realm
user -->|role membership| role
role --> association
association --> privilege
privilege --> action
privilege --> reach
privilege --> scope
privilege --> predicate
association -.-> evaluation
action --> evaluation
reach --> evaluation
scope --> evaluation
predicate --> evaluation
user -.->|acts in an asserted realm| evaluation
The diagram follows one role’s privilege association. Effective access also considers the user’s other applicable roles and the operation’s requirements.
Creating a privilege definition does not assign it to a user. The definition must be associated with a role, and the user must be a member of that role. Similarly, realm membership alone does not confer every permission in that realm; default-role rules may separately assign privileges through roles.
A realm pathname URN names a realm by its position in the hierarchy. For
example, urn:ayode:realm:/district/north-school/section-a identifies Section A
under North School in the district. The prefix urn:ayode:realm: identifies the
kind of name; the pathname after it shows the parent and child relationships.
Use the realm’s configured pathname, rather than guessing it from its display
name. The pathnames in this guide are illustrative.
Separate the realm choices
The word realm appears in several configuration fields because those fields answer different questions.
| Realm context | Question it answers |
|---|---|
| Owning realm | Where is this role or privilege definition administered? |
| Privilege target realm | Where does the privilege’s permitted reach begin? |
| Applicable realm | At which realm is that privilege applicable after its depth is considered? |
| Asserted realm | In which context is the user making this request? |
| Resource’s realm | Where does the resource involved in this operation belong? |
flowchart TD
district["District<br/>Owning realm for the role and privilege"]
definition["Privilege definition<br/>Target: North School<br/>Depth: 1"]
north["North School<br/>Target realm and asserted realm<br/>Distance from target: 0"]
section["Section A<br/>Applicable realm and resource's realm<br/>Distance from target: 1 — within reach"]
lab["Lab Group<br/>Distance from target: 2 — beyond depth 1"]
user["User with membership in North School"]
file["Shared file being read"]
district -->|parent of| north
district -.->|owns the configuration| definition
definition -.->|reach begins here| north
user -.->|asserts this context| north
north -->|one level down| section
section -->|one more level down| lab
section -.->|contains| file
classDef within fill:#302c41,stroke:#a8e5ff,color:#eeeef1,stroke-width:2px;
classDef outside fill:#242035,stroke:#747283,color:#eeeef1,stroke-dasharray:5 5;
class north,section within;
class lab outside;
In this example, the district administers the configuration, the user acts in
North School, and the file belongs to Section A. With North School as the
target, depth 1 includes North School and Section A, one level below it. The
Lab Group is two levels below the target and is outside this privilege’s reach.
The owning realm does not establish the starting point for counting depth.
Being within reach still requires the action, scope, and conditions to match.
These realms can coincide, but they are not interchangeable. The realm that owns a role is not, by itself, a boundary around every privilege in that role. The privilege’s target and depth determine its reach, subject to scope, predicate, and the operation’s own requirements.
A user can hold several roles across an institution’s realm hierarchy. An applicable privilege from another role can continue to authorize an operation after you narrow or remove a grant from the role you are editing. Review the user’s other roles as part of every access reduction.
Target realm and depth
Consider a district with two schools. North School contains Section A and Section B; Section A contains a Lab Group. South School is a sibling of North School. These names and arrangements are illustrative.
For a privilege targeted at North School, depth limits its reach as follows:
| Depth | Realms within reach |
|---|---|
0 |
North School only. |
1 |
North School and its immediate children, Section A and Section B. |
2 |
Those realms plus their children, including the Lab Group. |
flowchart TD
district["District<br/>Outside the target branch"]
north["North School — TARGET<br/>Distance 0<br/>Included at depth 0, 1, or 2"]
south["South School<br/>Sibling — outside the target branch"]
sectionA["Section A<br/>Distance 1<br/>Included at depth 1 or 2"]
sectionB["Section B<br/>Distance 1<br/>Included at depth 1 or 2"]
lab["Lab Group<br/>Distance 2<br/>Included at depth 2"]
district --> north
district --> south
north -->|one level down| sectionA
north -->|one level down| sectionB
sectionA -->|one more level down| lab
classDef target fill:#302c41,stroke:#a8e5ff,color:#eeeef1,stroke-width:3px;
classDef child fill:#302c41,stroke:#9a79ee,color:#eeeef1;
classDef outside fill:#242035,stroke:#747283,color:#eeeef1,stroke-dasharray:5 5;
class north target;
class sectionA,sectionB,lab child;
class district,south outside;
Count downward from the target, starting at zero. A depth setting includes all
levels up to that number; depth 2 includes distances 0, 1, and 2.
Increasing depth does not reach upward to the district or sideways to South School. Depth measures links in the actual realm hierarchy, so an intermediate realm changes how far a grant reaches. A new descendant within the configured depth can also fall within an existing privilege’s reach.
Scope is a separate choice
| Scope | How to interpret it |
|---|---|
none |
The action uses no self-versus-realm resource distinction. Authorization and realm context still apply; this does not mean unrestricted access. |
self |
The operation applies to the user’s own resource or participation, as defined by that operation. |
realm |
The operation uses access within its applicable realm context. Predicates and other resource conditions can still restrict it. |
Only scopes listed for a particular action are valid for that action. Scope
matching is exact: a realm grant does not automatically replace a required
self grant. A workflow may need separate grants for both.
Depth selects the realms where a privilege can apply. Scope describes the
relationship between the user and the resource within that reach. Increasing
the depth of a self privilege does not turn it into permission to access other
users’ resources. Where an operation supports self in a descendant realm, the
resource must still satisfy that operation’s definition of the user’s own
resource, and the selected realm context must also be valid.
Conversely, a realm privilege with depth 0 applies only at its target realm;
it does not reach child realms. Neither authorization scope is the educational
scope in a course’s scope and sequence.
Predicates express additional conditions
A predicate can require the user to have a relationship with the resource, such as being a member of the team involved in the request. The platform provides a catalog of supported predicates. These are selected conditions, not arbitrary expressions supplied by an institutional administrator.
The always-true predicate, written ⊤ and identified by
urn:ayode:privilege-predicate-expression:top, imposes no additional relationship
condition. It does not bypass action, realm, scope, or other checks. The
always-false predicate, ⊥, never authorizes a request; it is not an explicit
deny rule.
Relationship predicates require context supplied by the operation, such as the team being accessed. Choose a predicate supported by that operation. Attaching a team predicate to an unrelated action does not make the platform infer a team relationship.
Allow and deny
An applicable allow association supplies permission when its conditions are
satisfied. A matching deny takes precedence over a matching allow, including
an allow from another role. A deny must still match the action, realm reach,
scope, and predicate conditions; it is not a universal account block.
Removing an association removes that rule. It does not create a deny, and another applicable allow may remain. Removing a deny can likewise expose access already permitted by another role. Inspect the complete result after either change.
Configure access from a concrete requirement
1. Describe the responsibility
Write down who needs access, which operations they need, which resources are involved, and where the access must stop. Identify who approves that access and when it should be reviewed.
For example: “Selected North School staff may read files in North School’s shared realm storage and its immediate class sections. This responsibility does not include writing files, reading personal user storage, or accessing South School.”
This describes one responsibility, not the staff members’ entire access profile. Any other role they hold must be considered separately.
2. Confirm the hierarchy and administrative authority
Identify each realm by its configured pathname URN and confirm its parent relationships. In the example:
| Realm | Pathname URN |
|---|---|
| District | urn:ayode:realm:/district |
| North School | urn:ayode:realm:/district/north-school |
| Section A | urn:ayode:realm:/district/north-school/section-a |
| Lab Group | urn:ayode:realm:/district/north-school/section-a/lab-group |
| South School | urn:ayode:realm:/district/south-school |
The pathnames make Section A’s position one level below North School visible.
Confirm that the institution’s actual hierarchy has this structure before
choosing depth 1. Select the realm context in which the administrator is
authorized to make each configuration change.
The administrator needs privileges to perform the changes: creating roles, creating privileges, associating privileges with roles, and managing memberships are separately protected operations. Permission to use a resource does not itself grant permission to administer access to it.
Creation of a root realm and assignment of its initial administrator are platform administration operations. An institutional administrator should begin with the institution’s provisioned realm and delegated authority.
3. Define the role and its privileges
For the example, create or reuse a role named Learning Resource Reader with a description recording its purpose. The following is one privilege definition and its intended association:
| Setting | Example value |
|---|---|
| Owning realm | North School — urn:ayode:realm:/district/north-school. |
| Action | Read shared realm files — /realm-file-system/file/read. |
| Target realm | North School — urn:ayode:realm:/district/north-school. |
| Depth | 1. |
| Scope | realm. |
| Predicate | Always true, ⊤. |
| Role association | allow on Learning Resource Reader. |
The action selects shared realm file storage. It does not authorize reading personal user storage. The target and depth restrict which realms this grant covers; the role’s name does not enforce those restrictions.
Here North School owns the configuration as well as being its target; in the earlier diagram the district owned it. Both examples count depth from the target, North School.
This single privilege permits reading file contents. A usable browsing workflow may also require permission to list directories or view file versions. Include the additional actions needed for the intended task, then verify the complete task with a representative account.
4. Assign users and choose any automatic assignments
Establish the required realm membership and add the selected users to the role. Record which assignments are manual and which are supplied automatically.
| Assignment mechanism | Basis for assignment |
|---|---|
| Manual role membership | An administrator explicitly assigns a user to a role. |
| Realm default role | A configured rule assigns a role based on membership in the realm, regardless of how that realm membership was obtained. |
| Identity-based provisioning | A configured identity rule, such as an email-address match, can provision realm membership and an optional role. |
Use a default role only for access intended for every member covered by that realm rule. The example’s “selected staff” requirement calls for explicit or appropriately targeted assignment, rather than a school-wide default that also includes students.
An active provisioning rule may restore an assignment you remove manually. Include the rule’s owner in changes to automatically assigned access, and verify the resulting memberships after provisioning has been evaluated.
5. Verify access as a representative user
Inspect the configured privileges and role memberships, then exercise the actual workflow using a representative account. An administrator’s account may have additional grants that conceal a missing privilege or an unintended route to access.
For the Learning Resource Reader example, the following results describe this role alone, assuming valid authentication, the appropriate asserted realm, and no additional grants or denials from other roles:
| Check | Expected result from this role |
|---|---|
| Read a shared realm file in North School | Permitted. |
| Read a shared realm file in Section A | Permitted by depth 1. |
| Read a shared realm file in the Lab Group | Not permitted; it is two levels below North School. |
| Read a shared realm file in South School | Not permitted; it is outside the target branch. |
| Write or delete a shared file | Not permitted by the read action. |
| Read another user’s personal file | Not permitted by the shared realm file action. |
Test the forbidden cases as well as the successful ones. For conditional privileges, test both a user who satisfies the predicate and one who does not. If someone legitimately holds an additional role, document how that changes the expected result rather than treating one role as their complete access.
Privilege matrices help explain grants and their origins. They do not replace testing a specific resource operation: relationship predicates and business conditions can still affect the result. For example, participating in a chat also depends on eligibility for that conversation and current thread membership.
6. Review changes and revoke obsolete access
Review access when staff change responsibilities, students change enrollment, realm structure changes, or a temporary assignment ends. Check both the departing responsibility and any continuing responsibilities before changing shared roles. Editing a role’s privileges affects all its members.
Removing a realm default-role rule does not revoke existing user-role memberships. To withdraw automatically assigned access, change the provisioning rule as appropriate, remove the obsolete memberships or privilege associations, and verify that other roles do not retain the access. Recheck after subsequent provisioning activity.
Removing access to one institutional responsibility is also distinct from disabling a platform account or deleting a user’s data. Choose the operation that matches the intended change.
Diagnose unexpected access
Work through the attempted task in this order:
- Confirm the user can sign in. Adding privileges does not repair sign-in.
- Check the asserted realm and the resource’s realm. Membership context and privilege reach are separate requirements.
- Identify the action the user is trying to perform and its supported scope.
- Inspect the target realm, depth, and predicate on the applicable definitions.
- Inspect every applicable role and any matching deny. For excess access, look for another allow and for automatic role assignment.
- Check the operation’s other conditions, such as enrollment, resource state, or thread membership. Having a privilege does not remove these requirements.
For support, record the affected user, the task, the selected realm’s pathname URN, the resource’s realm, the expected result, and the message shown. Include a reference identifier if one is displayed. Do not include passwords. Check the reported conditions before granting broader access.
Related guidance
Courses and Lessons explains the academic structures used in institutional planning.