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 fedoraAdmin.
Extension Point: Container Authentication Implementations may configure application containers to employ any user authentication mechanism that meets servlet specifications. This is container-specific, but usually includes JAAS, LDAP, CAS, Shibboleth, etc.. |
|---|
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, etc.. Additional principals can be supported in Fedora authorization by implementing the PrincipalFactory interface. A PrincipalFactory examines Servlet requests and returns a set of additional principals for authorization. Example principals might include a named IP range, an affiliation or group from a Shibboleth SP header, principals extracted from SAML payloads, etc.. Fedora provides a configurable HeaderPrincipalFactory that extracts principals from headers.
Extension Point: PrincipalFactory Implementations may enhance the security context for all authorization decisions downstream by implementing a Principal Factory, which extracts additional security principals from servlet requests. Principals are extensible to whatever credential the organization wishes to privilege. Principal names must be unique. |
|---|
Reference Implementation: IpRangePrincipalFactory Fedora ships with a principal factory for named IP ranges. The factory may be configured with a map of names to a set of IP ranges. This allows Fedora administrators to assign privileges to all users within a named IP range, such as "On Campus". |
|---|
Reference Implementation: HeaderPrincipalFactory Fedora ships with this simple principal factory that creates string-based security principals from request headers. This is useful in cases, like the Apache HTTP Shibboleth module, where additional attributes are supplied as request headers. |
|---|
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.)
From the OAuth 1.0 specification:
OAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end- user). It also provides a process for end-users to authorize third- party access to their server resources without sharing their credentials (typically, a username and password pair), using user- agent redirections.
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 authorization happens within the OAuth workflow.
While OAuth is supported and encouraged, applications can still authenticate via container-level "user authentication". OAuth support is not required of all Fedora client applications.
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.
Regardless of the approach used for authentication of third party apps, certain applications will need to forward security attributes on behalf of end users.
Discussion: These break down into two categories, named principals and credentials. The distinction is whether Fedora or the third part application constructed the distinct security principals used for authorization. To illustrate we take the example of an IP restriction. Let's say that the authorization policy, regardless of implementation, says that users "on campus" can access a resource, but otherwise they cannot. The third party can support this authorization in two ways. It can provide the IP address of the end user request or it can provide the named security principal "on campus".
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. In mixed authentication environments, i.e. Fedora instances that support end-user and application requests, it is helpful to channel security credentials into a same pipeline for extracting the security principals that are the subject of authorization.
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 turn gets the Session from a SessionFactory. During Fedora transactions a JCR Session is 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 an 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.
Extension Point: AuthenticationProvider The AuthenticationProvider is a ModeShape interface that allows implementations to authenticate JCR sessions on the basis of custom credentials. Implementations may create a custom security context here that implements highly granular JCR authorization. See https://docs.jboss.org/author/display/MODE/Custom+authentication+providers |
|---|
Reference Implementation: ServletAuthenticationProvider Fedora ships with a AuthenticationProvider that checks for proper Fedora user roles before session creation. It creates a security context that implements the Fedora user-based authorization endpoint. |
|---|
Reference Implementation: OAuthAuthenticationProvider Fedora ships with an authentication provider that verifies OAuth token credentials and creates a special OAuth security context for new sessions that implements OAuth-based authorization. |
|---|
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.
A custom SecurityContext class can implement the existing AuthorizationProvider or AdvancedAuthorizationProvider interfaces to implement specialized security checks through the hasPermission method.
MODE-1920 AccessManager API
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.
This is a very simple, servlet-based authorization system. It's authentication provider will only create sessions for servlet requests that have the fedoraAdmin container role. It authorizes admins users to perform all actions.
This module creates sessions only for requests bearing a fedoraUser container role. It is useful in cases where Fedora is responding directly to container authenticated end users. This module compiles requests information into a authorization request that is passed to a policy decision point (PDP) according to the XACML standard.
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:
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.
These approached intercept JAX-RS requests and provide some form of policy enforcement around the API operation.
The Fedora AuthN/AuthZ modules are under construction. For now this is some prototype code here:
https://github.com/gregjan/fcrepo-authz