This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.
This page describes configuration of the Apache Web Server (httpd) on the Bamboo Services Platform (that is, on the host running the FUSE ESB instance to which centrally-hosted Bamboo services are deployed). Example configuration files, httpd.conf and ssl.conf, that were in active use as of March 2013 are in the Project Bamboo code repository at:
The last section of this page describes a number of client responsibilities in establishing trust via client auth. Client generation of X.509 certificates and configuration of selected clients are covered in the Certificate Exchange section of this page. (Note that additional client configuration necessary for the client to operate as a Shibboleth Service Provider is included in this documentation on a separate page: Shibboleth SP Installation and Configuration for Bamboo Trust Federation Clients.)
Trusted (known) client applications (those calling services on the Bamboo Services Platform) are expected to participate in client auth. This might be effected by running Apache Web Server (httpd) on the client application's host, or by other means. Modest suggestions are made in this document regarding generation and handling of X.509 certificates exchanged with the Bamboo Services Platform host in order to (physically) establish trust; these suggestions assume are given in the contexts of a simple test client (Firefox Poster); and a PHP application. Other clients' mileage will undoubtedly vary.
The (physical) establishment of trust effects the step described on the page Identity and Access Management - Authentication and Authorization as "registering as a member of the Bamboo Trust Federation by exchanging and publishing appropriate metadata [...]."
Clients that are not trusted (known) are treated as anonymous for purposes of policy enforcement (access control, permissions). Anonymous clients may not assert the identity of a known users, so requests made from an anonymous client application are treated as if an anonymous user were making the request.
These instructions are drawn from Project Bamboo's practical experience installing and configuring Apache Web Server (httpd) v2.2.22 to handle client authentication via exchange of X.509 certificates. The virtual machines on which these instructions were proven were Fedora 16-64bit VMs hosted by Linode.com.
The client configuration suggestions given at the end of this document reflect experience configuring Firefox Poster and the Drupal-based Account Services Module for participation in the Bamboo Trust Federation.
Per the info bloc at the top of this page, the following documents configuration of the Apache Web Server (httpd) v2.2.22 on the Bamboo Services Platform (that is, on the host running the FUSE ESB instance to which centrally-hosted Bamboo services are deployed).
Installation of httpd is well-documented for most platforms. YUM or similar installation is what's probably wanted for a Linux box / VM.
On the Linode VMs used by Project Bamboo, the GUI client Webmin further simplified installation of httpd; from that interface, it's a point-and-click operation.
A certificate, private key, and intermediate certificate chain can be obtained from a certificate granting authority. GoDaddy was the commercial authority used by Project Bamboo.
These files should be placed in the location appropriate to the server on which httpd is installed. On the Fedora 16 VMs used by Project Bamboo, that directory was:
Note that the key must be made root readable/writable only; the crt files should also be readable by group & other. This directory and the filenames will be referenced in configuration set in ssl.conf; the examples given use filenames of GoDaddy certs utilized by Project Bamboo, others' filenames will differ.
The following examples are taken from configuration for Apache Web Server (httpd) v. 2.2.22 on a server whose DNS name was bsp-dev.projectbamboo.org. Please consult the httpd project documentation for current configuration advice.
Specific instructions listed here include ONLY changes necessary to freshly-installed configuration files for httpd v2.2.22.
(your location for the SSL Engine log may differ)
Certificate, Certificate Key, and Certificate Chain files were purchased by Project Bamboo from GoDaddy.com (hence the gd_bundle.crt filename). A self-signed certificate may be used instead, provided clients and client applications do not require the assurance of server identity provided by a cert signed by a known Certificate Authority.
(Note that in-line comments included in the standard ssl.conf file are omitted here for brevity and clarity.)
These settings assume:
To physically establish trust between the Bamboo Services Platform and a client application, X.509 certificates are exchanged. The client supplies a Bamboo Services Platform administrator with a PEM-formatted public X.509 certificate, while retaining control and confidentiality of the corresponding key.
A client may generate a self-signed X.509 certificate and key using openssl (or other software of your choice). The following console dialog may be illustrative for those who wish to use openssl.
Due to unresolved problems encountered with certificates in which an e-mail address was part of the Subject DN, it is recommended that no e-mail address be supplied in the console-dialog that occurs when generating a self-signed certificate. Cf. JIRA issue IAM-103, marked as "Won't Fix" as of 22 April 2013.
You can view the newly created public cert using this openssl command:
If you wish to use a web browser as a trusted client to make calls to the Bamboo Services Platform, you will need to identify your browser with the key just generated above, to prove that the browser owns/controls the key corresponding to the public X.509 certificate. To do this with Firefox, for example, in order to use the Poster plugin to send requests to the BSP endpoint, you will need to export the key to PKCS12 format for import into Firefox. Here's how:
Assumption: the trusted client's administrator has generated or otherwise-produced a confidential key and corresponding public X.509 certificate, the latter in PEM format; and has supplied a Bamboo Services Platform administrator with the public, PEM-formatted X.509 cert.
The directory in which Apache Web Server (httpd) expects to find a client's PEM-formatted cert is specified with the Apache directive SSLCACertificatePath . In the example configuration given above, the directive looks like this in the ssl.conf file:
Having received the client administrator's PEM-formatted X.509 cert, the Bamboo Services Platform admin has a two step process to complete:
(1) copy PEM file to directory specified in SSLCACertificatePath
(2) create a symbolic link to the PEM file as required by httpd
Certificates in this directory must have filenames (or, better yet, symbolic links pointing to original files w/ filenames) that are hashes of the cert contained in the file, with a suffix of <period><zero>. To derive the appropriate hash, use openssl. Then create a symbolic link. Example (console output redacted for brevity):
For more detail, including circumstances in which a different numeral than zero is appended to the symbolic link or renamed cert, a description of configuring certs in this directory is given in the httpd-users mailing list archives of a message from Mark Montague of 20 July 2011: Configuring SSLCACertificatePath in httpd-ssl.conf.
Registration of known client applications requires some administrative prestidigitation in Grouper, explained in detail on the page Maintaining Application Catalog Data for Trusted Clients.
Poster is a Firefox add-on "that lets you make HTTP requests, set the entity body, and content type." For convenience, the add-on was utilized heavily by developers of Bamboo services during the course of the Bamboo Technology Project.
Configure Firefox to identify web service requests with the trusted client's key
The following instructions are valid for Firefox v.19.0.2, and were tested on a Mac.
Configure Firefox to trust the Bamboo Services Platform when establishing an SSL connection
This step is not necessary if the Bamboo Services Platform identifies itself with a certificate signed by a known certificate authority. This was the case in all testing performed by project teams in the course of the Bamboo technology Project.
However, configuration of a self-signed cert to be trusted by the browser and poster client should mimic the configuration process described above for the client-side cert. The differences are:
This documentation reflects practical, early experience configuring a Drupal-hosted client module (cf. Account Services UI - Bamboo IAM Client - Drupal Module PoC). These are not general instructions for configuring clients, or even for configuring PHP clients. Inclusion of these notes is indented to be a pointer to an early example, not a general prescription.
The PHP Client URL Library (cURL) may be used to construct RESTful calls to BSP-hosted services.
That module includes the code in bamboo_as_rest.inc, which includes execution of the curl_setopt function to assemble or point to the appropriate X.509 certificate .key and .pem files, and the file that includes the BSP's public X.509 cert, to be utilized in the request. This code is not well developed (e.g., it hard codes location of the relevant files), but it does represent a skeleton for how a better-developed codebase might be written to leverage the PHP cURL library.
A code snippet that sets key and cert values might look something like this: