...

This module does not define any specific roles or enforce permissions granted to roles. For roles to be effective, this module must be configured alongside a Policy Enforcement Point (PEP) an authorization delegate that is aware of roles. Two One roles-aware PEPs are authorization delegate is provided as a reference implementationsimplementation, the Basic Roles-Based PEP and the XACML PEPAuthorization Delegate.

REST API

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

...

(Editor's note: this section would make more sense within the Basic Roles PEP auth delegate documentation/page)

Order of operation:

• 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 Factory ExtensionsProvider extensions: Principal factory provider extensions may bring in more principals after authentication, such as groups, from sources like LDAP.
• Fedora Roles PEP Authorization Delegate Queries for Assigned Roles on Content: What roles have been assigned?
  
  • The authorization layer queries the requested repository object(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 objects, then a default set of role assignments is used. (see object C above)
• Fedora Roles PEP 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 object. The roles for each matching principal in the object ACL are the effective roles for the user.
  • At this point we have the effective access roles for this operation
• Fedora Roles PEP Authorization Delegate - Policy Enforcement: Does this role have permission to perform the requested action?
  
  • Note: The Fedora PEP 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 PEPauthorization 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 object.
  • Basic Roles PEPauthorization 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 in question, and the action requested. 
  • In other roles-based PEP authorization delegate implementations, more factors may also enter into the equation to determine permission.
• The PEP 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 checks are made. The PEP authorization delegate is not consulted as admins have permission to do everything. Objects 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 A.
   
   1. The user is assigned the user principal "EVERYONE".
   2. The PEP authorization delegate intercepts the request, gets the ACLs for object A:  "EVERYONE" => "reader" and "johndoe" => "admin".
   3. The PEP compares authorization delegate compares the user principal "EVERYONE" to the principals in object 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 object.
   4. The PEP sees authorization delegate sees if the role "reader" can view the object;  it can.
   5. The PEP returns authorization delegate returns "yes", and the request proceeds.
2. Unauthenticated user requests to see datastream 1 on Object A.
   
   1. The user is assigned the user principal "EVERYONE".
   2. The PEP intercepts authorization delegate intercepts the request, gets the ACLs for datastream 1: "johndoe" => "admin".
   3. The PEP compares authorization delegate compares the user principal "EVERYONE" to the principals in datastream 1's ACLs, but does not find a match.
   4. The PEP returns authorization delegate returns "no", and the request is denied.
3. Unauthenticated user requests to delete Object B.
   
   1. The user is assigned the user principal "EVERYONE".
   2. The PEP intercepts authorization delegate intercepts the request, gets the ACLs for object B:  "EVERYONE" => "reader" and "johndoe" => "admin".
   3. The PEP compares authorization delegate compares the principal "EVERYONE" to the principals in object 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 object.
   4. The PEP sees authorization delegate sees if the role "reader" can delete the object;  it cannot.
   5. The PEP returns authorization delegate returns "no", and the request is denied.
4. John Doe requests to update datastream 1 on Object A.
   1. The user is assigned the user principals "johndoe" and "EVERYONE".
   2. The PEP intercepts authorization delegate intercepts the request, gets the ACLs for datastream 1:  "johndoe" => "admin".
   3. The PEP compares authorization delegate compares the user principals "johndoe" and "EVERYONE" to the principals in datastreams's ACLs, and sees that "johndoe" matches.  The effective role for this request is "admin", the role paired with the principal "johndoe" on the object.
   4. The PEP sees authorization delegate sees if the role "admin" can update the object;  it can.
   5. The PEP returns authorization delegate returns "yes", and the request proceeds.