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.)
|Table of Contents|
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.
#ServerName www.example.com:80 # ==> PERSON mod DD MM YYYY # set server name properly ServerName bsp-dev.projectbamboo.org # <== end of mod
# UseCanonicalName Off # ==> PERSON mod DD MM YYYY UseCanonicalName On # <== end of mod
(your location for the SSL Engine log may differ)
# <== # PERSON mod DD MM YYYY # <IfModule mod_ssl.c> ErrorLog /var/log/httpd/ssl_engine.log LogLevel debug </IfModule> # end mod ==>
## ## SSL Virtual Host Context ## <VirtualHost _default_:443> # General setup for the virtual host, inherited from global configuration #DocumentRoot "/var/www/html" #ServerName www.example.com:443 # <== # PERSON mod DD MM YYYY ServerName bsp-dev.projectbamboo.org:443 # end mod of DD MM YYYY ==>
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.)
# <== # PERSON mod DD MM YYYY SSLCertificateFile /etc/pki/tls/certs/WILDCARD.projectbamboo.org.crt SSLCertificateKeyFile /etc/pki/tls/certs/WILDCARD.projectbamboo.org.key SSLCertificateChainFile /etc/pki/tls/certs/gd_bundle.crt SSLCACertificatePath /etc/pki/tls/certs/ca-certs-directory/ # end mod of DD MM YYYY ==>
#SSLVerifyClient require #SSLVerifyDepth 10 # <== # PERSON mod DD MM YYYY SSLVerifyClient optional SSLVerifyDepth 1 SSLOptions +StdEnvVars +ExportCertData # end mod of DD MM YYYY ==>
#SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire # <== # PERSON mod DD MM YYYY # SSLOptions +StdEnvVars +FakeBasicAuth +ExportCertData # end mod of DD MM YYYY ==>
These settings assume:
# # <== PERSON mod DD MM YYYY # # add proxy pass directives to forward "/services" traffic to Bamboo Services Platform -- over AJP # example of request URL: https://localhost/services/bsp/persons ProxyIOBufferSize 65536 ProxyPass /services ajp://localhost:8009 # end mod DD MM YYYY ==>
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.
$ openssl req -x509 -nodes -days 3660 -newkey rsa:2048 -keyout my_selfsigned.key -out my_selfsigned.pem Generating a 2048 bit RSA private key ..............................+++ ..............+++ writing new private key to 'my_selfsigned.key' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:CA Locality Name (eg, city) :Berkeley Organization Name (eg, company) [Internet Widgits Pty Ltd]:UC Berkeley Organizational Unit Name (eg, section) :Project Bamboo Common Name (eg, YOUR name) :Steve Masover Email Address : $ $ ls my_selfsigned.key my_selfsigned.pem $
You can view the newly created public cert using this openssl command:
openssl x509 -in my_selfsigned.pem -noout -text
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:
$ openssl pkcs12 -export -out my_selfsigned.pfx -inkey my_selfsigned.key -in my_selfsigned.pem Enter Export Password: Verifying - Enter Export Password: $ ls -l total 24 -rw-r--r-- 1 masover staff 1675 Mar 18 13:18 my_selfsigned.key -rw-r--r-- 1 masover staff 1541 Mar 18 13:18 my_selfsigned.pem -rw-r--r-- 1 masover staff 2701 Mar 18 13:20 my_selfsigned.pfx $
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):
# openssl x509 -noout -hash -in my_selfsigned.pem af21f59e # # ln -s my_selfsigned.pem af21f59e.0 # ls -l # ls -l lrwxrwxrwx 1 root root 15 Jan 14 16:14 af21f59e.0 -> my_selfsigned.pem -rw-r--r-- 1 root root 1493 Mar 18 17:34 my_selfsigned.pem #
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:
curl_setopt($session, CURLOPT_SSLKEY, "/my/location/mykey.key"); curl_setopt($session, CURLOPT_SSLCERT, '/my/location/mypubliccert.pem'); curl_setopt($session, CURLOPT_CAINFO, '/my/location/ca-bundle.crt');