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().

Fedora users may have the following servlet container roles.

• fedoraAdmin - Grants superuser permissions to the the Fedora repository. 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.
  
  

Additional Security Principals

Access may hinge on additional security principals that are specific to an organization. These principals are often based on Shibboleth, LDAP, CAS, databases and other sources. Additional principals can be included in authorization by implementing a PrincipalFactory. A PrincipalFactory examines Servlet requests and returns a set of additional principals. Examples include a named IP range, an affiliation or group from a Shibboleth header, principals extracted from SAML payloads, etc.. Fedora provides a configurable HeaderPrincipalFactory that extracts principals from headers.

OAuth 2.0 User Authentication

This feature allows a user to sign-in via a third-party service, such as Google, Yahoo or Facebook. The result of the OAuth 2.0 authentication flow is a username and access to whatever user account details are within the authorized scope, such as email address. Fedora is then free to use these user details to create a local user account or assign privileges as required for Fedora authorization. (All that this work flow provides is user authentication.)

OAuth Roles

• Client Application - Fedora
• Authorization Service - Google, etc..
• Resource Server - Fedora

OAuth 2.0 Application Authorization

From the OAuth 2.0 specification:

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Applications can be authenticated by means of token credentials generated through the OAuth 2.0 framework. Subject to the practical limitations explored below, Fedora will be designed such that application authorization can happen within the OAuth workflow. While OAuth is supported and encouraged, applications can still use container-level authentication, obtaining a container role and matching access. Therefore OAuth support is not required of all Fedora client applications.

OAuth Roles

• Client Application - custom front end, fedora proxy, or message-driven service
• Authorization Service - Fedora
• Resource Server - Fedora

OAuth Token Scopes

* for future consideration: A user with the fedoraUser role could grant tokens within a scope that is limited by their own user id credentials. The application would be able to act on their behalf. One token per app user is the OAuth model we commonly see. Otherwise an app would have to track which token to use within some smaller context.

FAQ

• Are OAuth mitigated operations subject to the access restrictions imposed on the user who authorized the token? (or the on-behalf-of user)
  
  • Then ACL restrictions on the user would need to apply equally to the token-based requests they have authorized.
• Can an OAuth tokens be used as principals and assigned access roles within the repository?
  • Yes, access tokens may be assigned roles within the repository. This is especially useful for limited application access to a subtree.
• How are scopes combined?
  • Each scope imposes additional limitations upon the access granted to the token. So "read only" and "fedora administrator" combine to make a token that can read all the data in the repository. It doesn't make much sense to combine "on-behalf-of" with "fedora administrator" or "forward credentials" since the result token would effectively only have on-behalf-of X access.

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.

The ability to forward credentials in request headers must be restricted to specific users:

• In servlet container authentication, forwarding with require the container role of fedoraProxy.
• In OAuth token authentication, the token must include the scope forward credentials.

XACML Authorization Extension: Content Roles and Policies

Assigning Content Roles

This is an optional approach to Fedora authorization in which users (security principals) are assigned named content roles on Fedora objects. The roles assigned in the tree of Fedora objects can be used in authorization mechanisms to confer broad access privileges. These authorization mechanisms (implementations of the AuthorizationProvider interface) can easily retrieve content roles specific to a Fedora object or JCR path.

Fedora defines some useful conventions for content roles:

• Owner - This is a read/write role that also allows the user to assign roles to others.
• Content roles are stored on a Fedora object mixin node - authorization mechanism must enforce edit privileges on this node.
• Content roles are inherited from higher up in the tree of Fedora objects.
• New roles may be assigned lower in the tree of Fedora objects.
• Role inheritance can be blocked at any point in the tree.
• Content roles have no effect on the privileges granted to user roles (originating in container auth) or conferred by other means.
• Roles can be assigned to any security principal that is available in the Fedora security context.
  
  • This can include things like a user, a named IP range, LDAP group or organizational affiliation.
  • Can be based on Shibboleth supplied x.520 headers
  • Are there useful CAS attributes other than username? Do CAS implementations use LDAP, for instance?
  • You can also assign roles to the Everyone principal, present in every Fedora security context.
    • Is Everyone anonymous? Or is there Everyone (that we know), and then Everyone (that we know) + Anyone (A. Soroka)
    • We can do both. I think "everyone that we know" is a subset of "everyone". How does "authenticated users" sound?
• A query can retrieve all content roles assigned to an object or a principal.

Role-Based Policy Set

Fedora provides a reference set of XACML policies formulated around each content role. These policies are written per role, so you can add whichever role/policy combinations you need to your repository. These example policies can be modified to support authorization specific to a repository.

• Do we support policies with additive permissions? (role B policy has all permissions of role A policy, plus...)
• Subtractive permissions (role B policy has all permissions of role A policy, minus...)
  • Is this something that XACML can do for us, or something we would have to rig up? - Greg Jansen
• Set operations between roles? (role D can do what role A can do, except for what roles B or C can do)
  • see above
• Provide examples of custom attributes being used in policies (a publication flag or embargo date, for instance)

Authorization for Other REST API Endpoints

These endpoints in the REST API will require the fedoraAdmin container role or the fedora administrator OAuth token scope:

TBD

Code Repository

The Fedora AuthN/AuthZ modules are in development here:

https://github.com/futures/fcrepo-authz