...

This module creates a REST API to assign new roles to identities and to query the roles already assigned on Fedora objects resources.

In roles-based access control, users or groups are not granted specific actions on resources; rather, users and groups have roles assigned to them on resources, and these roles are mapped onto permitted actions elsewhere. This makes it much easier to manage permissions globally: rarely will masses of objects need resources need to be updated if their permissions change. Only the role-to-permission mapping will be updated. Role-based access control is a common pattern in security, providing extensible role-specific behavior while retaining straightforward management.

...

The module adds another REST endpoint to every Fedora object Container and datastream path NonRdfSourceDescription path. The URL pattern is as follows:

<path to object>Container>/fcr:accessroles

REST methods:

...

Fedora uses a principal named "EVERYONE" to represent the general public. This principal is added to every incoming web request. You may assign any role to the EVERYONE principal.

By default roles , role names are not validated, since the module does not define the set of role names that may be assigned in Fedora. However, you may configure a set of specific roles and then the API will validate roles.

...

root/  (default content roles, i.e. no roles for anyone)
├── objectContainer A  (EVERYONE => reader; johndoe => admin)
│   ├── datastreamNonRdfSourceDescription 1  (johndoe => admin)
│   └── objectContainer Q  (EVERYONE => reader; johndoe => admin)
│       └── objectContainer R (janedee => admin)    
├── objectContainer B  (EVERYONE => reader; johndoe => admin)
│   └── objectContainer T
│       └── objectContainer V
└── objectContainer C 

Inheritance of Effective Roles

Descendant nodes resources inherit the roles assigned on ancestor nodes resources only if they have no roles assigned themselves.  If a node resource has any roles assigned, these assignments override ALL ancestor assignments.

The following cases, based on the example data above, demonstrate how inheritance plays out.

1. Datastream 1 NonRdfSourceDescription 1 of object Container A only allows one principal to access the noderesource:  johndoe.  He will have admin privileges.  None of the ACLs on object Container A will be applied; the datastream will NonRdfSourceDescription will not inherit the EVERYONE => reader ACL on object Container A.
2. Object Container R, a child of object Container Q, has its own content ACL:  janedee has admin privileges on object Container R.  No one else has any access to the noderesource, not even the parent node resource (object Container Q) principals (EVERYONE and johndoe).
3. Object Container T, a child of object Container B, has no content ACLs.  So it inherits the ACLs of its most immediate ancestor with content ACLs:  object Container B.  EVERYONE has reader privileges on object Container T, and johndoe has admin privileges on the objectContainer.
4. Object Container V also inherits the ACLs of object Container B (its most immediate ancestor with content ACLs).
5. Object Container C has no content ACL;  it inherits the ACLs of the root noderesource, which is to say, nothing.  No one other than fedoraAdmin has any access to this objectContainer.

Cascading Delete Permission

When deleting a noderesource, the user must have an effective role that will allow them to delete ALL the descendant objects Containers under the noderesource. (datastreamsNonRdfSourceDescriptions, child objectsContainers, etc..)  If any descendant node resource cannot be deleted, then the entire delete transaction will be denied.

For example, in the graph shown above, the principal johndoe cannot delete object container A, although he has an admin role on it and its datastreamNonRdfSourceDescription;  that is because he does not have an effective role on object Container R, the noderesource's grandchild, that will permit him to delete it.  If he wants to delete object Container A, he will first have to ask janedee to delete object Container R.

Authorization Operations and Example

...

• Container Authentication: A user comes into the system.  They are assigned a user principal:
  
  • If they authenticate through some authentication gateway, then their principal may be generated from some of the person's attributes;
  • Whether they authenticate or not, the request will always acquire an "EVERYONE" principal.
• Fedora Principal Provider extensions: Principal provider extensions may bring in more principals after authentication, such as groups, from sources like LDAP.
• Fedora Roles Authorization Delegate Queries for Assigned Roles on Content: What roles have been assigned?
  
  • The authorization layer queries the requested repository objectresource(s) for any content-assigned roles.
  • If none are found locally, then it will query each ancestor in turn until role assignments are found.
  • If no role assignments are found in the tree of objectsresources, then a default set of role assignments is used. (see object Container C above)
• Fedora Roles Authorization Delegate - Role Resolution: What roles does this request have?
  
  • The set of principals in the request are compared to the principals in the ACLs on the objectresource. The roles for each matching principal in the object Container ACL are the effective roles for the user.
  • At this point we have the effective access roles for this operation
• Fedora Roles Authorization Delegate - Policy Enforcement: Does this role have permission to perform the requested action?
  
  • Note: The Fedora Authorization Delegate is an extension point, so enforcement will vary by the chosen implementation. We assume that installations will combine the access roles module with a roles-based authorization delegate.
  • The effective roles, assigned to the user on the content, are used to determine if the user has permission to perform the action on a given objectresource.
  • Basic Roles authorization delegate implementation does permission checks in java code:
    
    • Permission is determined by evaluating at a minimum the effective roles for the user on the object resource in question, and the action requested. 
  • In other roles-based authorization delegate implementations, more factors may also enter into the equation to determine permission.
• The authorization delegate will return a response to ModeShape, which will throw an exception to Fedora if access has been denied.
• Fedora will respond with a 403 if the given REST operation is denied.
  
  
• The one exception to this process is the fedoraAdmin container role. If the request has a fedoraAdmin user role (in the container), then no object resource checks are made. The authorization delegate is not consulted as admins have permission to do everything. Objects Resources will never have the fedoraAdmin role explicitly assigned to them, since it is a container role and not a content role. (e.g. a tomcat user role)

...

1. Unauthenticated user requests to see Object Container A.
   
   1. The user is assigned the user principal "EVERYONE".
   2. The authorization delegate intercepts the request, gets the ACLs for object Container A:  "EVERYONE" => "reader" and "johndoe" => "admin".
   3. The authorization delegate compares the user principal "EVERYONE" to the principals in object Container A's ACLs, and sees that "EVERYONE" matches.  The effective role for this request is "reader", the role paired with the principal "EVERYONE" on the objectContainer.
   4. The authorization delegate sees if the role "reader" can view the objectContainer;  it can.
   5. The authorization delegate returns "yes", and the request proceeds.
2. Unauthenticated user requests to see datastream 1 NonRdfSourceDescription 1 on Object Container A.
   
   1. The user is assigned the user principal "EVERYONE".
   2. The authorization delegate intercepts the request, gets the ACLs for datastream 1NonRdfSourceDescription 1: "johndoe" => "admin".
   3. The authorization delegate compares the user principal "EVERYONE" to the principals in datastream 1NonRdfSourceDescription 1's ACLs, but does not find a match.
   4. The authorization delegate returns "no", and the request is denied.
3. Unauthenticated user requests to delete Object Container B.
   
   1. The user is assigned the user principal "EVERYONE".
   2. The authorization delegate intercepts the request, gets the ACLs for object Container B:  "EVERYONE" => "reader" and "johndoe" => "admin".
   3. The authorization delegate compares the principal "EVERYONE" to the principals in object Container B's ACLs, and sees that "EVERYONE" matches.  The effective role for this request is "reader", the role paired with the principal "EVERYONE" on the objectContainer.
   4. The authorization delegate sees if the role "reader" can delete the objectContainer;  it cannot.
   5. The authorization delegate returns "no", and the request is denied.
4. John Doe requests to update datastream 1 NonRdfSourceDescription 1 on Object Container A.
   1. The user is assigned the user principals "johndoe" and "EVERYONE".
   2. The authorization delegate intercepts the request, gets the ACLs for datastream 1NonRdfSourceDescription 1:  "johndoe" => "admin".
   3. The authorization delegate compares the user principals "johndoe" and "EVERYONE" to the principals in datastreamsNonRdfSourceDescription's ACLss ACLs, and sees that "johndoe" matches.  The effective role for this request is "admin", the role paired with the principal "johndoe" on the objectContainer.
   4. The authorization delegate sees if the role "admin" can update the objectContainer;  it can.
   5. The authorization delegate returns "yes", and the request proceeds.