Tuesday, August 13, 2013

Set up Shibboleth SP server for AAF integration on CentOS

1. System Requirements
  • Apache is installed.
  • Reverse proxy is set up.
  • SSL is enabled for Apache.
2. Install timer and sync time.
This step is very important, because Shibboleth SP server needs to run on a server which system time is sync with the IDP server. 
$ sudo yum install ntp $ sudo ntpdate server 0.centos.pool.ntp.org
3. Install & config Shibbloleth
Please refer to http://wiki.aaf.edu.au/tech-info/sp-install-guide for a full document.
Download and installation (as root)
# yum install httpd mod_ssl # wget http://download.opensuse.org/repositories/security://shibboleth/CentOS_CentOS-6/security:shibboleth.repo -P /etc/yum.repos.d # yum install shibboleth
Generate certificate with the correct hostname
Run the following, substituting the externally visible hostname for sp.example.org:
# cd /etc/shibboleth # ./keygen.sh -f -h sp.example.org -e https://sp.example.org/shibboleth


Download AAF metadata signing certificate

AAF Test Federation
# wget https://ds.test.aaf.edu.au/distribution/metadata/aaf-metadata-cert.pem -O /etc/shibboleth/aaf-metadata-cert.pem
AAF Production Federation
# wget https://ds.aaf.edu.au/distribution/metadata/aaf-metadata-cert.pem -O /etc/shibboleth/aaf-metadata-cert.pem

Edit /etc/shibboleth/shibboleth2.xml

Replace all instances of sp.example.org with your hostname.
  1. In the <Sessions> element, make session handler use SSL: set handlerSSL="true"
    and set cookieProps="https"
  2. change the handlerURL from a relative one ("/Shibboleth.sso" to an absolute one - handlerURL="https://sp.example.org/Shibboleth.sso".
  3. Optionally, customize in the <Errors> element the pages and settings. Your users will come in contact with these if an error occurs. Change the SupportContact attribute to something more meaningful than root@localhost.
  4. Load the federation metadata: add the following (or equivalent) section into shibboleth2.xml just above the sample (commented-out) MetadataProvider element
    AAF Test Federation
    <MetadataProvider type="XML" uri="https://ds.test.aaf.edu.au/distribution/metadata/metadata.aaf.signed.complete.xml"
         backingFilePath="metadata.aaf.xml" reloadInterval="7200">
       <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
       <MetadataFilter type="Signature" certificate="aaf-metadata-cert.pem"/>
    AAF Production Federation
    <MetadataProvider type="XML" uri="https://ds.aaf.edu.au/distribution/metadata/metadata.aaf.signed.complete.xml"
         backingFilePath="metadata.aaf.xml" reloadInterval="7200">
       <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
       <MetadataFilter type="Signature" certificate="aaf-metadata-cert.pem"/>

  5. Locate the <SSO> element (new in SP 2.4) and:
    • Remove reference to default idp.example.org - delete the entityID attribute.
    • Configure the Discovery Service URL in the discoveryURL attribute:
      AAF Test Federation
      AAF Production Federation

Edit /etc/shibboleth/attribute-map.xml

Mapping all attributes you need to request from IDP.

64-bit platforms

On x86_64, if you have installed also the i386 version of shibboleth and its configuration Apache configuration file is taking over, edit/etc/httpd/conf.d/shib.conf and change the path to the Shibboleth Apache module to the 64-bit version:
 LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_22.so


There are 2 different Shibboleth-related log files you can access for troubleshooting.
  • native.log: is located in /var/log/httpd and can be configured in /etc/shibboleth/native.logger
  • shibd.log: is located in /var/log/shibboleth and can be configured in /etc/shibboleth/shibd.logger
  • shibd_warn.log: is located in /var/log/shibboleth
Make sure that the right processes have write permissions to the log files!

Protect a resource

You can protect a resource with Shibboleth by configuring your Apache webserver. Edit the file /etc/httpd/conf.d/shib.conf, you can add as many location to protect by SP server as you want and /secure is a default example:
<Location /secure>
    ShibRequestSetting authType shibboleth
    ShibRequestSetting requireSession true
    require valid-user
More information on how to protect your resource can be found onhttps://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPhtaccess.

Register your SP server in AAF Federation Registry

Before you can use you SP server, you have to register it to AAF Federation Registry
AAF Test Federation
AAF Production Federation

Finishing up

Start up Apache and shibd:
# service httpd start
# service shibd start
# chkconfig httpd on
# chkconfig shibd on


In order to test if everything is working properly, lets create a simple PHP site which will require AAF authentication.
  1. Go to your apache documentRoot (/var/www/html) and create a directory called secure
  2. Create a file called test.php containing the following,
         while (list($var,$value) = each ($_SERVER)) {
               echo "$var => $value <br />";
  3. Edit the httpd.conf file and verify that the php5 module is uncommented.
    LoadModule php5_module libexec/apache2/libphp5.so
  4. Then you can test SP server set up by visiting https://hostname/secure/test.php.


We recommend shibd start before apache start so that in case of shibd errors, apache isn't trying to make erroneous connections while something is being fixed.

Configure Shibboleth to protect Java Servlets

We recommend shibd start before apache start so that in case of shibd errors, apache isn't trying to make erroneous connections while something is being fixed.

The Shibboleth SP is presently only implemented in C++ as a module for Apache httpd, IIS, and NSAPI. However, it's quite easy to use the Shibboleth SP to provide authentication information for Java servlets in a wide variety of servlet containers.
In the setup described here, requests from browsers are intercepted first by Apache httpd. The Shibboleth SP then checks these requests to enforce authentication requirements. After an assertion is received and a Shibboleth session is established, the SP or Apache httpd can enforce access control rules, or it can just pass attributes to the application. The request is then forwarded to the servlet through the use of the AJP13 protocol. Subsequent requests can leverage the Shibboleth session or a session maintained by the application or servlet container to persist the login.

Setup AJP13 support in your servlet container

This step depends on your servlet container.
  • Tomcat: Tomcat has an AJP 1.3 connector enabled by default.
    • Setting the tomcatAuthentication="false" attribute on the AJP <Connector> element allows for passing REMOTE_USER from Apache httpd. See Tomcat's AJP Connector documentation for more.
  • Jetty: Jetty's documentation has good instructions on how to enable both Jetty and your application to listen on AJP 1.3.
Be careful that there is no direct HTTP listener opened by the servlet container. If, for example, there's an HTTP connector listening on port 8080 and no interceding firewall, users would be able to directly access the servlet on port 8080, which bypasses Apache httpd. This also means they would bypass Shibboleth authentication and authorization.

Setup reverse proxy in Apache to redirect hostname/appname to ajp://hostname:8009/appname.

Step by step instruction of this step can be found http://blog.htxiong.com/2013/08/force-https-for-entire-serverdomain.html



Set up reverse proxy & Force https for entire server/domain

Sometime we need to disable http for the entire server/domain, then all applications regardless which web container/server it deployed on, will be only accessible via https.

To do this, we can disable http methods in Apache and use reverse proxy processing all requests to every application which is not with Apache but servlet web containers. And following content shows how to achieve this goal step by step.

Set up reverse proxy

a) Ubuntu: https://help.ubuntu.com/community/ApacheReverseProxy
b) CentOS

Install Apache HTTP Server

Make sure your system is up to date by issuing the following command:
yum update
Enter the following command to install the Apache HTTP Server:
yum install httpd
Issue the following command to start the web server:
/etc/init.d/httpd start
To ensure that Apache starts following the next reboot cycle, issue the following command:
chkconfig httpd on
To install PHP support, including common support bundles, issue the following command:
yum install php php-pear

Enabling the Proxy Module

The CentOS package of the Apache HTTP server includes the proxy module. To enable this module, create the /etc/httpd/conf.d/proxy.conf file with the following content.
File excerpt:/etc/httpd/conf.d/proxy.conf
<IfModule mod_proxy.c>
        #turning ProxyRequests on and allowing proxying from all may allow
        #spammers to use your proxy to send email.

        ProxyRequests Off

        <Proxy *>
                AddDefaultCharset off
                Order deny,allow
                Allow from all
        ProxyPass /app http://localhost:8080/app
        ProxyPassReverse /app http://localhost:8080/app
        # Enable/disable the handling of HTTP/1.1 "Via:" headers.
        # ("Full" adds the server version; "Block" removes all outgoing Via: headers)
        # Set to one of: Off | On | Full | Block

        ProxyVia On
This turns on proxy support in the module configuration. Please note the warning regarding the ProxyRequests directive. It should be "off" in your configuration. Next, we'll issue the following command to restart Apache:
/etc/init.d/httpd restart
Apache should restart cleanly. If you encounter any issues, you may wish to inspect the logs available under /var/log/httpd/ for more information.

How to create a ssl certificate on Apache

HOWTO: Disable HTTP Methods in Apache

There are a minimum of four components to a mod_rewrite rule; the directive that loads the module, the directive that turns the rewrite engine on, a rewrite condition, and a rewrite rule.
Since mod_rewrite is so commonly used, the directive that loads the module will more likely than not already be present. Search your apache configuraction file(s) for mod_rewrite.so (in /etc/httpd/modules). If it is not found, add the following line to your apache configuration file (typically known as /etc/httpd/confhttpd.conf):
 LoadModule  rewrite_module  path/to/apache/modules/mod_rewrite.so
To enable the rewrite engine and force https for entire server, add the following:
        # Enable the rewrite engine and force https for entire server
        RewriteEngine On 
        RewriteCond %{HTTPS} !=on
        RewriteRule ^/(.*) https://%{SERVER_NAME}/$1 [R,L]