Guides: Debian GNU/Linux 6.0 from sources Windows with IIS Solaris from sources  
  
URL: https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.4/sp/deployment/solaris-source.html
Author: Lukas Hämmerle - SWITCH
$Date: 2012-07-30 11:07:13 +0200 (Mo, 30 Jul 2012) $
$Revision: 1858 $

Deployment of Shibboleth Service Provider (SP) 2.4.3 on
Solaris from sources

Table of contents

0. Introduction

Note For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the deployment section of the SWITCHaai website.

This guide describes the installation and configuration of a Shibboleth Sevice Provider (SP) 2.4.3 on a Solaris from sources system.
It covers the installation of the Shibboleth web server module as well as the Shibboleth daemon and their configuration for the SWITCHaai or AAI Test federation.

For further information about the Shibboleth Sevice Provider, please have a look at the references.

Assumptions

Please ensure that the following prerequisites are met before proceeding with the installation of the Shibboleth Service Provider:
X.509 certificate
A valid certificate is required for decrypting SAML assertions and/or establishing SSL connections to Identity Providers.
Please refer to http://www.switch.ch/aai/certificates/ for further information about certificates and certificate requirements.
The same certificate can be used by the web server and by the Shibboleth Service Provider. However, it is recommended that Shibboleth uses a self-signed certificate whereas the web server should use a certificate from a well-known CA.
Please follow the steps described below to create a self-signed certificate for between the Shibboleth components. See SWITCHaai Certificate Acceptance Policy.

Known issues

The following issues are known and should be taken into account when installing a Shibboleth Service Provider:
libcurl SSL/TLS support
The Shibboleth Service Provider requires that the libcurl library is linked against openssl and not gnutls.

1. Setup Profile

In order make configuration easier and more convenient we kindly ask you to provide some information about your environment. This allows aut-generating and custom-tailoring some of the configuration files.

In which federation would you like to deploy your SP?
FQDN of the service?
Please provide the entityID (unique identifier) of the Service Provider:
Note The convention is to pick an entityID of the form https://#service host name#/shibboleth. In cases where the service host name (e.g. elearning.example.org) is different from the system name (e.g. web-host27.example.org), one should always use the service hostname.
Filesystem path to the configuration directory:
Note The location of the custom configuration should be separated in the /etc/shibboleth/ directory. It allows upgrading the Shibboleth Service Provider software without overwriting the existing configuration.
Filesystem path to the X.509 key:
Filesystem path to the X.509 certificate:
Filesystem path to the installation directory:
Filesystem path to the logging directory:
URL of the resource?
Support contact email address of the resource (will be shown in error Shibboleth messages):

1.1 Quick download of configuration files

If you are in a hurry and know the whole setup process, you can download all relevant configuration files directly here:

2. Prerequisites

Before starting to build and configure the Shibboleth Sevice Provider, assure that the following prerequisites are met:
Apache HTTP 2.2
For configuration, see at the Apache HTTP documentation in the references.
NTP
Servers running Shibboleth must have their system time synchronized in order to avoid clock-skew errors:
Shibboleth build environment
Since the Shibboleth Service Provider is implemented in C/C++, some C/C++ build tools are needed
(e.g. Sun Studio C/C++ Compiler from the packages SPROcc and SPROcpl.

3. Installation

Please follow the instructions on https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSolaris10SourceBuild or listed below.

Note For some general Solaris installation information, take a look at https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSolarisInstall
Warning Currently the following installation instructions need to the follwing patch for a successful build:
https://bugs.internet2.edu/jira/browse/SSPCPP-157
SP Components"); $stop = strpos($raw, "

Installation

"); $content = substr($raw, $start, $stop-$start); $content = str_replace("/display/", "https://wiki.shibboleth.net/confluence/display/", $content); $content = str_replace("/images/icons/", "https://wiki.shibboleth.net/confluence/images/icons/", $content); $content = str_replace("/opt/shibboleth-sp", substr($installHome,0,-1), $content); // clean up src $lines = preg_split("/\n/", $content, -1, PREG_SPLIT_NO_EMPTY); foreach ($lines as $line) { if (preg_match("/src=\"\//", $line)) continue; echo $line; } ?>

3.3 Define the current Shibboleth SP release

Note It is recommended to create a symlink /opt/shibboleth-sp/, which points to the current Shibboleth Service Provider software release (e.g. /opt/shibboleth-sp-2.4.3/ Installing/updating it this way, prevents you to adjust all the path references in the configuration files each time and allows you smoothly upgrades between new software releases/patches.
Symlink the current installation: 
if [ -L /opt/shibboleth-sp2 ] ; then sudo rm /opt/shibboleth-sp2 ; fi;
sudo ln -sf $SHIB_HOME /opt/shibboleth-sp2

3.4 Install Shibboleth Apache module

Create the file /etc/apache2/mods-available/shib.load:
Create the file /etc/apache2/mods-available/shib.conf:
Adjust the Apache configuration /etc/apache2/envvars: 
...
...
# This file is generated from envvars-std.in
#

export LD_LIBRARY_PATH=/opt/shibboleth-sp/lib
Enable the Shibboleth Apache module: 
sudo a2enmod shib

Install Shibboleth daemon

Copy the distribution init script: 
cp $SHIB_HOME/etc/shibboleth/shibd-debian /etc/init.d/shibd
Adjust the init script: 
PATH=/sbin:/bin:/usr/sbin:/usr/bin
DESC="Shibboleth 2 daemon"
NAME=shibd
SHIB_HOME=/opt/shibboleth-sp/
SHIBSP_CONFIG=/etc/shibboleth/shibboleth2.xml
LD_LIBRARY_PATH=$SHIB_HOME/lib
DAEMON=$SHIB_HOME/sbin/shibd
SCRIPTNAME=/etc/init.d/$NAME
PIDFILE=/var/run/$NAME.pid

...
Install the init script: 
chmod +x /etc/init.d/shibd
cd /etc/init.d
ln -s shibd /etc/rcS.d/K28shibd
ln -s shibd /etc/rc0.d/K28shibd
ln -s shibd /etc/rc1.d/K28shibd
ln -s shibd /etc/rc2.d/K28shibd
ln -s shibd /etc/rc3.d/S15shibd

Prepare your custom configuration

Warning This step is only needed if you do a fresh installation. In case of an update, these steps will overwrite the existing configuration files, which may not be what you want!
Copy some configuration files: 
mkdir /etc/shibboleth/ 

cp $SHIB_HOME/etc/shibboleth/native.logger /etc/shibboleth/ 
cp $SHIB_HOME/etc/shibboleth/shibd.logger /etc/shibboleth/ 
cp $SHIB_HOME/etc/shibboleth/syslog.logger /etc/shibboleth/

Prepare logging directory

Note This step is only needed if you do a fresh installation. In case of an update these steps where already done.
Note The Shibboleth Apache module log (/etc/shibboleth/native.logger) runs by the Apache process and has to be writeable.
Create logging directory and set according permissions: 
mkdir -p /var/log/shibboleth/ 
touch /var/log/shibboleth/shibd.log 
touch /var/log/shibboleth/native.log 
touch /var/log/shibboleth/native_warn.log 
chgrp www-data /var/log/shibboleth/native.log 
chmod g+w /var/log/shibboleth/native.log 
chgrp www-data /var/log/shibboleth/native_warn.log 
chmod g+w /var/log/shibboleth/native_warn.log

Define the current Shibboleth SP release

Note It is recommended to create a symlink /opt/shibboleth-sp/, which points to the current Shibboleth Service Provider software release (e.g. /opt/shibboleth-sp-2.4.3/ Installing/updating it this way, prevents you to adjust all the path references in the configuration files each time and allows you smoothly upgrades between new software releases/patches.
Symlink the current installation: 
if [ -L /opt/shibboleth-sp2 ] ; then rm /opt/shibboleth-sp2 ; fi;
ln -sf $SHIB_HOME /opt/shibboleth-sp2

4. Configuration

4.1 Self-signed certificate generation

Note You can skip this if you are going to use a certificate from a well known CA or if you already created a self signed certificate in a previous installation.
Note Please consider that a self-signed certificate has to fulfil certain requirements. Using the command below will respect all those requirements.

For creating a self signed certificate follow these steps: 

cd /etc/shibboleth/    
sudo sh $SHIB_HOME/etc/shibboleth/keygen.sh -h sp.example.org -y 3 -e https://sp.example.org/shibboleth

4.2 Logging

The Shibboleth Apache module log is configured by /etc/shibboleth/native.logger: 

...
log4j.appender.native_log.fileName=/var/log/shibboleth/native.log
...
log4j.appender.warn_log.fileName=/var/log/shibboleth/native_warn.log
...

The Shibboleth daemon log (shibd.log) and the transaction log (transaction.log) are configured in the file /etc/shibboleth/shibd.logger: 

...
log4j.appender.shibd_log.fileName=/var/log/shibboleth/shibd.log
...
log4j.appender.warn_log.fileName=/var/log/shibboleth/shibd_warn.log
...
log4j.appender.tran_log.fileName=/var/log/shibboleth/transaction.log
...
log4j.appender.sig_log.fileName=/var/log/shibboleth/signature.log
...

4.3 Shibboleth service provider

The main configuration of the Shibboleth Service Provider is done in /etc/shibboleth/shibboleth2.xml:
Download the attribute map file, which contains the attribute definitions and defines the mapping from attributes to the web server HTTP environment variables: 
sudo wget -nc https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.4/sp/deployment/download/attribute-map.xml \
-P /etc/shibboleth/
Warning Before updating the Service Provider, it is strongly recommended to first backup the /etc/shibboleth/attribute-map.xml!
Note By default, Shibboleth 2.x uses environment variables instead of HTTP headers to improve security. If you need the HTTP Headers (i.e. by using mod_jk) you have to set the Apache directive ShibUseHeaders On within a protected application. Refer to the Native SP configuration for further information on this topic.
Download the attribute filtering policy: 
sudo wget -nc  https://help.switch.ch/aai/docs/shibboleth/SWITCH/2.4/sp/deployment/download/attribute-policy.xml \
-P /etc/shibboleth/
Warning Before updating the Service Provider it is strongly recommended to first backup the /etc/shibboleth/attribute-policy.xml!

4.4 Download federation specific file

Download the trust anchor certificate to verify metadata signatures: 
sudo wget http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem -P /etc/shibboleth/

Compare the certificate fingerprint with the fingerprint of the SWITCHaai Root CA certificate shown on https://www.switch.ch/pki/aai/: 

openssl x509 -in /etc/shibboleth/SWITCHaaiRootCA.crt.pem -fingerprint -sha1 -noout
SHA1 Fingerprint=3C:E2:5A:E0:9D:B4:BB:2B:FD:33:3C:22:80:39:F7:FC:4A:F9:2C:E9

4.5 Enable metadata access at entityID URL

According to the convention, the entityID should have the form of a URL. If the entityID is used as a URL (https://sp.example.org/shibboleth), this URL should return an entity's metadata. In order for this to work, the web server must be configured accordingly.

Create a new configuration file, e.g. /etc/apache2/sites-available/sp.example.org, or modify an existing one like default-ssl : 
<VirtualHost sp.example.org:443>

...

  Redirect seeother /shibboleth https://sp.example.org/Shibboleth.sso/Metadata

</VirtualHost>
Make sure to set all the SSLCertificateFiles to the right ones.
Enable the virtual hosts (default-ssl if you changed the default file otherwise the name of the file you created): 
sudo a2ensite default-ssl
Enable the ssl module: 
sudo a2enmod ssl

5. Run & Test

Test the configuration file: 
sudo /opt/shibboleth-sp/sbin/shibd -t -c /etc/shibboleth/shibboleth2.xml
Note If the output is only one line containing the following message, everything is as expected: 
overall configuration is loadable, check console for non-fatal problems
If there are any ERROR messages it is strongly recommended to have a look at the problem. WARN messages are generally not very serious but it also is recommended to examine the problem.
Start the Shibboleth daemon: 
sudo /etc/init.d/shibd start
Test configuration and restart Apache: 
sudo apache2ctl configtest
sudo apache2ctl restart
Use the status URL https://sp.example.org/Shibboleth.sso/Metadata for a quick test. This URL should return the dynamically generated XML metadata of this Service Provider.

AAI Resource Registry

In order to activate the Service Provider within the federation it is necessary to register it with the Resource Registry. After this procedure, the metadata of this Service Provider will be included in the federation metadata. Therefore, all AAI components will learn about this new Service Provider.
The purpose of the Resource Registry is to have an up-to date list of all Identity Providers and Service Providers in the SWITCHaai Federation.
(See the information about the Resource Registry) in order to generate federation metadata and various configuration files.

To register a Service Provider:
  1. Go to the AAI Resource Registry.
  2. Log in with a SWITCHaai or AAI Test account. Use organisation account to get access. In case your organisation doesn't operate yet an AAI Identity Provider, please ask aai@switch.ch for an account.
    SWITCHaai accounts can also be used to manage AAI Test resources but not vice versa.
  3. Click on the tab Resources
  4. Click on Add a Resource Description
  5. Click on Run Shibboleth 2.x wizard
  6. Fill out all forms that are marked incomplete. Some forms do not need to be filled out completely.
  7. After completing all sections (they should all be marked as 'optional' or 'ok'), click on Submit for Approval.
    A Resource Registration Authority administrator of your organization then has to approve the Resource Description in order to make it active. Only after this step, its description will be included in federation metadata.

Simple Test Resource

For a real test that shows if the Service Provider retrieves any user attributes from an Identity Provider, you must first protect a resource,
e.g. https://sp.example.org/secure/.
This can be accomplished by adding the following directives to the Apache site configuration,
e.g. /etc/apache2/sites-enabled/sp.example.org: 
<VirtualHost sp.example.org:443>
...

  <Location /secure>

    AuthType shibboleth
    ShibRequireSession On
    require valid-user
  </Location>

</VirtualHost>
Restart Apache: 
sudo apache2ctl restart
Note Further information about protecting resources with Shibboleth can be found at SWITCHaai - How to protect a resource with Shibboleth access rules web page.

After restarting Apache, try to access: https://sp.example.org/secure/. This directory is protected by Shibboleth in the default configuration. Even if the directory does not exist. When accessing this URL the authentication should be initiated and one should be redirected either to the WAYF or to an Identity Provider.
Upon successful authentication, a HTTP 404 error (File not found) might be returned, because there might be no directory /secure in the web server root directory.
Anyway, if you can access https://sp.example.org/Shibboleth.sso/Session and get back information about the session like the issuer (IdP) and released attributes, this is a good test that the Service Provider was set up successfully.

If more testing is needed, e.g. to get the values of the released attributes, add a simple PHP script into the secure/ directory, like that index.php: 
<html><body><pre>
<?php print_r($_SERVER); ?>
</pre></body></html>
This PHP script has to be placed in a Shibboleth protected directory (e.g. /secure from above). If successfully authenticated and authorized, you should see some environment variables that contain your user attributes.

6. Troubleshooting

6.1 Logfiles

If some of the above tests are unsuccessful, we recommend the following procedure:

Note In order to avoid the log files to grow to enormous sizes, set the log level to an accurate level like WARN or INFO after debuging.

6.2 Common problems

Find below a list of common problems and possible solutions:
No log files are written
Check the permissions of the log files or the path for the log files set in /etc/shibboleth/native.logger or /etc/shibboleth/shibd.logger . If shibd is not run as root user, you might have to adapt the owner of the log directory and files to the user that runs shibd.
No attributes/Certificates problems
Check the Apache SSL certificate with the https://tools.switch.ch/certchaintest/ to make sure the full certificate chain up to the root CA certificate is attached to your certificate.

In case you don't understand or don't find the cause of the error, have a look at the NativeSPTroubleshootingCommonErrors web page.

7. Productionalization

Some good practices according Service Provider productionalization:

BEST CURRENT PRACTICES for operating a SWITCHaai Service Provider
The document describes best current practices for operating a Service Provider (SP) within the SWITCHaai federation in production use. It is meant to cover service management and operational related aspects as well as the technical infrastructure for successfully operating an SP.
Subscribe to the SWITCHaai mailing lists
Important information about the SWITCHaai federation are distributed by the AAI-Operations mailing list. Therefore the administrator of the Service Provider should subscribe to the list.
News and announcements are sent by the AAI-Announce mailing list. You might subscribe to it as well.
Customizing error pages
The error pages and messages can be configured in /etc/shibboleth/shibboleth2.xml: 
<Errors
  session="sessionError.html"
  metadata="metadataError.html"
  access="accessError.html"
  ssl="sslError.html"
  localLogout="localLogout.html"
  globalLogout="globalLogout.html"
  supportContact="aai@example.org"
  logoLocation="https://www.switch.ch/aai/design/images/SWITCHaai.gif"
  styleSheet="https://www.switch.ch/aai/design/shib-error.css"/>
Adjust at minimum the logoLocation and styleSheet. You may want to fully customize the html pages.
Note See https://wiki.shibboleth.net/confluence/display/SHIB2/Productionalization, section Service Provider for more information.

8. References 

--
$Id: index.php 1858 2012-07-30 09:07:13Z haemmer $