Page tree

Old Release

This documentation covers an old version of Fedora. Looking for another version? See all documentation.

Skip to end of metadata
Go to start of metadata

Overview

This module creates a REST API to assign new roles to identities and to query the roles already assigned on Fedora 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 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.

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 an authorization delegate that is aware of roles. One roles-aware authorization delegate is provided as a reference implementation, the Basic Roles-Based Authorization Delegate.

REST API

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

<path to Container>/fcr:accessroles

REST methods:

methoddescription
GETRetrieves the roles assigned on a resource.
GET w/effective parameterRetrieves the effective roles assigned on a resource, which may cascade from an ancestor role assignment.
POSTSets all the roles assigned on a resource.
DELETERemoves any roles assigned on a resource, such that effective roles are inherited again.

The POST and GET methods currently support a JSON structure (as Content-type application/json) where principals are mapped to lists of roles:

{
"johndoe" : [ "reader" ],
"janedoe" : [ "writer" ],
"freddoe" : [ "patron", "editor" ]
}

This module assigns one or more roles to a string, which is the name of a security principal. (java.security.Principal) The principals used in your repository environment must have unique names. You may use whatever principals you wish, but we recommend applying the appropriate standard for your environment. This module does not validate principal names.

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, 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.

Example Data

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

Inheritance of Effective Roles

Descendant resources inherit the roles assigned on ancestor resources only if they have no roles assigned themselves.  If a 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. Binary 1 of Container A only allows one principal to access the resource:  johndoe.  He will have admin privileges.  None of the ACLs on Container A will be applied; the binary will not inherit the EVERYONE => reader ACL on Container A.
  2. Container R, a child of Container Q, has its own content ACL:  janedee has admin privileges on Container R.  No one else has any access to the resource, not even the parent resource (Container Q) principals (EVERYONE and johndoe).
  3. Container T, a child of Container B, has no content ACLs.  So it inherits the ACLs of its most immediate ancestor with content ACLs:  Container B.  EVERYONE has reader privileges on Container T, and johndoe has admin privileges on the Container.
  4. Container V also inherits the ACLs of Container B (its most immediate ancestor with content ACLs).
  5. Container C has no content ACL;  it inherits the ACLs of the root resource, which is to say, nothing.  No one other than fedoraAdmin has any access to this Container.

Cascading Delete Permission

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

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

Authorization Operations and Example

(Editor's note: this section would make more sense within the Basic Roles 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 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 resource(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 resources, then a default set of role assignments is used. (see 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 resource. The roles for each matching principal in the 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 resource.
    • 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 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 resource checks are made. The authorization delegate is not consulted as admins have permission to do everything. 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)

Examples:

  1. Unauthenticated user requests to see Container A.
    1. The user is assigned the user principal "EVERYONE".
    2. The authorization delegate intercepts the request, gets the ACLs for Container A:  "EVERYONE" => "reader" and "johndoe" => "admin".
    3. The authorization delegate compares the user principal "EVERYONE" to the principals in 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 Container.
    4. The authorization delegate sees if the role "reader" can view the Container;  it can.
    5. The authorization delegate returns "yes", and the request proceeds.
  2. Unauthenticated user requests to see binary 1 on Container A.
    1. The user is assigned the user principal "EVERYONE".
    2. The authorization delegate intercepts the request, gets the ACLs for binary 1: "johndoe" => "admin".
    3. The authorization delegate compares the user principal "EVERYONE" to the principals in binary 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 Container B.
    1. The user is assigned the user principal "EVERYONE".
    2. The authorization delegate intercepts the request, gets the ACLs for Container B:  "EVERYONE" => "reader" and "johndoe" => "admin".
    3. The authorization delegate compares the principal "EVERYONE" to the principals in 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 Container.
    4. The authorization delegate sees if the role "reader" can delete the Container;  it cannot.
    5. The authorization delegate returns "no", and the request is denied.
  4. John Doe requests to update binary 1 on Container A.
    1. The user is assigned the user principals "johndoe" and "EVERYONE".
    2. The authorization delegate intercepts the request, gets the ACLs for binary 1:  "johndoe" => "admin".
    3. The authorization delegate compares the user principals "johndoe" and "EVERYONE" to the principals in binary's ACLs, and sees that "johndoe" matches.  The effective role for this request is "admin", the role paired with the principal "johndoe" on the Container.
    4. The authorization delegate sees if the role "admin" can update the Container;  it can.
    5. The authorization delegate returns "yes", and the request proceeds.
  • No labels

7 Comments

  1. Notes on Auth Documentation and Configuration:

    I found most of the functionality to work as outlined in the wiki documentation elsewhere. Some items (relevant to the setup, not the auth model itself) worth attention, though:

     

    1. The fact that some dependencies and changes in configuration are required for authz functionality should be specified. For example, adding Maven dependencies for fcrepo-authz, and adding relevant beans in Spring xml configuration file.
    2. fcrepo-webapp SanityCheckIT.java needs modification for response code when org.fcrepo.auth.ServletContainerAuthenticationProvider is in charge (currently the relevant test looks for 2xx).
    3. Some discrepancies in the supplied realm (fcrepo-weapp jetty-users.properties – e.g. the fedora admin role is supposed to be fedoraAdmin, and fedora user role is supposed to be fedoraUser).
    4. Granting an invalid role (e.g. 'reader' versus 'read') does not generate any HTTP warning (although a log message is produced). It would be helpful to have this sort of warning in place.
    5. Perhaps mention somewhere (or change this behavior if it's wrong) that although a user might not have permissions to view any objects etc, but can still access fcr:worksapces, fcr:namespaces etc. (To test this, try the example mentioned in the Http calls section w/ a call to /fcr:workspaces.)
    6. (For the rare case of users new to container managed authentication) Should specify that web.xml needs to have the <security-constraint> etc elements to specify roles.
    7. Small discrepancies in the wiki – e.g. the RESTful calls for auth should be made to fcr:accessRoles (camelcase) not fcr:accessroles.
    8. Overwriting permissions – perhaps return an 'item updated' text response (or specify in wiki that updating permissions means wiping out, not adding to/subtracting from previous permissions.).
    9. Perhaps highlight the cascade delete policy (in Cascading Delete Permissions section above). It might come as a surprise to some folks.
    10. Perhaps giving some curl examples might help (for new users). I've pasted a few commands below as an example.

    Unknowns: clustering; cascade performance in large hierarchical graph. . .

    HTTP API Examples:

    The following commands create and assign permissions for a node. The assumption is that a user with a fedoraAdmin role has been specified in a realm (e.g. in jetty-users.properties).

    In this example, this admin user is 'repo_admin', and the test user (with only read permissions) for the node is 'john'.

    curl -X POST http://localhost:8080/rest/test -u "repo_admin:password"  
    curl -X POST -H "Content-Type: application/json" -d '{"john" : [ "reader" ] }' http://localhost:8080/rest/test/fcr:accessRoles -u "repo_admin:password"
    curl http://localhost:8080/rest/test/fcr:accessRoles?effective -u "john:password"
    
    
    1. Thanks, Osman Din.

      #2 above, are you saying the test could be enhanced? or is the test somehow incorrect?
      #7 above, the documentation is correct, the code should be changed to not have a camel-case endpoint (https://www.pivotaltracker.com/story/show/61179680

      Greg Jansen, comments on the above points? Shall we generate some tickets?

       

  2. Thanks Osman! I will go make my tickets now.

  3. FYI, we've been discussing how we use roles here at UNC this week and we created a new use case document. I think there are some enhancements we'll want to do for the roles API in the next release, namely:

    • For any role assignment, ability to specify always inherit. This would make a role assignment effective for all sub-nodes, i.e. a role that cannot be revoked except at the same ACL. Use case might be assignment of a collection administrator role.
    • For any role assignment, ability to specify never inherit. This role would be local to the node, i.e. not considered effective at sub-nodes. Use case might be where the public can see a collection, but nothing within it. (Sort of a convenience, in that you don't need to override the role at every child node.)

    These are just initial ideas for satisfying these cases.

    1. The current (hard-coded) default is always inherit, correct?  In which case, the task would be to add a switch to allow changing the default to never inherit, then implementing the code to look for the switch, and apply the node enforcement appropriately.

      One question about never inherit:  what is the default ACL on nodes with no ACL set, then?  the ACL of the root node (in which case, never inherit is really inherit only from root node)?

      1. Hey Scott, the current hard-coded default is "inherit until ACL". So assignments are inherited down the tree until another ACL is found. At that point the assignment would need to be repeated. So "always inherit" would mean that the assignment inherits right past another ACL. The always inherited assignment cannot be blocked.

        One neat side effect of this is that we could assign repository-wide roles at the root node, once it supports an ACL..

        There are other ways to handle this functionality and give people the ability to groom their tree of ACLs. I'm open to ideas.

        The ACL on the root node will be settable in a future release. When the root ACL is not set, a default ACL will be used, which assigns nobody any roles, i.e. fedoraAdmin has to set the root node ACL the first time.

        In the case of "never inherit", that refers to a particular assignment of a role. For instance, if I assign you a reader role on a collection, but specify that the assignment is never inherited, then you do not get reader of child nodes in that collection, only reader on the collection node itself.

         

         

  4. Greg Jansen, can you integrate the API documented here into the top-level Fedora REST API documentation?

    Also, we will want to integrate the AuthZ API into the root page of the F4 webapp.