Shibboleth Bridging Element Deployment documentation

1 Shibboleth Bridging Element Installation

Shibboleth Bridging Element Installation

These installation only apply to Unix-based systems. In case explanations are not detailed enough, feel free to ask the developer (lukas.haemmerle@switch.ch) of the the Bridging Element in order to assist you and improve the documentation at the same time.

Prerequisites

This guide as well as the default configuration files uses the following values 
as example values. Please change them according to your setup.

Home/Remote Federation Name:        exampleFederation
Organisation Domain:                example.org
Bridging Element Hostname:          be.example.org

Usually if you need to replace or change something, it will be written
between # signs, e.g. in https://#BE.EXAMPLE.ORG#/shibboleth you would
replace the #BE.EXAMPLE.ORG# with the host name of your Bridging Element.

In most configuration files that need to be adapted, you will find the 
options that most likely need to be adapted within comments like

### EDIT SECTION START ###
[THINGS THAT NEED TO BE ADAPTED]
### EDIT SECTION END ###

When in the steps below is spoken of local Federation or only federation, 
then this always means the federation that you already have in place on your 
side and that shall be connected to eduGAIN. Depending on the context, your 
local federation acts as Home federation for users of your local federation, or 
as Remote federation for users of other federations accessing resources in your 
local federation.

You have to be an experiences UNIX administrator with a basic Unix and Apache
know-how in order to follow the installation steps. 
In addition, you should be familiar with installing and configuring a Shibboleth
Service Provider according to your federation's policies for installing the Home
Bridging  Element.

Before you start installing the Home and Remote Bridging Elements, it is 
recommended to start with the following:

1. Get a URN for your Bridging Element: 
   You should get a urn of the form:
   
   urn:geant:edugain:component:be:#FEDERATION NAME#:#BE NAME#
   and
   urn:geant:edugain:component:fpp:#FEDERATION NAME#

   where the values surrounded by # should be replaces by your local 
   federation's name and a name for the Bridging Element (hostname recommended).
   
   The 'be' urn is needed in order to get a certificate for your 
   Bridging Element whereas the 'fpp' urn is needed in order to get a 
   certificate that is required to publish metadata to the eduGAIN 
   Meta Data Service (MDS).
   If you already have an fpp urn and certificate for your federation, 
   you of course can skip this.
   
   Please refer to https://registry.edugain.org/browser/ for getting a URN or
   let a whole URN namespace be delegated to your own URN registry if you have
   any.

2. Get an eduGAIN accepted certificate for the Bridging Element.
  
   Once you have got a URN assigend to you, go to http://sca.edugain.org/ and
   create a certificate request for your Bridging Element(s). Make sure to use 
   the URN value of the above step for the component identifier value
   when creating the signing request.
  
   Unless your local federation already has got Registration Authority rights for 
   the eduGAIN CA or one of the other accepted eduGAIN Root CAs (refer to 
   http://www.edugain.org to see which CAs these are), you probably should apply 
   to get RA privileges for the eduGAIN SCA CA. More information concerning that 
   can be found as well on http://sca.edugain.org/

3. Once you got your eduGAIN accepted certificate, you have to convert it into
   a  java keystore. How to accomplish this relatively easy, is described in 
   Appendix A at the bottom of this document
   
4. Installation and configuration of the Bridging Element.
   As you will see the Bridging Element consists of a Home and a Remote Bridging 
   Element. In theory you could install them separately or only one of them, 
   which would be useful if you only wanted to grant the users of your local 
   federation access to other resources connected via eduGAIN but not vice versa
   (in this case you would only install the Home Bridging Element).
   However, in most cases you probably want to install both components.
   
   Refern to I. and II. below in order to install the Home and Remote Bridging 
   Element. 
   
5. After having installed Home and/or Remote Bridging Element, you must publish
   the metadata about them into the eduGAIN Metadata Service (MDS). This step is
   described in Appendix B.

Home Bridging Element Deployment

Note:
The Shibboleth Home Bridging Element cannot handle encrypted NameIDs in SAML2 assertions.
Therefore, one has to make sure that in the IdP's relying-party.xml file encryptNameIds="never"
for the saml:SAML2SSOProfile. This will be the default behavior for IdPs whose version > 2.1.2.

Note: As of May 2009, the Home Bridging Element must be protected by Shibboleth Service Provider 2.1 or newer. Shibboleth 1.3.x should not be used anymore it is not developed further and 1.3 support will be completely stop in June 2010.

The ShiBE-H translates authentication and attribute assertions from the local federation to eduGAIN assertions.

Since there is no Java Service Provider yet for Shibboleth, we have to use an Apache-Tomcat setup in order to make the attributes coming from Shibboleth available to the Java-based ShiBE-H. To get that up and running you have to do:

1. Install and configure Apache with SSL
- Get certificates supported in eduGAIN. You should find a guide how to
request a certificate, on this page:
https://www.rediris.es/jra5wiki/index.php/pkIRIS%20Guide%20for%20eduGAINSCA
You will need the certificate in a later step. Because it may take some time
until your request is being approved, you should do this first.

- In Apache, configure a <VirtualHost be.example.org:443> to support SSL on port 443.
You ca use any certificate you like for Apache.

Usually there comes a sample configuration for SSL with Apache.
Apache SSL Documentation: http://httpd.apache.org/docs/2.2/ssl/

2. Install and configure a Shibboleth Service Provider for your local federation
The Service Provider is needed by the Home Bridging Element in order to get
attributes for a user in the local federation. The Home Bridging Element
cannot ask an Identity Provider in the local federation directly for a user's
attributes.

- See your local Shibboleth federation's installation guides on how to install
a Shibboleth Service Provider 2.x . After installing and configuring it, you
should test the Service Provider to make sure that it receives a user's
attributes. This usually can be tested by accessing a Shibboleth-protected
web page like https://#BE.EXAMPLE.ORG#/secure with a web browser and
checking that the user's attributes were received by outputting the web
server's environment (e.g. with a PHP script that contains
<? print_r($_SERVER)?>).

- Make sure the Shibboleth attribute assertion is exported to a web server
environment variable. This can be achieved by adding the "exportAssertion"
XML attribute to the "host" element in the "RequestMap" element in the
shibboleth.xml configuration. E.g.
<Host name="#BE.EXAMPLE.ORG#" exportAssertion="true">

3. Install and configure Tomcat
You must install a Tomcat version >= 5.5.20 and mod_jk >= 1.2.20 because
since these versions it is possible to increase the maximum packet size of
HTTP headers passed on by the Apache module mod_jk to Tomcat.

Note:
Make sure you only use the Sun JVM/JRE for using the BEs and affiliated
tools. Using Kaffe or GNU Java, you may encounter strange behaviour or
errors that you won't see with Sun's Java

You may have to disable or configure the Tomcat security manager to read
the configuration files in /etc/eduGAIN

Tomcat Documentation: http://tomcat.apache.org/tomcat-5.5-doc/index.html

- Install tomcat so that the webapps are located in /opt/tomcat/webapps
You may use symlinks for that. E.g. if tomcat is installed under
/usr/lib/tomcat create a symlink like:
--
ln -s /usr/lib/tomcat /opt/tomcat
--

- Disable all connectors except the ajp1.3 connector (and any debugging
connectors) and make sure that the AJP connector looks like below.
Especially important is the XML attribute 'packetSize' that also will have
to be configured in mod_jk in step 4.
--
<Connector port="8009" address="127.0.0.1"
enableLookups="false" redirectPort="443" protocol="AJP/1.3"
tomcatAuthentication="false" packetSize="65536"
/>
--

- Endorse xalan and xerces libraries

--
rm ${PATH_TO_TOMCAT}/common/endorsed/*
cp ${PATH_TO_TOMCAT}/webapps/ShiBE-H/WEB-INF/lib/xalan* \
${PATH_TO_TOMCAT}/common/endorsed/
cp ${PATH_TO_TOMCAT}/webapps/ShiBE-H/WEB-INF/lib/xerces* \
${PATH_TO_TOMCAT}/common/endorsed/
--

4. Install and configure mod_jk
Mod_jk is an Apache module that can transfer HTTP requests for certain URLs
to Tomcat in order to be answered. So, mod_jk is a Tomcat connector for
Apache.
Don't use mod_jk2 if possible, it's deprecated.

mod_jk Documentation: http://tomcat.apache.org/connectors-doc/

- Modify your Apache configuration with something like below. Especially
important is that the URLs for ShiBE-R and ShiBE-H are served by Tomcat.
They should be accessible in via https://#BE.EXAMPLE.ORG#/ShiBE-H.

--
<IfModule mod_jk.c>
JkWorkersFile /opt/tomcat/conf/workers.properties
JkLogFile /opt/tomcat/logs/mod_jk.log
JkLogLevel info
JkMount /ShiBE-H/* ajp13
# Comment out the next line if you don't want to install the SHiBE-R
JkMount /ShiBE-R/* ajp13
</IfModule>
--

The worker ("ajp13") be be called different in your configuration. So, make
sure that you use the value specified for the worker in the
workers.properties file.

- Use a workers.property file like below. Espeically important is the last
directive, that increases the maximum size of an ajp13 packet.
--
# /etc/tomcat/workers.properties
# define a worker using ajp13
worker.list=ajp13
worker.ajp13.type=ajp13
worker.ajp13.host=127.0.0.1
worker.ajp13.port=8009
worker.ajp13.max_packet_size=65536
--
- Make sure the max_packet_size is set to 65536 (Bytes), the default value would be
too low to handle large GET and POST requests from mod_jk

5. Protect the URL /ShiBE-H/ with Shibboleth so that a user
accessing it must have a valid Shibboleth session that allows the ShiBE-H to
read the user's attribute assertion in order to translate it to an eduGAIN
assertion.

Apache configuration to Shibboleth-protect the ShiBE-H.
--
# Make sure the attributes are available for the whole ShiBE-H
<Location /ShiBE-H/>
AuthType shibboleth
ShibRequireSession off
ShibExportAssertion On
ShibUseHeaders On
require shibboleth
</Location>

# Enforce authentication for the listener
<Location /ShiBE-H/WebSSORequestListener>
AuthType shibboleth
ShibRequireSession On
ShibExportAssertion On
ShibUseHeaders On
require valid-user
</Location>
--

In case you are still using a Shibboleth 1.3 Service Provider, you need to remove the ShibUseHeaders directive because this feature is only available in Shibboleth 2.x.

Make sure you have an exportLocation in your shibboleth2.xml something like:

--
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
handlerURL="/Shibboleth.sso" handlerSSL="false"
exportLocation="http://127.0.0.1/Shibboleth.sso/GetAssertion"
idpHistory="false" idpHistoryDays="7">
--

This will make sure that the Home Bridging Element can download the user's
assertion.

Test this by accessing /ShiBE-H/ShiBEWebSSOResponder with your web browser.
When you are redirected to the WAYF URL that you configured in your Shibboleth
configuration, it is most likely working as it is supposed to, provided you made
sure that the Shibboleth attribute request really works as suggested in step 2.

6. Install and configure the Shibboleth Home Bridging Element ShiBE-H
- Download the latest version of the ShiBE-H and the configuration files from
the eduGAIN Webpage
- Download the latest version of the ShiBE-doc files and unzip them.
- In the checked out directory 'ShiBE-H' you should find whe ShiBE-H.war file
in the 'dist' directory. If you want to recompile the war file, go to the
ShiBE-H directory and run 'ant war' (install Apache ant
first if you haven't already)

Note:
When compiling the Bridging Element yourself, you may have to make sure that you comment out
all instances of the following code:

/*
eduGAINComponentID cid = new eduGAINComponentID((SignableSAMLObject) root);
cid.checkFederationName(federationID);
cid.checkEntityName();
*/

in the file "net/geant/edugain/meta/rest/RESTClientImpl.java".
This is needed because the MDS metadata probably doesn't contain yet signed
meadata at the time you read this. Therefore, we you have to disable the validation for now.

- Copy the home/dist/ShiBE-H.war file to your tomcat/webapps directory
- Copy the 'doc/eduGAIN' directory from the unzipped ShiBE-doc files to '/etc/eduGAIN'
- Change permission of /etc/eduGAIN/hbe_targeted_ids.txt to be writeable by
the Tomcat user
- If tomcat hasn't unpacked the war file already, restart tomcat
If Tomcat doesn't automatically unpack the war file so that you finally
have a directory webapps/ShiBE-H/ you must do that manually by running
'jar x ShiBE-H.war' to get the same resul
- Have a look at the instruction at the bottom of this page on how to convert
your X.509 key and certificate from step 1. into a Java Keystore.
- Edit the file /etc/eduGAIN/edugain_client.properties according to the description
within the file
- Edit the file /etc/eduGAIN/home_bridging_element.properties to reflect your
deployment.
- Edit the files /etc/eduGAIN/hbe_* for attribute conversion and filtering

7. Test the Home Bridging Element
In order to make sure that the ShiBE-H works as expected, you will have to
access a web resource of another federation .
(e.g. https://kelimutu.switch.ch/aai or see
https://www.rediris.es/jra5wiki/index.php/eduGAIN%20testbed)

When you access a protected resource in the remote federation, you probably
will be asked to choose your Home Organization/Institution. In the list of
possible choices you should find an entry that contains 'eduGAIN',
'Other federation' or something similar. Choose that entry and you should be
redirected to a Remote Briging Element, which will present you a WFAYF (Which
Federation Are You From) page that should also contain a linke to the Home
Bridging Element you just installed. If the list doesn't contain the link to
your Home Bridging Element, you may have to ask the administrator of the
WFAYF service to include a link to your ShiBE-H. The link would then be:
https://be.example.org/ShiBE-H/WebSSORequestListener

Upon selecting the Home Bridging Element you just installed. You should be
redirected there. If everything is fine, the ShibE-H will redirect you to the
WAYF URL you configured in step 6 in the web.xml.

Upon selection your local Home Organization and authenticating there, you
should be redirected back to your Home Bridging Element and from there to the
Remote Bridging Element and from there to the web resoure in the remote
federation that you tried to access originally.

If you ever see a Tomcat error message, have a look at the tomcat log,
which should usually be in /var/log/tomcat/catalina*.out and check the
messages before the stacktrace. Most probably a file was not found or the
Shibboleth assertion was not available.

If you see an Apache error message, check the Apache error log,
e.g. /var/log/apache/error.log Probably you didn't configure mod_jk properly.

Remote Bridging Element Deployment

The ShiBE-R translates eduGAIN authentication and attribute assertions to 
assertions for your local Shibboleth federation.

If you haven't already installed the ShiBE-H you will have to set up at least a 
Tomcat web server (preferrably on port 443 with SSL support).

Prerequisites:
For the Remote Bridging Element you must have the following components installed
on the host you want to use it:
- (optional) Apache + mod_jk. This is not mandatory and in fact only Tomcat as 
  web server will work just fine. 
- Tomcat version >= 5.5.20
- You need an X.509 certificate that is accepted in your local federation

Do the steps 1 (except requesting a certificate for eduGAIN ), 3 and 4 of the 
above ShiBE-H instructions in order to set up Apache + mod_jk + Tomcat and make
sure the following line is  uncomment in the Apache configuration (provided you
use Apache as front-end web server).

--
JkMount         /ShiBE-R/*              ajp13
--

1. Install and configure the Shibboleth Remote Bridging Element ShiBE-R
  - Download the latest version of the ShiBE-R and the configuration files from
    the eduGAIN download page
  - Download the latest version of the ShiBE-doc files and unzip them.

2. Deploy ShiBE-R
  - Copy the  file remote/dist/ShiBE-R.war to your tomcat/webapps directory
  - If you haven't done this already, copy the doc/eduGAIN directory from the unzipped ShiBe-doc files
    to /etc/eduGAIN

3. There is Java keystore file called exampleFederation.jks  in /etc/eduGAIN
   You have to import an X.509 certificate/key pair into that store. The 
   certificate must be accepted in your local federation because it is used to
   sign assertions that are then sent to Service Provider in your federation.
   
   Follow the guide at the bottom of these instructions on how to create a Java
   keystore from a PEM formatted key and certificate.
   
   - Edit the file /etc/eduGAIN/remote_bridging_element.properties
     according to the given comments there.
     Change the paths, aliases and passwords to point to the keystore that you 
     created in step above.
   - Edit the files /etc/eduGAIN/rbe_* for attribute conversion and filtering
   - Start tomcat in order to make tomcat unpack ShiBE-R
     If Tomcat doesn't automatically unpack the war file so that you finally
     have a directory webapps/ShiBE-R/ you must do that manually by running
    'jar x ShiBE-R.war' to get the same result
     

4. Add a description of the BE to your local federations metadata as if it was 
   a normal Shibboleth Identity Provider. See the following example for a 
   metadata entry:
   
--
<EntityDescriptor entityID="urn:geant:edugain:component:be:exampleFederation:be.example.org">
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:mace:shibboleth:1.0">
        <Extensions>
            <shibmd:Scope xmlns:shibmd="urn:mace:shibboleth:metadata:1.0" regexp="false">be.example.org</shibmd:Scope>
        </Extensions>
        <KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:KeyName>be.example.org</ds:KeyName>
            </ds:KeyInfo>
        </KeyDescriptor>
        
        <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
        <SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest" Location="https://be.example.org/ShiBE-R/ShiBEWebSSORequester"/>
    </IDPSSODescriptor>
    
    <Organization>
        <OrganizationName xml:lang="en">EduGAIN Bridging Element</OrganizationName>
        <OrganizationDisplayName xml:lang="en">EduGAIN Bridging Element</OrganizationDisplayName>
        <OrganizationURL xml:lang="en">http://www.switch.ch/aai/help/</OrganizationURL>
    </Organization>
    
    <ContactPerson contactType="technical">
        <SurName>Technical Contact</SurName>
        <EmailAddress>admin@be.example.org</EmailAddress>
    </ContactPerson>
    <ContactPerson contactType="support">
        <SurName>Support Contact</SurName>
        <EmailAddress>support@be.example.org</EmailAddress>
    </ContactPerson>
    <ContactPerson contactType="administrative">
        <SurName>Administrative Contact</SurName>
        <EmailAddress>info@be.example.org</EmailAddress>
    </ContactPerson>
</EntityDescriptor>
--
   
   The following values are important:
   - entityID, which should correspond to the componentId value from 
     the /etc/eduGAIN/remote_bridging_element.properties
   - KeyName, which should be the subject of your certificate created in step 3
     or at least the common name of the subject.
   
   There is no AttributeAuthorityDescriptor needed in the metadata because the
   attribute request is not implemented yet.
   
5. Add an entry to your WAYF
   Because the ShiBE-R acts like an Identity Provider within your federation, you
   should add an entry to your federation's WAYF (Where Are You From service) in
   order to allow users from another federation to access this service.
   For that you have to create an entry like "Other federation via eduGAIN" or
   something similar. If the user chooses this entry, he should be redirected to
   the URL https://be.example.org/ShiBE-R/ShiBEWebSSORequester from 
   where on eduGAIN takes over.
   Once the user is authenticated in his Home Federation, he will return to your
   Remote Bridging Element from where on he is sent back to the Service Provider
   he tried to access initially.   
   
6. Testing the Remote Bridging Element
   As for the Home Bridging Element you can test your installation by 
   accessing a Resource protected by a Shibboleth Service Provider in your 
   federation. In the best case this Service Provider just should protect a page
   that displays all Shibboleth attributes. This could be a simple PHP script 
   that contains nothing than:
   --
   <?php print_r($_SERVER); ?>
   --
   
   This script then should show the attributes of an authenticated user. Upon
   access, you should be redirected to the WAYF you configured in the previous 
   step. There, you should choose the entry that points to the Remote Bridging 
   Element you installed.
   After authenticating in another federation (ask somebody to create you an 
   account in another federation), you should be returning back to your 
   Service Provider and see some attributes.
   If something fails, it is important to know where the error occurred. Check 
   first on which host the error was thrown. If it's not the host where your
   ShibE-R is installed and not the host where the Service Provider is 
   installed, the error happens somewhere in between where you cannot do much.
   If the problem occurred on your host, check which component displayed the 
   error. Is it Apache (check Apache's error.log), is it Tomcat or ShiBE-R 
   (check catalina.out) or is it the Service Provider you test against (check 
   the shibd.log). In all cases you should find more information about the 
   nature of the error in the relevant log files.

Logging

In order to enable logging, you may have to add or adapt the line:
--
net.geant.edugain.base.log.filter.logger=(ch.SWITCH|net.geant)
--
in the file /etc/eduGAIN/edugain_client.properties (default) and make
sure that the file /var/log/edugain.log is writeable by the system user
that Tomcat is running under.

Appendixes

A. How to generate a Java Keystore with X.509 certificates

Converting a PEM X.509 key and certificate pair into a JAVA Keystore is usually
quite cumbersome. Using the instructions below, this taks becomes very easy.

Preconditions:
- It is assumed that you accomplish this task on a UNIX-like system
- /bin/sh must exist on the system
- The 'java' binary must be in the path of executable files
- You must have a PEM or DER encoded X.509 private key and a certificate with
  the chain up to the root CA certificate attached
- You must have downloaded and unzipped the ShiBE-doc files

Within the doc folder you should find a folder called 'tools'. 
It should contain a script called 'create-keystore.sh' and a JAR file 
called 'not-yet-commons-ssl-0.3.9.jar'.
In order to create a JAVA keystore that is used by the Bridging Element, you 
have to to the following:

1. Change to the 'tools' folder with 'cd #PATH TO#/tools'
2. In your terminal, run './create-keystore.sh'
3. Provide a password for the keystore to be created, the path to the private
   key and the certificate.

If everything is successful, you should find a .jks file within your current 
working directory that was created with the password you provided.

If you want to achieve the same on Windows, run the following command:
java -cp not-yet-commons-ssl-<version>.jar
org.apache.commons.ssl.KeyStoreBuilder $PASS $KEY $CERT

and replace $PASS with a password, $KEY with the path to the private key and

$CERT with the path to a certificate file.

Alternatively you can run the command
java -cp not-yet-commons-ssl-<version>.jar
org.apache.commons.ssl.KeyStoreBuilder $PASS $PKCS12

and replace $PASS with a password, and $PKCS12 with the path to a PKCS12
(*.p12) file.

The resulting keystore's contents can be displayed with the command
keytool -list -keystore <...>.jks

B. How to publish metadata about your Bridging Element to the eduGAIN MDS

In order to make your Bridging Elements work with the other eduGAIN components, you will have to publish metadata about it to the official eduGAIN Metadata Service (MDS). In this case, you will be a Federation Peering Point (FPP).

Get a valid FPP certificate signed by the eduGAIN SCA CA and import it in a Java keystore (see Appendix A).
Prepare the metadata file to publish. You may have a look at the current MDS to get an idea of the format of the metadata. In addition there is a file Example-MDS-Metadata.xml file in the same directory as this file. Use it as a starting point for adaption.
Then have a look at eduGAIN Signing and uploading instructions on how to publish metadata.

Note: If you encounter strange errors when running the above command or script, make sure you are using Sun's JVM/JRE and not Gnu Java or Kaffe.

Common Problems

In case there is a StackOverflowError problem when Tomcat deploys the Bridging Element, you might want to try removing the JAR file slf4j-jcl-1.4.3.jar from the WEB-INF directory of the deployed WAR file and restart Tomcat again.

Bugs and feedback

Please report bugs and feedback to: lukas.haemmerle@switch.ch

Retrieved from "http://wiki.edugain.org/index.php5/Shibboleth_Bridging_Element_Deployment_documentation"

This page was last modified on 25 May 2009, at 11:03.

Enabling identity federation