Overview

Use Cases

...

Container Authentication

User authentication is generally handled by the Servlet container, i.e. Tomcat, JBoss AS, Jetty, etc. Authenticated requests will arrive at Fedora servlets with a non-null values for getRemoteUser() and getUserPrincipal().

Users authenticated in this way will have user roles of either fedoraUser or fedoraAdminFedora users may have the following servlet container roles.

• fedoraAdmin - Grants blanket superuser permissions to the the Fedora repositoryfedoraUser - Grants permissions that are specific to the user or their principals, see authorization below. Bypasses the configured policy enforcement point (PEP).
• fedoraUser - The policy enforcement point (PEP) grants permissions on the basis of this authenticated user and the credentials on the request.
• fedoraProxy - The policy enforcement point (PEP) grants permissions on the basis of end-user security credentials that are forwarded via extended request headers.

See the overview on configuring servlet container authentication for more details.

Additional Security Principals

Fedora can authorize actions on the basis of a user name. Access may also hinge on additional security principals that are specific to an organization. These principals are often based on attributes coming with the request from Shibboleth, LDAP, CAS, etcdatabases and other sources. . Additional principals can be supported included in Fedora authorization by implementing the a PrincipalFactory interface. A PrincipalFactory examines Servlet requests and returns a set of additional principals for authorization. Example principals might Examples include a named IP range, an affiliation or group from a Shibboleth SP header, principals extracted from a SAML payloads, etc.. Fedora provides a configurable HeaderPrincipalFactory that extracts principals from headers.

Authentication of Third-Party Applications (OAuth)

Applications can be authenticated by means of token credentials delivered through the OAuth protocol. A user with the fedoraAdmin role may authorize application access without any limits upon scope, including access equivalent to the fedoraAdmin role. A user with the fedoraUser role can only grant tokens within a scope that is limited by their own user credentials, since the application will only be able to act on their behalf. For specifics see the OAuth section below.

Establishing JCR Sessions

All requests to the JCR repository that underlies Fedora come through a JCR Session. The JCR Session results from JCR authentication and contain security context that allows the repository to make the most granular Fedora authorization decisions downstream. JCR sessions are tied to every Fedora REST request by means of an InjectedSession annotation on resources. This annotation will bring in a JCR Session from a SessionProvider that in turns get the Session from a SessionFactory. During Fedora transactions a JCR Session saved with the transaction. Sessions in transactions will remain open until the transaction is closed or the maximum time between requests is reached.

JCR authentication is based on ServletCredentials that are passed through from the REST endpoint. The place to start looking at this is the SessionFactory, which retrieves the transaction session or formulates a repository login attempt from the servlet request. Repository logins are based on a extensible credentials object. In ModeShape logins may be implemented by many implementations of an AuthenticationProvider interface. Fedora includes an ServletAuthenticationProvider that checks requests for a Fedora user role of either fedoraUser or fedoraAdmin before permitting Session creation.

Authorization (DRAFT)

Fedora 4 will intercept JCR operations in order to enforce policies that are based on the Fedora object model and other node characteristics. While a single Fedora API call may span several JCR operations, these will be joined by a JCR transaction and may all fail together due to a permission check.

Policies will be stored in the repository attached to or in some (likely hierarchical) relationship to the nodes that they govern. Many nodes may attach the same named policy.

Pluggable ModeShape AuthorizationProviders

A custom SecurityContext class can implement the existing AuthorizationProvider  or AdvancedAuthorizationProvider interfaces to implement specialized security checks through the hasPermission method. 

Principal Discovery

Principals used in ACLs

ModeShape has a pending pull request that implements part of the Access Control spec from JCR 2.0 (MODE-1920). Their implementation includes defined internal node properties and API for manipulating access control lists in the JCR repository. These are features of objects that are only accessed by clients through the AccessControlManager API.

• ModeShape Question: How best to store roles and policies within the repository? (normal nodes/properties or behind the AccessManager API)

XACML PEP AuthorizationProvider

• This provider would delegate authorization decisions to a XACML PDP.
• Policies might be stored in the repository tree (see JCR 2.0 16.3 and JBossLDAPPolicyLocator as an example)
• Standard and customized XACML attribute mappings could be stored in the repository. (JCR query, data type, attribute ID)
  
  • Write an "attribute finder" based on relative JCR XPath.
• Roles could be assigned to principals on Fedora object nodes. (Probably should involve an upstream ModeShape change to AccessManager.)
• Best implemented against MODE-1920 (a pending pull request for 3.4)
  
  • Gives us a standard place to store ACLs on nodes (limited to user => permission sets)
• Best for enforcement policies based on Fedora structures, i.e. policies govern CRUD on the nodes/properties of the Fedora object
• More security checks, but less complexity (consider SPARQL update, for instance)
• It's the JCR way, secures the JCR API as well
• Cannot block the whole Fedora API method before execution (but we have transactions?)

Option: Internal PDP vs. External

• Use JCR API for attribute lookups
• Less penalty for light authZ requests (i.e. use more attribute lookups based on Fedora object model)
• ??

Relevant Links

• JCR 2.0 Access Control Management
• MODE-1920 Pull Request (ACM)
  
  • persistence of access control lists that tie principals to a set of permissions
• ModeShape AuthorizationProvider interface
• Apache Shiro (framework of interest)
  

Possible Components

• JBoss XACML Engine
• JBoss SAML PDP endpoint (takes SAML payload + XACML request over SOAP)
• PEP Interceptor for Fedora REST API (intercepts JAX-RS)
• Filesystem Connector (configures JCR access to live policies folder)
• Security attributes source (typically configured at container level, e.g. Shibboleth)
  • Can we contain this variability using Principals? Installers configure or write their own serializable Principal objects, based on their attribute source?
• Some useful reference implementations of Fedora authorization policy

Requirements

• Support a fedora admin container role - Reasonable performance is important when intercepting every request. In addition to performance optimizations, the PEP should allow a bypass method for requests considered pre-authorized for all repository actions by virtue of some container role.
• Repository admin should be able to update access policy on his/her items
• Content owner should be able to update access policy on his/her items
  
  • Who is the content owner? Is this a feature of the RBAC profile (owner as role) or a general authorization feature? Or both? (I think owner is probably a role)
  • If we define a Fedora owner property, then we have to restrict updates to it as well.
• Support permission of specific actions, such as patch SPARQL update, as well as generic actions, like create, read, update and delete.
  • Fedora API may not be granular enough in all cases, modifyDatastreams is in the API, but some of the datastreams might be restricted.
• Access should be controlled when an item is searched.
  
  • Need specifics here.  What metadata is protected on these items? How will we facilitate end-user authorization requests without providing some metadata?
• Access should be controlled when resource is requested directly
• Allow resources to be protected at the jcr node level
  
  • Do we want policy language to reflect the Fedora API or the Fedora object model?
    • The object model. The object model is the common set of notions for the entire repository. It is entirely plausible that parties will introduce new APIs, and we don't want to incur or inflict the cost of rewriting au th code. (  A. Soroka )
• Allow users to authenticate via Shibboleth, CAS, LDAP.
  
  • Yes, but this should be a container concern.  It would be great if LDAP user metadata could be packaged as SAML for the PEP.
• Support for users granting permissions to applications via OAuth. (see below)
• Support for decision caching ( JBoss XACML decision cache )

OAuth Support

Users that wish to authorize other applications to act on their behalf will be able to do so via the OAuth endpoint. So policy-based restrictions on the user role will apply equally to token-based requests.

Which is a requirement?

• The application using the OAuth can never exceed the current authorizations of the user that created the token. (Permission implies the ability to grant permission to an app.)
• or
• The OAuth token can only be authorized by an "owner", i.e. someone authorized to grant permissions generally.

Users will want to limit the scope within which they authorize these applications:

• to particular parts of the repository hierarchy
• to a particular set of well defined actions
• to a time frame

Note that JCR 2.0 privilege discovery might align well with OAuth scopes.

Reference Profile: Role-Based Access Control (RBAC)

One way to implement XACML authorization is to write policies around user roles, i.e. recognizable sets of permissions. This separates the determination of user roles from the policies that determine permitted actions. Fedora 4 beta ships with a RBAC reference profile. It consists of a set of role-based XACML policies and metadata conventions for assigning roles within the repository on the basis of the authenticated request attributes.

Requirements

• Role assignment can be based of Shibboleth supplied x.520 attributes (Are there useful CAS attributes other than username? Do CAS implementations use LDAP, for instance?)
• Support for inheritance of roles assigned in the repository tree.
• Support for override of inherited roles at any object level.
• Support for policies with additive permissions (role B policy has all permissions of role A policy)  
• Examples of custom attributes being used in policies (a publication flag or embargo date, for instance)
• Support for indexing all the roles assigned to an object (Sequencer that updates a derived property in JCR?)

Authorization Example: Modify Datastreams

Inputs:

• REST path (and translated as JCR path)
• list of datastreams to delete
• new datastreams as Multipart

JCR operations:

• zero or more remove node calls
• zero or more create node calls

Authorization metadata (has permission for all above JCR calls):

• user principals (user, group)
• roles assigned to principals (for RBAC, possibly stored in Mode's AccessControlManager ACL)
  
  • coming from the object above the datastream or higher up
• Just enforcing who can modify datastreams means determining node type and checking for that specific permission with respect to the role.
• Restricting by datastream name or other metadata?

Forwarding Security Credentials

Since applications often act on behalf of end users with extended security attributes, such as those from Shibboleth, the ability to forward credentials to a central point of authorization is key. Regardless of the approach used for authentication of third-party applications, these applications will need to forward security attributes on behalf of end users for authorization. An example of this pattern is the X-Forwarded-For header often used in web proxies, which we can use to forward the end-user IP address.

Fedora supports both end users and application users. It is helpful to feed both local and forwarded security credentials into a same pipeline for extracting security principals that are the basis for authorization.

Access Roles API

The access roles API allows you manage the assignment of access roles throughout the repository tree. For details, please see the Access Roles Module.

Fedora Policy Enforcement Point (PEP)

Fedora includes an extension point that allows installers to build their own enforcement logic for all Fedora actions. A PEP enforces appropriate access for fedora users and their proxies, i.e. applications acting on their behalf. The PEP interface is simple, for details please see Authorization Delegates. Some policy enforcement points may be roles-aware, meaning that they leverage role assignments from the Access Roles API.

...