|Table of Contents|
From planning workshops (April 2008- September 2010), Project Bamboo identified a number of characteristics of humanities scholarship that point to a need for a broadly-federated and loosely-coupled identity and access management (IAM) infrastructure. The assumptions that influenced design and implementation of Bamboo's approach to IAM included:
By "broadly-federated" IAM infrastructure, we mean an infrastructure that allows faculty and students to log in via their home institutions; and also permits unaffiliated scholars ('citizen scholars') to use readily-available logins they are likely to maintain already, such as social media identities established with Google, Facebook, and other social media. Use of existing logins – and, in the case of institutional identities, logins that can be trusted, more-or-less, to belong to the faculty member or student who uses the login for access – is generally considered more convenient and reliable than establishment of multiple separate logins for tools or services relevant to the spectrum of a scholar's activity. (It is for this reason that institutions of higher education in the United States have formed the InCommon trust federation to federate the identity aspect of identity and access management; similar networks have been formed elsewhere, and trust between these national federations is an ongoing, as-yet-unrealized effort. See footnote [a] below for the context in which a Bamboo Trust Federation was posited by this project.)
By "loosely-coupled" IAM infrastructure, we meant that the same federated login ought to be applicable to a wide range of research environments, tools, and services, since the set applicable to humanities scholarship is large, diverse, and constantly evolving.
It is worth noting that no previously existing infrastructure fully addressed the goals (described below) that arise from the set of assumptions listed above at the time the Bamboo Technology Project commenced (October 2010).
This functionality was implemented with as little new coding as possible. Instead, Project Bamboo sought to integrate extant software libraries and applications, including Apache Web Server (httpd), Shibboleth, Grouper, and SimpleSAMLphp. Where new coding was necessary, adherence to established standards, such as XACML, was prioritized.
[b] As the Bamboo IAM infrastructure was implemented, the "minimal set of user attributes" required of an IdP includes only a user identifier unique to the IdP (a.k.a. a "scoped" user identifier); and a unique identifier of the IdP itself, generally the domain name of an institution or social media provider, such as berkeley.edu or google.com. A discussion of N-tier authentication and user attribute release in relation to Project Bamboo's work can be found in this documentation on the page Authentication - Current Limitations and Future Direction.
|It is noteworthy that here and elsewhere within the scope of this documentation the Bamboo 'branding' is used as a matter of convenience. The technology implemented and integrated may be differently-named by adopters as desired, within the requirements imposed by the open-source ECL2 software license that governs all intellectual property produced by Project Bamboo.|
The Bamboo Technology Project was conceived as a three-year software development effort, to be conducted in two phases. Only the first phase was funded. During this first phase, the underlying services to effect functionality described above were completed. In addition, test integrations between client applications and IAM infrastructure services, the latter intended to be hosted centrally, were conducted as proofs of functional utility. However, end-user interfaces were not built out; thus, provision has not yet been made for 'user-friendly' establishment and maintenance of Bamboo identities, profiles, groups, or policies. Such user-interfaces are left as work to be done by adopters of the Bamboo IAM infrastruture.
It is also noteworthy that while functional utility has been proven, instantiation of the Bamboo IAM infrastructure on servers hosted in production data centers were limited to development instances used for testing and integration purposes. Productionizing these servers, load testing, and documentation of deployment architectures was not undertaken in the funded phase of the project's technology development.
The basic requirements for a client application to participate as a trusted member of the Bamboo IAM ecosystem are described in the Implemented IAM functionality section, above.
As of the close of the Bamboo Technology Project, the implemented IAM infrastructure does not utilize N-tier authentication, as implementation and uptake of Enhanced Client Protocol (the technology we hoped to use in early stages of the project) was judged insufficiently mature to adopt in the timeframe of the Bamboo Technology Project. Details are discussed in this documentation on the page Authentication - Current Limitations and Future Direction.
In overview, the implementation approach used in lieu of N-tier requires that client applications be trusted to authenticate users and to make true assertions about those users' identities and roles to centrally-hosted services. This is a less-than-ideal approach because it limits use of fine-grained user-attributes in policy decisions. "Fine-grained user attributes" that could be supplied by an higher ed institution might include, for example, contact information (e-mail address, phone number, postal address, etc.); or affiliation type (e.g., faculty, student, staff, alumna). Use of such attributes might, for example, permit faculty members to access content licensed by an institution for faculty use but not for use by students or staff.
The reason that Bamboo's approach limits use of these fine-grained attributes is that passing user attributes between independent or loosely-coupled applications / platforms would violate the norms of trust agreements between Identity Providers and Service Providers.
To comply with the norms just described a "SourcedId" that uniquely identifies a user's login via a particular Identity Provider, irrespective of the client application that manages the authentication, is constructed of two distinct elements:
The SourcedId is only passed (as elements in an XML document or in a URL) for certain requests to the Person Service: those requests that associate, modify, or disassociate a Bamboo user identity with a login via one or multiple Identity Providers; and those that obtain for the client a Bamboo Person Identifier (BPId) which is used in subsequent requests to BSP-hosted services to identify the logged-in user. The BPId is transmitted in an HTTP request header, as described in the following paragraphs.
The IAM solution implemented by Project Bamboo requires a client application to add a set of HTTP headers to requests sent to IAM and other centrally-hosted services – those that, in project parlance, are hosted on the Bamboo Services Platform. These HTTP request headers include the following:
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 as described above.
[c] The value of X-Bamboo-BPID is set to the identifier for the application itself (X-Bamboo-AppID) when a client application calls the Person Service to create a new Bamboo Person Identifier; or to retrieve the BPId for a user based on the identifier of the IdP with which she has logged in and an SHA-256 hash of that IdP's user identifier for the logged-in person.
[d] Client applications are responsible for extracting the conventionally-represented IdP identifier from attributes available to it following successful user authentication; the appropriate string is expected to be the top-level domain and its immediate subdomain in the Apache httpd environment variable Shib-Identity-Provider available to the client on successful user authentication (e.g. extract "wisc.edu" from the Shib-Identity-Provider value "https://logintest.wisc.edu/idp/shibboleth"). Policies and policy evaluation are described on the page Authorization and Policy. Also see Conventions for representing Identity Providers in the Bamboo Trust Federation.
A client application to manage Bamboo identities (create identities, associate them with logins via trusted identity providers, update profiles) was begun in Fall 2012, but halted in mid-stream when future funding for the Bamboo Technology Project was not forthcoming. The client app was a Drupal module, named the Account Services Module, and was implemented to a point sufficient to constitute a Proof of Concept for (a) integrating a trusted client in the Bamboo Trust Federation; (b) processing authentication via independently-hosted Identity Providers (e.g., Google, UC Berkeley, UW Madison); and (c) managing identities through trusted-client web service calls to the Person, Contact, and Person Profile services hosted on the Bamboo Services Platform, including management of account linking (recognizing a user who logs in from any of multiple IdPs as the same individual, i.e., the same "Bamboo Person" identified by a single BPId).
An overview of the module's design and coding approach can be found on the page Account Services UI - Bamboo IAM Client - Drupal Module PoC. The Project Bamboo wiki archives contain a complete set of requirements for this application, cf. Account Services Drupal module workflow and the linked page Account Linking Service Draft Sequence Diagram (a search for the page names on the wiki instance at Berkeley where the archive is housed should turn up the page if the link breaks...). The draft sequence diagram for the Account Linking use case is also included directly below this paragraph (click thumbnail for a larger view), to illustrate the types of component interactions the Account Services Module is designed to orchestrate:
Discussion of integration of a Drupal instance with the Bamboo Trust Federation can be found on the page Client Environment-Tool-Service Integration with Bamboo IAM infrastructure.
Authorization for resources served by the services running on the Bamboo Services Platform (BSP), or resources for which the BSP manages policy, is described in some detail on the page Authorization and Policy. That page describes:
Bamboo's IAM infrastructure includes a number of component technologies in addition to the services developed to run on the Bamboo Services Platform (BSP), including the FUSE ESB that provides the deployment environment for the BSP. The diagram below, its labels, and the list beneath the diagram briefly describes these technologies and their function in the infrastructure.
The deployment topology implied by the purple boxes -- pairing the Social/SAML Gateway with Grouper, and the Account Services and Group Management UI – is not required; it reflects only the implemented or planned deployment topology used for development and testing during the course of the Bamboo Technology Project.
A - Identity Providers (IdPs): These exist independent of Project Bamboo, but are participants in the Bamboo Trust Federation described above. Institutional IdPs are generally SAML implementations, usually Shibboleth, operated by institutions of higher education; social media IdPs are generally commercial entities, such as Google or Facebook, widely trusted to provide identities associated with social media services.
B - Account Services User Interface: This interface was partially built as a Drupal module, and has been used to demonstrate client integration, cf. Account Services UI - Bamboo IAM Client - Drupal Module PoC. The purpose of this interface is to present to end-users an easily navigated, browser-based means of self-registration, profile maintenance, and 'account linking' (the latter refers to the ability to link a single Bamboo Person identity to logins via any number of IdPs).
C - Group Management User Interface: This interface was not built in the completed phase of work. Its purpose, when built or adapted, will be to present an easily-navigated, browser-based means to create and organize, populate, and manage groups that are maintained centrally. Memberships in centrally-maintained groups are intended to be used as factors in determining permissions (access to services and resources) across multiple applications and platforms. Cf. Group Service Contract Description - v0.9-alpha.
D - Social/SAML Gateway: This gateway transforms the user-attributes supplied by social media IdPs (e.g., Google, Facebook) into SAML assertions. SAML is the authentication lingua franca for the Bamboo IAM infrastructure.
E - Grouper: An Internet2 open-source application, Grouper is used to store data about known and trusted applications in the Bamboo ecosystem, and to store data representing groups created and managed by users. Users are expected to access these groups via the (to-be-implemented) Group Management User Interface (C, above); the Group Management User Interface and other client applications are intended to direct requests to the Group Service centrally-hosted on the Bamboo Services Platform. Grouper is an implementation choice used by the Bamboo Technology Project team to persist group-related data behind the Group Service. It is therefore, like the database used by services on the BSP, or the file system used for storage of some data, a technology located 'deep' in the background of the Bamboo ecosystem. Grouper is included on the diagram and listed here (while neither a database nor the BSP host's file system are referenced) because it is a less-common choice of persistence technology than a relational database or a server file system.
F - Bamboo Services Platform (centrally-hosted services): The BSP is an instance of Fuse ESB (based on Apache ServiceMix), used as a container (deployment host) for services intended to be run centrally as the 'hub' of Bamboo's IAM infrastructure, collection interoperability services (see Interoperability of Digital Collections), and proxied services that enable access to remotely-hosted tools for humanities scholarship (see Proxied Access to Remotely Hosted Tools for Scholarship).
G - Client application/tool/service: This placeholder in the diagram may be any application, research environment, tool, or service participating in the Bamboo Trust Federation, described above. The Account Services User Interface (B in the diagram) was partially-implemented during the Bamboo Technology Project (October 2010 to September 2012) as an example of how such a client can be integrated into the Bamboo ecosystem.
H - Shibboleth SP: This is a well-known and widely-deployed technology provided by the open-source Shibboleth project. As described on the project's web site, The Shibboleth Service Provider SSO-enables and Federation-enables web applications written with any programming language or framework. It integrates natively with popular web servers like Apache and IIS. A loosely coupled integration strategy allows you to support SAML, rich attribute-exchange, and many value-added features, often without significantly changing your application code or using proprietary interfaces.
I - Apache Web Server (httpd): This is a well-known and ubiquitously-deployed open-source web server technology. In the Bamboo IAM infrastructure, it is used to establish trust, via exchange of X.509 certificates (which may be self-signed) between applications/tools/services/platforms participating in the Bamboo Trust Federation, described above.
Additional diagrams based on the one shown above sketch component interactions:
Documentation about installation and configuration are principally located under the wiki page Install and Configure Technology Components.
For an architectural overview of services on the Bamboo Services Platform, including IAM services, see Architectural Overview of the Bamboo Services Platform.
Service APIs for Person, Person Profile, Contact, Group, Request Manager, Protected Resource, and other centrally-hosted services, see Service APIs - Centrally-Hosted Bamboo Services.