Navigation:
Documentation
Archive
Page Tree:
This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.
This is a wiki rendering of the attached MS-Word document, BambooServicesPlatform_SoftwareArchitectureDescription_v0.4.1.docx, written by Fernando Alvarez in March 2013. The document is also attached as a PDF.
The Bamboo Services Platform (BSP) is a framework and technology stack for the development and deployment of secure RESTful web services that:
BSP enables and facilitates the development and deployment of RESTful web services by partner institutions by:
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.
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:
BSP services follow a layered architecture, with each layer typically being deployed in its own, separate bundle:
BSP’s Services architecture is composed of:
There are only a handful of obligations placed on a service developer in order to deploy a RESTful service in BSP:
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:
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.
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.
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.
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:
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.
Metadata Name | Description |
objectClass | Interface name the service provider implements; a fully qualified Java reference type name. |
service.id | Unique identifier assigned sequentially by the OSGi Service Framework at bundle start time. |
service.pid | Uniquely identifies the service / service provider and persists across multiple Framework invocations. It is assigned by Project Bamboo during an out of band process. |
service.ranking | Ranking used by framework algorithm when selecting from amongst multiple service providers. |
serviceDescriptionLocation | URL to description of the RESTful service if the service provider is a Resource class; otherwise URL to a description of the service provider. |
service.description | Description of the RESTful service if the service provider is a Resource class otherwise a description of the service provider. |
service.vendor | Entity responsible for the service. |
serviceRestfulAddress | Only required if the service provider is a Resource class. The value should be the same as it appears in the address attribute of the jaxrs:server element, e.g. if "<jaxrs:server id="persons" address="/persons>" then the value should be "persons" |
serviceVersion | For a Resource class, this value identifies the version of the RESTful API exposed by the service provider; otherwise, this value identifies the version of the service provider. |
servicesUsed | List of other services used by this service. |
serviceProviderName | Name of the service / service provider. |
serviceProviderType | Specifies whether a service provider is functional ot system. |
defaultServiceProvider | Whether or not this service provider is the default service provider for the service. |
serviceProviderSupportedVersionsRange | Range of service API versions supported by this service provider. |
serviceProviderContact | Email for use in contacting the resource responsible for supporting the service provider. |
Key determined by service developer | Additional metadata about a service provider. |
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:
The POST and PUT API methods require an XML document in the HTTP Body that contains the Widget resource data:
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:
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:
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.
No overrides needed:
public interface WidgetDocumentHandlerService extends DocumentHandlerService<WidgetType>{ }
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.
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:
<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>
public class WidgetDAO extends GenericDAOImpl <WidgetType, URI> implements WidgetRepository { @Override public URI persist(WidgetType widget) { create(widget); return Widget.getWidgetId(); } }
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.
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):
The API is defined in a Java interface that:
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);
The API is implemented in a Java class, called the Resource Class, that:
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; } }
BSP provides a number of services that provide cross-cutting functionality to other services.
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:
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.
Exposes an SOA layer API for services wishing to record events. Used primarily for IAM purposes in BSP 0.9.
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.
A user may be:
A client is any software application that makes a RESTful call to a service hosted by BSP. A client may be:
Apache web server responsible for validating X-509 certificates and routing HTTP(S) traffic to BSP via an AJP-13 connection.
Access Management services perform the Authentication, Authorization, and Non-Repudiation security functions within BSP.
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.
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.
The Groups service provides a general facility for declaring, naming, and referencing groups of one or more Bamboo Persons.
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.
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.
The Person Profile service manages descriptive information about a Bamboo Person. The descriptive information is largely self-asserted
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.
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.
[Internet2's] Grouper is a system for creating and maintaining institutional groups in a central repository that is used by BSP to:
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).
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:
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.
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:
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:
Authentication in BSP IAM uses the following 3rd-party software:
(click image below to enlarge)
The enumerated list above is numbered from zero (0) in the attached Word and PDF versions of this document.
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 (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 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:
XACML Construct | BSP Implementation |
Policy administration point (PAP) - The system entity that creates a policy or policy set | Manual process maintains policies as XML documents stored in the file system |
Policy decision point (PDP) - The system entity that evaluates applicable policy and renders an authorization decision | BSP PolicyService |
Context handler - The system entity that converts decision requests in the native request format to the XACML canonical form and converts authorization decisions in the XACML canonical form to the native response format | BSP RequestManagerService |
Policy information point (PIP) - The system entity that acts as a source of attribute values | BSP PolicyInformationPointService with implementations:
|
Policy Retrieval Point (PRP) - The system entity where the XACML policies are stored (non-normative construct) | File system based using com.sun.xacml.finder.impl.FilePolicyModule |
The enumerated list above is numbered from zero (0) in the attached Word and PDF versions of this document.
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.
BSP’s XACML implementation should be refactored to employ an RDBMS (or conceivably Grouper) to persist policies. The benefits would be:
The Policy service should be enhanced to expose an API for CRUDL of policies based on XACML Policy schema. Advantages:
[Cf. Technology Component Overview section of Identity and Access Management - Authentication and Authorization.]