The Shibboleth Proxy


Introduction

The aim of the Shibboleth Proxy is to provide an intermediate filter to the Shibboleth authentication system. This filter shall enable Shibboleth unaware applications to connect automatically and make use of HTTP-based service providers protected by the Shibboleth single sign-on authentication framework.

Technical Overview

The Shibboleth Proxy realises a user configurable HTTP proxy filter, which provides seamless access to shibbolized web service providers. For the time being, the proxy forwards any Http-request received from desktop applications to the destined service provider. Next, the proxy analyses the HTTP-response returned by the service provider. If the analysed response turns out to be a redirection request to a Shibboleth Identification Provider, the proxy takes control of the communication protocol and completely carries out the necessery authentication steps instead of by the user. When finished authentication, only the final response to its initial request is returned to the client application. This way, the Shibboleth Proxy enables any HTTP-compatible desktop application to connect to the Shibboleth SSO framework. Moreover, this can be realised without any modifications to the original software.

To subsequent client requests, the proxy adds the necessary Shibboleth identification tokens(cookies) to the HTTP-request header and forwards them to the intended destination. The required user credentials (username/password) must be provided by the user within the proxy's configuration file.

Specification

Along with the four main steps of the Shibboleth protocol, the following section provide more detailed information on how the Shibboleth Proxy recognises and filters Shibboleth protocol steps. Furthermore, the actions taken by the Shibboleth Proxy for each step will be explained in more detail.

Step 1 (Initial Client Request)

The Shibboleth Proxy simply forwards any HTTP-Request to its destination. Therefore, the Shibboleth Proxy rewrites the URL-scheme of any request to https.

Currently, the Shibboleth Proxy does not support the HTTPS-tunneling feature(HTTP CONNECT). Since, the target URL of a resource located on a Shibboleth SP, the target URL of the request must be modified by the client application such as it starts with the http URL-scheme.

The same issue applies for supporting Subversion clients. Here, the scheme of the URL contained in the HTTP-header named Destination must be rewritten to let Subversion clients working properly.

Step 2 (Redirection to IdP for authentication)

After having proxied the initial request to the potential SP, the Shibboleth Proxy awaits the SP's response. When the proxy receives the reponse, it searches the response regarding the existence of following properties:

  • a Set-Cookie header with a name starting with _shibstate_
  • a Location header

The proxy uses the value of the Location header to determine the target URL of request to be redirected.

When the IdP asks for authentication, the proxy automatically transmits the credential values configured with the related Shibboleth configuration option (see Configuration)

If neccessary, the analysis of the Location header may be updated in a later version in order to check the existence of the URL-parameters shire, target and providerId characterising IdP-redirections as well as the _shibstate cookie.

Step 3 (IdP Response to the Authentication Request)

When getting the response referring to the request being redirected to the IdP, it will be analysed regarding the existence of following properties:

  • a Set-Cookie header with a cookie name equalling to JSESSIONID
  • a form containing the ** form attributes action and method ** form parameters TARGET and SAMLResponse

If the value of the form attribute method equals to post, then a HTTP-POST request to the URL retrieved from the value of the form attribute action is created and sent to this URL probably being the URL of the SP's assertion consumer service. The request is completed by adding

  • the HTTP-header Referrer consisting of the URL formerly used for the redirection request to the !IdP(step 2)
  • the URL-encoded parameters TARGET and SAMLResponse according to the values read from the HTML-form of the !IdP response

and sent to the SP.

Step 4 (Final Request to the Target Resource)

In this final step, the response to the last request is analysed regarding the existence of

  • the HTTP-headers Set-Cookie with cookie names starting with
    • _saml_idp and
    • _shibsession_
  • a HTTP-header Location

Next, the request will be redirected to location given within the value of the Location header along with the cookies _saml_idp and _shibsession_ retrieved from the Set-Cookie HTTP-headers.

The resulting response from the SP should be the final response to the intial client request and will be delivered unchanged to the requesting client application.

Installation

Preliminaries

You need to have installed  Java SE6 on your computer. The Shibboleth Proxy may work with older Java versions or libraries as well, but this is untested. Please contribute your own experience, so we can publish this to others (especially MacUsers). Currently, the ShibProxy contains a ShibProxy.sh and a ShibProxy.bat file in order to run the Shibboleth Proxy on either Linux or Windows.

Furthermore, you should download the  Java(TM) Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6. This enables Java (the Shibboleth Proxy) to use cryptographic functions with full strength.

The file contains a directory jce. Extract the file and copy the content of that directory (not the directory itself) into the directory jre/lib/security of your java installation. When using Windows, this will usually be found in e.g. C:\Program Files\Java\jre1.6.0_07\lib\security. If you are using the JDK installation, look at C:\Program Files\Java\jdk1.6.0_07\jre\lib\security. Debian based Linux uses /usr/lib/jdk/jre/lib/security normally.

Download

Shibboleth Proxy (Alpha1) Shibboleth Proxy (Alpha1)

After having successfully downloaded the file, unpack the file somewhere in your home directory.

tar xvfz ShibProxy.tgz

Under Windows, you can use Zip-Programms like  WinZip or  7Zip to do this.

Libraries

The Shibboleth Proxy is programmed with  Java SE6 and uses the following libraries:

 Apache Commons beanutils 1.7  (lib)
 Apache Commons codec 1.3  (lib)
 Apache Commons collections 3.2  (lib)
 Apache Commons configuration 1.5  (lib)
 Apache Commons digester 1.8  (lib)
 Apache Commons lang 2.3  (lib)
 Apache Commons logging 1.1.1  (lib)
 Apache HttpComponents - HttpClient 4.0 alpha2  (lib)
 Apache HttpComponents - HttpCore 4.0 alpha6  (lib)
 Apache log4j 1.2.15  (lib)
 Jetty WebServer 6.1.6  (lib)

Configuration

The configuration of the Shibboleth Proxy is implemented using the  Apache Commons Configuration API. That means, it consists of two files:

  1. config.xml
  2. shibproxyConfig.xml

The Shibboleth Proxy comes preconfigured to be used with the current EDIT applications. Nevertheless, you still need to enter your EDIT username and password within the Shibboleth/Credentials section of the shibproxyConfig.xml file, if want to be authenticated automatically! If you are obliged to use an proxy server in order to access the internet, then the proxyHost and proxyPort entries within the Client section of the shibproxyConfig.xml file will be your friend! If you want to change the port the Shibboleth Proxy listens to, then rewrite the port entry within the Server section of the shibproxyConfig.xml file.

Initially, that's all you should have to configure. Change into the ShibProxy directory and start the Shibboleth Proxy

cd ShibProxy
./ShibProxy.sh
### Windows ###
./ShibProxy.bat

Below, you will find a detailed decription of the various configuration options of the Shibboleth Proxy.

config.xml

This file must be located within the working directory of the Shibboleth Proxy. It simply determines where to find the final configuration file.

Example config.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>
  <xml fileName="shibproxyConfig.xml" />
</configuration>

The attribute fileName within the element xml defines the file name of the proxy's configuration file (shibproxyConfig.xml).

shibproxyConfig.xml

Herewith, the Shibboleth Proxy has to be configured. The configuration file is written in XML, starts with an ShibbolethProxy element and includes the following configuration sections:

  • Client
  • Server
  • Shibboleth

Client section

The Client section defines options neccessary to the client-side functionality of the Shibboleth Proxy:

proxyHost(optional)
Defines the host name of a web proxy, which may be needed to access the internet in some domains.
proxyPort(optional)
Defines the port number of the web proxy specified within the proxyHost option.
truststoreFile
Defines the file storing certificate chains for the !IdP and SP server being accessed.
truststorePassword
The password to access the truststore file.
truststoreType
The type of the truststore (JKS or PKCS12)
keystoreFile(optional)
Defines the file storing the user's private key and certificate. This can be used for SSL-client authentication.
keystorePassword(optional)
The password to access the keystore file.
keystoreType(optional)
The type of the keystore (JKS or PKCS12)

Server section

The Server section defines options neccessary to the server-side functionality of the Shibboleth Proxy:

port
Defines the port number, the proxy listens to.
keystoreFile
Defines the file storing the private key and certificate of the Shibboleth Proxy. This is necessary to establish SSL connections to the Shibboleth Proxy.
keystorePassword
The password to access the keystore file.
keystoreType
The type of the keystore (JKS or PKCS12)

Shibboleth section

The Shibboleth section defines options neccessary to authenticate against the Shibboleth framework:

Credentials
Currently, only credential of type Username/Password were supported (attribute type). So, the next element define the username (or login id) and the passwort of the user, to which favour the Shibboleth Proxy shall authenticate.
Username
Login of the user within the domain of the authenticating IdP.
Password
Password of the user specified in the option Username.

Example shibproxyConfig.xml

Here is an example of a complete shibproxyConfig.xml configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<ShibbolethProxy>
	<Client>
		<proxyHost></proxyHost>
		<proxyPort></proxyPort>
		<truststoreFile>EDIT-WP5.7-truststore.jks</truststoreFile>
		<truststorePassword>public</truststorePassword>
		<truststoreType>jks</truststoreType>
	</Client>
	<Server>
		<port>8080</port>
		<keystoreFile>ShibProxy.p12</keystoreFile>
		<keystorePassword>editwp57</keystorePassword>
		<keystoreType>pkcs12</keystoreType>
	</Server>
	<Shibboleth>
		<Credentials type="UsernamePassword">
			<Username>your_username</Username>
			<Password>your_password</Password>
		</Credentials>
	</Shibboleth>
</ShibbolethProxy>

Using the Shibboleth Proxy

First, run the Shibboleth Proxy as follows: Change into the ShibProxy directory and start the Shibboleth Proxy

cd ShibProxy
./ShibProxy.sh
### Windows ###
./ShibProxy.bat

The Shibboleth Proxy will listen on localhost (127.0.0.1) port 8080 per default. Next, you must configure your browser, Eclipse or subversion client to use the Shibboleth Proxy as SSL proxy, or as general proxy if SSL proxying can not be configured.

Firefox

Open the Preferences dialog, select the Extented tab, click on network, Connection/Preferences. Then select manual proxy configuration and enter localhost and 8080 in the line SSL-Proxy.

Eclipse

Here, you will find the right dialog under Windows/Preferences/General/Network Connections. Select manual proxy configuration and enter localhost and 8080 in the line SSL-Proxy. This configuration applies to any Eclipse plugins, i.e. you can use the  ''Eclipse Trac Plugin'' as well as the SVN-plugins  ''Subversive'' or the former  ''Subclipse''.

Subversion

The original subversion client can be configured in the .eclipse/servers file within your home directory. Under Windows, this will be somewhat like C:\Dokumente und Einstellungen\username.

There, configure the entries http-proxy-host and http-proxy-port within the global section, to use the Shibboleth Proxy globally.

[global]
http-proxy-host = localhost
http-proxy-port = 8080

If you just want to use the Shibboleth client when accessing the host sp.e-taxonomy.eu, then you must define a group (sp), and configure the Shibboleth Proxy within a section of that group name.

[groups]
sp = sp.e-taxonomy.eu

[sp]
http-proxy-host = localhost
http-proxy-port = 8080

Attachments