Table of Contents |
---|
Overview
Excerpt |
---|
Fedora 4 authorization is designed to be fine grained, while at the same time manageable by administrators and end users. Authentication is managed by the servlet container or externally, but authorization mechanisms are open to extension and many reference implementations are included. Roles-based access control is an included feature that makes permissions more manageable and at the same time easier for external applications to retrieve, index and enforce. Finer grained security checks have no impact on the performance of requests that have a Fedora administrator role. |
Use Cases
F4 alpha 2 |
---|
Table of Contents |
---|
Use Cases
- Researcher control the polices on their own objects
- Distributed authentication and authorization
- University of North Carolina at Chapel Hill
- Unified Authorization
- Setting Individual Permissions
- Yale University
- Fedora managing access conditions
- Programmers use API for access condition support in external systems, i.e. HydraTitle (goal)
- Applications use API for updating access conditions stored in Fedora
- University of Wisconsin - Madison
- Islandora
- Hydra
- Avalon Media System
...
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 of either fedoraUser or fedoraAdmin.
- fedoraAdmin - Grants superuser permissions to the the Fedora repository. Bypasses the configured policy enforcement point (PEP).
- fedoraUser - Grants permissions based on the configured 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) , see authorization belowgrants permissions on the basis of end-user security credentials that are forwarded via extended request headers.
Info | ||
---|---|---|
| ||
Implementations may configure the servlet container to employ any user authentication mechanism that meets specifications. This is container-specific, but usually includes JAAS, LDAP, CAS, Shibboleth, etc.. |
See the overview on configuring servlet container authentication for more details.
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.
...
Info | ||
---|---|---|
| ||
In Development: 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". |
Info | ||
---|---|---|
| ||
In Development: 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. |
OAuth 2.0 Third-Party 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 Authorization of Third-Party Applications
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.
OAuth Roles
- Client Application - custom front end, message-driven service
- Authorization Service - Fedora
- Resource Server - Fedora
Possible Limitations
- A token covers a certain scope of access, tied to the client app. Assuming that user privileges vary throughout a repository, can OAuth tokens be used to effectively record user privileges?
- One token per application or per app user, is the OAuth model we see in the wild. Otherwise an app would have to know which token to use within some smaller context.
- Similarly, how much access can a single OAuth token cover? Can they be patched or modified after authorization to cover more cases?
Implementation Questions
- Are OAuth mitigated operations subject to other access restrictions imposed on the user who authorized the token? (or the on-behalf-of user)
- Then ACL restrictions on the user would apply equally to the token-based requests they have authorized.
- Who will be able authorize third-party applications at the server's Resource Owner Authorization endpoint? (/authorize)
- fedora administrators
- who else?
- What scopes will govern token access?
- on behalf of user X (or security principal X)
- set of permitted actions (read, write) (Note that JCR 2.0 privilege discovery might align well with OAuth scopes.)
- within repository path /A/B/C
- between now and X months hence
- Which scopes are optional and which are mandatory, for whom?
- Do admins get to give away global permissions to apps?
- Are tokens authorized by normal users restricted to their current permissions?
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.
Forwarding Credentials and Security Principals
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 Regardless of the approach used for authentication of third-party appsapplications, certain these 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".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 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 basis for authorization.
- Container User Role: forward credentials
- OAuth Token Permission: forward credentials
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 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.
Info | ||
---|---|---|
| ||
ModeShape Authentication Provider 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. This is really a ModeShape extension point used internally by Fedora. For the analogous Fedora extension point, see Policy Enforcement Point (PEP). See https://docs.jboss.org/author/display/MODE/Custom+authentication+providers |
...
title | Reference Implementation |
---|
Servlet Container Authentication Provider
...
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)
...
title | Reference Implementation |
---|
...
Fedora
...
ModeShape-Based Authorization Modules
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 (for now, simply a JCR Session) and may all fail together due to a permission or validity check.
A custom SecurityContext class can implement the existing AuthorizationProvider or AdvancedAuthorizationProvider interfaces to implement specialized security checks through the hasPermission method.
- Best for enforcement policies based on Fedora structures, i.e. policies govern CRUD on the nodes/properties of the Fedora object
- It's the JCR way, secures the JCR API as well
- More security checks, but less complexity (consider SPARQL update, for instance)
- Cannot block the whole Fedora API method before execution (but we have transactions?)
Fedora Admin Authorization Module
This is a very simple, servlet-based authorization system. Its authentication provider will only create sessions for servlet requests that have the fedoraAdmin container role. It authorizes admins users to perform all actions.
XACML Fedora User Authorization Module
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 request information into a authorization request that is passed to a policy decision point (PDP) according to the XACML standard.
- This authorization provider will 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.
- ModeShape Question: How best to store policies within the repository? (normal nodes/properties or possibly behind the AccessManager API)
Option: Internal PDP vs. External
- Use JCR API for attribute lookups
- Always store as much as possible in the repo itself. (A. Soroka)
- Less penalty for light authZ requests (i.e. use more attribute lookups based on Fedora object model)
Internal PDP (within ModeShape JVM) | External PDP (remote XACML service) |
---|---|
Minimal administrative overhead through dependency injection, etc.. | Flexible, can be any XACML implementation |
ModeShape cache will keep frequently used ACL metadata in memory. Removes the need for any additional cache. | Decent performance may require custom metadata caches. |
No network overhead making connections or marshaling data. | Network latency, etc.. |
Decision and policy cache invalidation may be based on events. | Cache invalidation requires wiring JCR or Fedora JMS specifics into the chosen XACML service. Cache invalidation would be asynchronous. |
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)
- 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.
- And this should happen at the model, not at external APIs (A. Soroka)
- 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 )
- Do we want policy language to reflect the Fedora API or the Fedora object model?
- 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.
- Agreed, but we need an extension point that allows us to gather more user details, other implementation-specific principals that might be granted roles/privs.
- Support for users granting permissions to applications via OAuth. (see below)
- Support for decision caching ( JBoss XACML decision cache )
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)
REST API-Based Authorization
This approach intercepts JAX-RS-supported HTTP requests and provides some form of policy enforcement around the API operation.
Prototype Code
The Fedora AuthN/AuthZ modules are under construction. For now this is some prototype code here:
...
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.
Info | ||
---|---|---|
| ||
A policy enforcement point enforces appropriate access for Fedora users and their proxies, i.e. applications acting on their behalf. One policy enforcement point may be configured at a time. |
Info | ||
---|---|---|
| ||
The basic roles enforcement point determines access on the basis of 4 simple roles that may be assigned throughout the repository. These are reader, metadata reader, writer, and admin. For details please see the Basic Role-based Authorization Delegate. |
Info | ||
---|---|---|
| ||
In Development: The XACML PEP forwards authorization requests to a XACML policy decision point. It is aware of access roles and may also make determinations on the basis of a wide range of Fedora resource properties. Policy sets may be customized for different part of the repository tree. For detail please see the XACML Authorization Delegate. |