Introduction

Bamboo Services Platform

The Bamboo Services Platform (BSP) is a framework and technology stack for the development and deployment of secure RESTful web services that:

• Are tailored to support a range of applications used by humanist scholars
• Conform to a common RESTful API style and service architecture
• Leverage shared infrastructure services such as OSGi service layer calls, result set caching, and identity management

Mission

BSP enables and facilitates the development and deployment of RESTful web services by partner institutions by:

• Defining a services architecture
• Creating a framework for service development
• Developing and deploy shared infrastructure services
• Evaluating, deploying, and supporting an enabling technology stack

Status

The current version of BSP is 0.9. Further development is on hiatus, with the next potential work being undertaken by Tufts University in Q4 2013.

Document Organization and Intent

This document is intended for developers who are engaged in either developing services for deployment in BSP or extending BSP itself.

This document provides an overview of BSP’s architecture design and components in the context of the concerns identified by BSP’s stakeholders. The document is organized as a sequence of sections focusing on domains of the architecture, each of which is then decomposed into views covering specific areas of concern:

• Services Architecture
• Utility Services
• Identity and Access Management Architecture
• Enabling Technology Stack

Services Architecture

Overview

BSP services follow a layered architecture, with each layer typically being deployed in its own, separate bundle:

• REST Oriented Architecture (ROA) layer functions as an HTTP adapter for BSP services, with ROA services exposing a Java interface that provisions a RESTful API. ROA services are dependent on corresponding SOA services for the actual implementation of service functionality
• Service Oriented Architecture (SOA) layer exposing a Java interface API that provides the essential service functionality by wrapping the components in the domain layer. This layer also facilitates inter-service communication of SOA services
• Domain layer implements the functional domain and persistence approach either as a set of components (e.g. Java classes) or as proxy for some set of components implemented outside of BSP

BSP’s Services architecture is composed of:

• Service Framework, a set of interfaces and base classes that define and implement a pattern for service design as well as a set of services that facilitate service execution
• One or more RESTful services that provide value to digital humanists
• Utility services that provide cross-cutting functionality to RESTful services

RESTful Services

There are only a handful of obligations placed on a service developer in order to deploy a RESTful service in BSP:

• The service must be deployable as one or more OSGi bundles
• Have created a Java interface specifying the methods which comprise the service’s API and that extends the GenericResources interface
• Have created a Java class implementing the Java interface
• A Spring configuration file that:
  
  • Publishes an OSGi service complete with metadata (see Service Catalog below) with the Java interface as the service interface and the Java class as the service provider
  • Instantiates the java class (and any supporting classes) using the Spring Beans construct
  • Configures a JAXRS endpoint for the service

A minimal service configuration would thus appear as in the fragment below:

    <osgi:service ref="widgetResource"
		interface="org.projectbamboo.bsp.services.widget.resources.Widgets"
		ranking="0">
		<osgi:service-properties>
			<entry key="service.pid" value="urn:uuid:dec36b3a-60f8-448c-b1bd-7793a22298b9"/>
			<entry key="serviceDescriptionLocation" value="https://wiki.projectbamboo.org"/>
			<entry key="service.description" value="RESTful API over Widgets"/>
			<entry key="service.vendor" value="UC Berkeley"/>
			<entry key="serviceRestfulAddress" value="widgets"/>
			<entry key="serviceVersion" value="1.0"/>
			<entry key="servicesUsed">
		      	    <list>
            		  		<value>org.projectbamboo.bsp.services.core.servicecatalog.service.ServiceCatalogService</value>
        			   </list>
			</entry>		
			<entry key="serviceProviderName" value="Widgets Service"/>
			<entry key="serviceProviderType" value="functional"/>
			<entry key="defaultServiceProvider" value="true"/>
			<entry key="serviceProviderSupportedVersionsRange" value="[1.0.0,2.0.0)"/>
			<entry key="serviceProviderContact" value="falvarez@berkeley.edu"/>
		</osgi:service-properties>
    </osgi:service>
    <bean
    	id=" widgetResource " 
    	class="org.projectbamboo.bsp.services.widget.resources.WidgetResource">
    	<property name="serviceCatalog" ref ="serviceCatalog"/>
    </bean>
    
    <jaxrs:server id="cihub" address="/widgets">
        <jaxrs:serviceBeans>
            <ref bean=" widgetResource "/>
        </jaxrs:serviceBeans>
    </jaxrs:server>

The GenericResources methods that must be implemented (they are used during Authorization processing) are:

• URI resolveResourceId(URI resource) – return either the specific resource Id parsed from the resource passed, or, if the service does not care about specific resources then it must return the resource passed as is
• URI resolveServiceId(URI resource) - return the service.pid (see metadata) for the service

Services Framework

BSP Service Pattern

While a service that meets only the minimum requirements will function as designed when deployed in BSP, service developers – when the flexibility exists – are encouraged to design and implement their service per the BSP service pattern in order to obtain the benefits of shared, tested, code.

Services Framework Services

Request Manager Service

The Request Manager service (also described in the IAM section) provides SOA layer services with methods that expose details about the current request, including the bPId of the user.

Document Handler Service

The Document Handler Service specifies the methods that a resource's document handler must implement for serializing resource representations based on supported media (mime) types. Service developers should create a document handler (and potentially a sub-interface of DocumentHandlerService) for each resource. Alternatively, a service developer may opt to allow BSP to use its default document handler, which is also provided by the Document Handler Service.

Service Catalog Service

The Service Catalog service provides a service consumer (e.g. end user, application developer) with access to information about available services developed for use in, and deployed through, the Bamboo Service Platform (BSP). This information includes both a reference to description of the service's RESTful API ( i.e. a contract that specifies how the service will perform Internet-based HTTP GET, POST, PUT, and DELETE calls) as well as a profile of the service listing all service providers and any supporting services that are potentially involved in implementing the functionality specified by the service. Using the Service Catalog service, a service consumer interested in some set of functionality can:

• Obtain information about what services are currently available
• What functionality a service provides and how
• How to invoke a service over the Internet
• Select from among multiple candidate service providers for a service; service providers are differentiated by the organization that developed the service provider, and by the version of the service a service provider supports.

Service Catalog

The Service Catalog is a set of metadata defined in the Spring bean configuration file for the service and published to the OSGi Service Framework whenever that service’s bundle is activated. The service metadata fulfills both a documentation function (e.g. what the service does, who created it, etc.) as well as forming the basis for the selection algorithm used by the ServiceCatalog service to return a service provider to a requesting service.

Widget Service – an example

This is an example of how a service developer would follow / leverage the BSP service pattern. The example is a typical RESTful CRUDL (Create, Read, Update, Delete, List) service that provides an API for RESTful access to Widget resources. The RESTful API exposed by the Widget service includes:

• GET /bsp/widgets/(widgetId}
• DELETE /bsp/widgets/(widgetId}
• PUT /bsp/widgets/(widgetId}
• POST /bsp/widgets

The POST and PUT API methods require an XML document in the HTTP Body that contains the Widget resource data:

• widgetId – a BSPIdentifierType
• widgetName – a String
• widgetLanguage – a ISO6393UserType

A BSPIdentifierType specifies a unique identifier for BSP Resources; all identifiers used by BSP are URNs. A BSP URN is defined (following ABNF) as:

BSPIdentifierType = URN NID NSS
URN = ("urn:")
NID = ("uuid:")
NSS = EIGHT 3FOUR TWELVE
EIGHT = 8(HEXDIG)
FOUR = "-" 4(HEXDIG)
TWELVE = FOUR EIGHT

The Widget service follows the BSP service pattern; as such it is deployed as four bundles:

• Domain – contains the XML schema and binding files for Widgets and its bound Java classes
• ROA – contains the RESTful API and enabling JAXRS Java classes
• SOA – contains Java interfaces and classes that provision the functionality exposed by the RESTful API by manipulating the domain model classes and interacting with other BSP services
• Persistence – Hibernate configuration files and Java DAO that maintain the state of the objects in the service.

Domain Layer

The Widget service provides a RESTful API that uses XML. Widget service can leverage the BSF (Bamboo Services Framework) document handling constructs to marshal and unmarshall Widget data by:

1. Creating a Widget schema defining the Widget data. The WidgetType complex type extends the BSPResourceType from the BSPResource schema in order to both inherit common elements and attributes (e.g. Creator) as well as enabling WidgetType to be used on the BSF document handling construct
2. Creating a Widgets binding file containing any XML – Java bindings; there should be no binding annotations in the schema itself
3. Generating the Java bound type WidgetType class
4. Creating the Java interfaces and classes required to participate in the BSF document handler construct:
   1. Interface WidgetDocumentHandlerService
   2. Class WidgetDocumentHandler
   3. Class WidgetXMLHandler

 Because the common code is in the BSF, the service developer’s work is basically to just create the Widget components, extending the BSF components as required.

WidgetDocumentHandlerService

No overrides needed:

public interface WidgetDocumentHandlerService extends DocumentHandlerService<WidgetType>{
}

WidgetDocumentHandler

No overrides needed:

public class WidgetDocumentHandler extends DocumentHandler<WidgetType> implements WidgetDocumentHandlerService {
	public WidgetDocumentHandler(List<MediaTypeHandler<WidgetType>> handlers) {
		super(handlers);
	}
}

Note that while BSF is designed to accommodate non-XML (e.g. JSON) types, none have been implemented in BSP to-date. To do so, a developer would have to create an abstract JSONHandler class similar to XMLHandler but with the appropriate JSON processing; one approach to consider would be to treat XML as the canonical form and then include a JSON – XML transform for API purposes only.

Persistence Layer

The persistence layer for the Widget service is a bundle that contains the Widget ORM-RDBMS mappings and Java interface and classes that participate in the persistence portion of the BSF.

Widget service can leverage the BSF persistence constructs to CRUD Widget data by:

• Creating a Widget Hibernate mapping file; there should be no JPA annotations in the Java classes
• Creating a WidgetRepository interface that extends the BSF Registry interface
• Creating a WidgetDAO class that extends the BSF GenericDAOImpl class and implements WidgetRepository

Widget.hbm.xml

<hibernate-mapping package="org.projectbamboo.bsp.services.widget.domain.jaxb">
	<typedef class="org.projectbamboo.bsp.common.java2sql.BSPIdentifierUserType" name="BSPIdentifierUserType" />
	<typedef class="org.projectbamboo.bsp.common.java2sql.ISO6393UserType" name="ISO6393UserType" />
	<class name="WidgetType" table="widget">
		<id	name="widgetId" type="BSPIdentifierUserType" length="45" >
			<generator class="assigned" />
		</id>
		<property name="modified" type="timestamp" />
		<property name="modifier" type="BSPIdentifierUserType" length="45" />
		<property name="creator" type="BSPIdentifierUserType" length="45" />
		<property name="created" type="timestamp" />
		<property name="widgetName" />
		<property name="widgetLanguage" type="ISO6393UserType" length="3" />
    </class>
</hibernate-mapping>

WidgetDAO

public class WidgetDAO extends GenericDAOImpl <WidgetType, URI> implements WidgetRepository {
	@Override
	public URI persist(WidgetType widget) {
		create(widget);
		return Widget.getWidgetId();
	}
}

SOA Layer

The SOA layer for the Widget service is a bundle that contains Java interfaces and classes that provision the functionality for widget CRUDL. Because Widgets is just a CRUDL service, there is not need to add any code other than the creation of the WidgetService interface that extends the GenericResourceInterface and a WidgetServiceImpl class that implements WidgetService.

If the service developer wished to access other BSP services, they would use the ServiceCatalog service to discover the service and invoke its service provider.

ROA Layer

The ROA layer for the Widget service is a bundle that functions as a RESTful adapter for the Widget service. It defines and exposes the RESTful API and publishes an OSGi service that provisions said API. The bundle contains an interface, a Java class, and a Spring configuration file; all other components where either created (and reside in the appropriate bundle) in the SOA or Domain layers or comprise members of the BSP Services Framework (BSF):

• GenericResources - BSF interface that must be implemented by all pattern-following RESTful interfaces
• Widgets – the RESTful interface for the Widget service
• WidgetResource – the resource class that implements Widgets and extends GenericResource in order to inherit all of its common methods. For a CRUDL service, these may be all that’s necessary for the service to be implemented
• WidgetType – A class generated in the Domain layer that is the JAXB binding for the Widgets schema that defines the Widget resource data
• WidgetService – an interface for the SOA layer Widget service that is used by the ServiceCatalog service to return a service provider for the service that contains the actual service logic for the Widget service
• WidgetDocumentHandlerService – an interface for the SOA layer Widget Document Handler service that is used by the ServiceCatalog service to return a service provider for the service that marshall and unmarshalls Widget resources
• ServiceCatalogService – A BSF service that returns a service provider for a given service interface. This is the only service in BSP that must be specified in the Spring configuration file using the Spring osgi:reference> element; all other services (or rather service providers) should be obtained using the ServiceCatalog service

RESTful Service API

The API is defined in a Java interface that:

• Extends GenericResources
• Contains a JAXRS @Path annotation whose value is relative to the JAXRS server element’s address attribute in the Spring configuration for the ROA bundle
• Defines methods for the HTTP DELETE, GET, POST, and PUT actions
• Defines an overloaded GET method for returning lists
• Includes all JAXRS annotations – no annotations should appear in the resource class

Example fragment:

@Path("/")
public interface Widgets extends GenericResources {
    /**
      * Returns a <tt>WidgetType</tt>.
      * 
      * @param mT - Content type to be returned 
      * @param widgetId - Widget identifier
      * 
      * @return 
      * <ul>
      * <li>HTTP Response Status 200</li>
      * <li>HTTP body containing a <tt>WidgetType</tt></li>
      * </ul>
      * 
      * @throws WebApplicationException 404 if the Widget does not exist
      */
    @GET
    @Path("/{widgetId}")
    public  InputStream get(	@DefaultValue(APPLICATION_XML) @HeaderParam(ACCEPT) MediaType mT, 
@PathParam("widgetId") URI widgetId);

RESTful Service Resource Class

The API is implemented in a Java class, called the Resource Class, that:

• Implements the interface, e.g. Widgets
• Extends the GenericResource base class, specifying the previously created WidgetType, WidgetService, and WidgetDocumentHandlerService as type arguments
• Overrides the Class<?> getRESTInterface() method to return the interface class, e.g. Widgets.class

Example fragment:

public class WidgetResource extends GenericResource<WidgetType, WidgetService, WidgetDocumentHandlerService> implements Widgets {
	@Override
	public InputStream get(MediaType mT, URI bPId) {
		return super.get(mT, bPId);
	}
…
    @Override
	protected Class<?> getRESTInterface() {
		return Widgets.class;
	}
}

Utility Services

BSP provides a number of services that provide cross-cutting functionality to other services.

Notification Service

The Notification Service's primary function is to disseminate Notifications on behalf of Publishers to those Notification Consumers for which Subscriptions have been registered, against specific Topics. While the Notification Service will be designed to provide a general publish / subscribe capability, the requirements specifically call for the ability to:

• Provide a user/client with a notification that their asynchronous request has been processed
• Enable a Bamboo Person to broadcast a message to other Bamboo Persons and/or Bamboo Groups

Result Set Caching Service

The Result Set Caching (RSC) service permits a set of results – generally returned by another service – to be stored and retrieved for a limited period of time. The purpose of this temporary storage is to keep service results available for application to further service-processing (e.g., in a "pipeline" process) without unnecessary transport of the result set over the network (e.g., between the service host and a caller/client of a series of services, in a "pipeline" process).

The RSC will send / receive content based on the media type provided by the BSP when adding the content to the cache. Said media type information will be stored as part of the Cache Item's metadata. The RSC will not edit or verify that the content provided in fact constitutes a valid example of the given media type, nor will it perform any exception handling over and above returning a "404 Not Found" if the requested item is not available from the cache.

Event Logger Service

Exposes an SOA layer API for services wishing to record events. Used primarily for IAM purposes in BSP 0.9.

Identity and Access Management Architecture

Overview

BSP’s Identity and Access Management Architecture is that set of components that in combination function to permit, deny, and log access to a BSP-hosted resource by a user making a request via some client.

User

A user may be:

1. Anonymous – Any user that does not access BSP via a Registered Application
2. Anonymous – Any user accessing BSP via a registered application that for whatever reason has not provided a Bamboo Person Identifier (bPId) as part of the request
3. Authenticated - Any user accessing BSP via a registered application that has provided a Bamboo Person Identifier (bPId) as part of the request . An authenticated user of a BSP-hosted service is called a Bamboo Person. A Bamboo Person:
   1. May be created, and its identifier (bPId) associated, with multiple identity providers (IdPs), such as one or more universities and/or one or more social media IdPs
   2. Proves their identity by authenticating to an associated IdP; Bamboo's IAM infrastructure does not gain or maintain access to user credentials (passwords). Where privileges depend on affiliation with an institution, affiliation must be proven by login to that institution's IdP in any given session to prove currency of the affiliation
   3. May specify an associated set of profile information, including links to profile information maintained elsewhere
   4. May form groups that are maintained in a central store, and may add to their groups any other Bamboo Persons

Client

A client is any software application that makes a RESTful call to a service hosted by BSP. A client may be:

1. Non-registered – Any client that has not performed the procedure required to become a registered application
2. Registered Application – Any client that has performed the procedure required to become a registered application and has provided the following information as part of the request:
   1. An X-509 certificate
   2. Required HTTP headers

Web Server

Apache web server responsible for validating X-509 certificates and routing HTTP(S) traffic to BSP via an AJP-13 connection.

Access Management Services

Access Management services perform the Authentication, Authorization, and Non-Repudiation security functions within BSP.

Request Manager Service

The Request Manager service intercepts RESTful calls to BSP services and performs the functions of a Policy Enforcement Point (PEP), limiting access to BSP services based on previously defined policies.

Protected Resource Service

The Protected Resource service enables a Bamboo Person to extend access to resources they own to other Bamboo Persons, groups, or institutions. The information maintained by the Protected Resource service is used by BSP as part of the authorization process for a request. Contact Service.

Groups Service

The Groups service provides a general facility for declaring, naming, and referencing groups of one or more Bamboo Persons.

Policy Service

The Policy Service provides a centrally manager decision point for policies consumed by components of the Bamboo Services Platform (BSP). The Policy Service performs the Policy Administration Point (PAP) and Policy Decision Point (PDP) functions within the Bamboo Service Platform Authorization architecture.

Identity Services

Person Service

The Person Service manages a Bamboo Person identifier that is unique across the Project Bamboo namespace. The purpose of the Bamboo Person identifier is to uniquely identify a person who utilizes Bamboo technology independently of the one or more methods they use to assert identity.

Profile Service

The Person Profile service manages descriptive information about a Bamboo Person. The descriptive information is largely self-asserted

Contact Service

The Contact Service manages contact information for communication to people, groups of people, or organizations. Contact information may include (but is not limited to) delivery addresses, email addresses, phone and fax numbers, etc.

Application Catalog Service

The Application Catalog service manages a registry of known applications. A known or "registered" application is an application that has met the requirements for trust by the Bamboo Services Platform (BSP). Whether or not a client is a registered application has an impact on a user/client's ability to access protected resources in the BSP.

Grouper

[Internet2's] Grouper is a system for creating and maintaining institutional groups in a central repository that is used by BSP to:

1. Persist information about registered applications
2. Persist group, membership, and privileges asserted by Bamboo Persons via the Group Service

Authentication View

Authentication (AuthN) is the process of confirming that a user is who they claim to be. Responsibility for authentication in BSP is shared between three components, an Identity Provider (IdP), a Registered Application, and BSP IAM. BSP IAM requires that the user be authenticated on every request; that is, BSP does not maintain any session state or tokens (e.g. cookies).

Trust but Verify

BSP does not directly authenticate the user; instead, BSP follows a Trust-but-Verify model in which it authenticates the Registered Application and then trusts it to assert the user’s identity (i.e. bPId). This is with the understanding that the Registered Application had in its turn delegated credential validation to an IdP. It is a prerequisite of the Authentication process that both the Registered Application and the User be known to BSP.

A Registered Application is authenticated based on values provided in both the X-509 certificate and HTTP headers passed as part of the request:

• The Registered Application must provide a value for the subjectDn in the X-509 certificate
• The Registered Application must provide a value for the X-Bamboo-AppID header

During the authentication of the Registered Application BSP compares the value of the subjectDn against that which is stored in BSP (physically in Grouper) as part of the data relating to the application referenced by the value of X-Bamboo-AppID.

Pre-authenticated Users

Only a Registered Application may assert the identity of a user on behalf of whom the request is made, as well as asserting the scoped roles to be assigned to that user. BSP’s IAM architecture requires a Registered Application to provide the following HTTP headers to requests against services hosted on BSP:

• X-Bamboo-AppID: A UUID that identifies the client research environment, application, tool, or service; this UUID is issued as part of the process of registering a trusted client in the Bamboo Trust Federation
• X-Bamboo-BPID: A UUID that identifies the user on whose behalf the request is being sent; this is obtained via a service call that occurs in time between user login and any other service request
• X-Bamboo-Roles: An optional pipe-delimited (|) set of scoped roles asserted to belong to the user, of the form role@domain (i.e. an RFC822 name)

Anonymous Users

A client application may make requests anonymously. If the client is not a Registered Application, it does not provide any HTTP headers – they are ignored by BSP.

A Registered Application may choose to make a call on behalf of a user who may not be a Bamboo Person. In this case, the user is treated as anonymous but they may inherit certain permissions in quality of their request coming from a Registered Application. When making an anonymous request the Registered Application (which is still authenticated) provides:

• X-Bamboo-AppID: A UUID that identifies the client research environment, application, tool, or service; this UUID is issued as part of the process of registering a trusted client in the Bamboo Trust Federation
• X-Bamboo-Roles: An optional pipe-delimited (|) set of scoped roles asserted to belong to the user, of the form role@domain (i.e. an RFC822 name)

Enabling Technologies

Authentication in BSP IAM uses the following 3rd-party software:

• Spring Security Framework (SSF) – BSP implements interfaces and extends base classes from this module in order to plug into the standard Spring Security flow; in other words, Spring Security provides the framework within which BSP AuthN occurs
• AJP – BSP uses AJP 1.3 as the protocol by which it receives requests from Apache and thereby obtains the X-509 certificate subjectDn
• Servicemix – BSP services run under the CXF servlet which in turn runs under Jetty
• Pax Web Extender Whiteboard – BSP uses this service to declare a filter to Jetty against the CXF Servlet; it is this filter (a Spring Security FilterChainProxy) that enables BSP to intercept calls made to services on BSP

Authentication Flow

(click image below to enlarge)

1. When Servicemix is started:
   
   1. Bundle fragment jetty.config is attached to the CXF Servlet bundle; this has the effect of configuring the AJP connection; Servicemix must be restarted whenever this bundle is initially deployed or refreshed for the AJP connection to be in effect
   2. The spring-security.xml configuration files in the auth bundle causes SSF to start and instantiates the BSP beans that participate in the SSF during AuthN (and AuthZ)
   3. The Perimeter class in the auth bundle registers the FilterChainProxy filter on the CXF servlet
2. A user makes a request for a service on BSP
3. The client, a Registered Application, interacts with the IdP to authenticate the user
4. The client, a Registered Application, builds the request:
   
   1. Request from the user (i.e. the URL plus any HTTP Body content)
   2. The registered application X-509 certificate
   3. Values for the X-Bamboo-AppID, X-Bamboo-BPID, and X-Bamboo-Roles (optional)
5. Apache verifies that the X-509 certificate against the certificate store
6. Apache sends the request to Jetty via the AJP protocol
7. Upon receipt at Jetty, the fact that a SSF FilterChainProxy has been registered against the CXF servlet initiates the SpringFilterChain processing
8. SSF calls the HTTPHeaderPreAuthenticatedFilter class, which in turn determines whether or not an X-509 certificate has been passed:
   
   1. if not passed, the class returns NULL to the SSF which then proceeds to process other filters (which include the filter that handles anonymous calls)
   2. If passed, obtains the subjectDn from the X-509 certificate, the request path information (e.g. relative URL), and the contents of X-Bamboo-AppID, X-Bamboo-BPID, and X-Bamboo-Roles which are all then made available as a Request object to SSF
9. SSF then calls the InterimPreAuthenticatedProvider class which in turn calls the ApplicationCatalog service to validate:
   
   1. Does the subjectDn value match that which is stored in Grouper as an attribute of the application referenced by the value of X-Bamboo-AppID
   2. Does the date-time on the BSP server fall within the range of valid start / end date attributes of the application referenced by the value of X-Bamboo-AppID
   3. If validation fails, the request will be rejected and information to that effect will be logged via the Event service
10. SSF then calls the BSPUserDetailsService (this is not a service in the BSP sense) class, which in turn calls the PersonService to determine if the value passed in X-Bamboo-BPID corresponds to a previously created Bamboo Person:
    
    1. If the value passed is NULL, the user will be considered anonymous via a Registered Application
    2. If the value passed is not NULL, but the call to the PersonService returns a Not Found exception, the request will be rejected
    3. If the Bamboo Person exists, the BSPUserDetailsService class will provide SSF with a Requestor object which SSF uses to create the SSF SecurityContextHolder – this is the “Principal” that is available as a Threadlocal variable for the balance of the request lifecycle
    4. Information pertaining to the successful reception and validation of a Registered Application request will be logged via the Event service
11. The balance of the flow for a pre-authenticated user is considered AuthZ and will be covered in that section
12. SSF completes its processing and if the request has been authorized, passes control to CXF which in turn calls the service requested by the client
13. If the request did not include an X-509 certificate, then the client is considered a non-registered application and the user an anonymous user. SSF invokes the BSPAnonymousAuthenticationFilter which:
    
    1. Provides SSF with a Requestor object which SSF uses to create the SSF SecurityContextHolder – this is the “Principal” that is available as a Threadlocal variable for the balance of the request lifecycle
    2. Logs Information pertaining to the successful reception and validation of an Anonymous request via the Event service
    3. Control is returned to SSF which proceeds with AuthZ (i.e. step 11)

Notes for Future Developers

The HTTPHeaderPreAuthenticatedFilter class implements a near-term approach which will be superseded by the N-Tier approach once SAML ECP (Extended Client or Proxy) for Shibboleth is available. At this point, HTTPHeaderPreAuthenticatedFilter should be replaced by a class that performs the same function but that harvests data from either variables provided by Jetty or a SAML assertion document.

Authorization View

Authorization (AuthZ) to access services or resources is effected via definition, decision, and enforcement of policies that allow or deny service and resource access based on factors that include institutional affiliation; membership in groups managed independently of individual applications; resource ownership; and/or the identity of a client application from which a user issued their request.

AuthZ in BSP is policy-based (as opposed to say Role-based); specifically, BSP follows the XACML architecture and specification to policy-based AuthZ.

XACML

XACML stands for eXtensible Access Control Markup Language. The standard defines a declarative access control policy language implemented in XML and a processing model describing how to evaluate authorization requests according to the rules defined in policies. XACML is primarily an Attribute Based Access Control system (ABAC), where attributes associated with a user or action or resource are inputs into the decision of whether a given user may access a given resource in a particular way. While discouraged in BSP, Role-based Access Control (RBAC) can also be implemented in XACML as a specialization of ABAC.

The XACML model supports and encourages the separation of the authorization decision from the point of use. When authorization decisions are tightly-coupled with the client application (or based on Access Control Lists (ACLs)), it is very difficult to update the decision criteria when the governing policy changes. When the client is decoupled from the authorization decision, authorization policies can be updated on the fly and affect all clients immediately.

BSP has implemented the XACML model as follows:

Authorization Flow

1. When the org.projectbamboo.bsp.policy.domain bundle is started, the policy XML files in the policy directory are read in by the com.sun.xacml.finder.impl.FilePolicyModule
2. Once the AutnN flow has progressed through steps 2-10 (or step 13, if anonymous), SSF passes control to BSPVoter, a class that implements SSF AccessDecisionVoter and BSP PolicyEnforcementPoint interfaces
3. BSPVoter obtains the method (e.g. POST, GET, etc.) and resource (i.e. the path, no query parameters) from the HTTP Request and calls the RequestManagerService to authorize the request
4. The RequestManagerService logs the request for a decision and then proceeds to build a BSP XACMLContextType:
   
   1. Obtaining subject (i.e. user, registered application) attributes from the SSF principal
   2. Obtaining action from the method parameters passed by BSPVoter
   3. Obtaining resource from the method parameters passed by BSPVoter
   4. Obtaining group attributes from the GroupPIP service
   5. Obtaining resource attributes from the ResourcePIP service
5. The RequestManagerService then uses a ContextHandler object to format the XACMLContextType to a com.sun.xacml.ctx.RequestCtx object
6. The RequestManager then calls the Policy service, passing the RequestCtx
7. The Policy service evaluates the request:
   
   1. Calls the com.sun.xacml.PDP object, passing the RequestCtx
   2. The com.sun.xacml.PDP object evaluates the request based on the policies it obtained from the com.sun.xacml.finder.impl.FilePolicyModule and returns a com.sun.xacml.ctx.ResponseCtx back to RequestManager
8. The RequestManager then returns control back to BSPVoter based on the decision in the ResponseCtx
9. Depending on the result (e.g. Permit, Deny) BSPVoter will return a “vote” to SSF and log the result
10. SSF will in turn, depending on the resolution of all AccessDecisionVoter (in BSP 0.9 there is only the one, BSPVoter) votes, allow the request to proceed or return a Not Authorized to the client

Protected Resource Service

The Protected Resource service enables a Bamboo Person to extend access to resources they own to other Bamboo Persons, groups, or institutions. The information maintained by the Protected Resource service is used by BSP as part of the authorization process for a request.

Notes for Future Developers

BSP’s XACML implementation should be refactored to employ an RDBMS (or conceivably Grouper) to persist policies. The benefits would be:

• Real-time policy access as opposed to the current bundle-start-time approach, allowing for new policies or edits to existing policies to take effect immediately and without having to bounce the Policy Domain bundle.
• Reuse of rules as opposed to the current approach which duplicates shared rules in each policy
• Potentially faster policy resolution based on an RDBMS-based policy finder

The Policy service should be enhanced to expose an API for CRUDL of policies based on XACML Policy schema. Advantages:

• Allow implementation of AuthZ over policy creation and maintenance
• Provides opportunity for validating policy content

Enabling Technology Stack

[Cf. Technology Component Overview section of Identity and Access Management - Authentication and Authorization.]