Installing shibboleth on linux

Installing shibboleth on RHEL

First start with this reference: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall

They will tell you to use "yum" to install shibboleth as follows:

$ yum install shibboleth.x86_64

But before we can do that, we need to know what version of Red Hat Linux is being used. To do that use the following command:

lsb_release -i -r

If the command is not recognized, you'll need to install the tool:

# yum install redhat-lsb

My version was 5. We will need to know this version to know which shibboleth repo to use

Now follow this link to see the list of available repos:

http://download.opensuse.org/repositories/security://shibboleth/


Next we need to add the shibboleth repo so that 'yum' knows where to find it. To do that create a new file called shibboleth.repo under the folder /etc/yum.repos.d

shibboleth.repo

[shibboleth]
name=Shibboleth Repo
baseurl=http://download.opensuse.org/repositories/security://shibboleth/RHEL_5/

enabled=1

Now we can execute the yum install command

$ yum install shibboleth.x86_64

When I did this the first time, I got an error about a missing KEY. To ignore key verification execute the following command:

$ yum install --nogpgcheck shibboleth.x86_64

The shibboleth installation directory will be found in /etc/shibboleth

Here I assume you've already installed Apache web server (HTTPD)
To restart apache:

/etc/init.d/httpd restart

Then to startup shibboleth

/sbin/service shibd start

Now to test the connection, in your browser, visit the following URL:

http://your.server/secure

You should see this error message:

shibsp::ConfigurationException

The system encountered an error at Thu Sep 20 15:47:58 2012

To report this problem, please contact the site administrator at root@localhost.

Please include the following message in any email:

shibsp::ConfigurationException at (http://your.server/secure)

No MetadataProvider available.

This is fine because we know you haven't fully configured shibboleth yet, but at least we know shibboleth is running and is able to accept web requests

SELinux

According to the shibboleth wiki, they do not officially support SELinux and it is well known that shibboleth will not work with SELinux turned on. To set SELinux into permissive mode run the following commands

[root@webserver shibboleth]# getenforce
Enforcing
[root@webserver shibboleth]# setenforce 0
[root@webserver shibboleth]# getenforce
Permissive

Reference: SELinux and Shibboleth


Now let's get the shibboleth URL identified to enable webservices. To do that add the following to the file /etc/httpd/conf.d/shib.conf

<Location /Shibboleth.sso>
    SetHandler shib
</Location>

<Location /c/portal/login>
  AuthType shibboleth
#  ShibUseHeaders On
  ShibRequestSetting requireSession 1
  require valid-user 

</Location>

The ShibUseHeaders parameter is required to copy the session attributes into the request headers. The request headers will contain details about who's logging in to your web application.

Update (22/12/2015):  The use of ShibUseHeaders is not recommended due to some potential security threats. I've updated the above configuration to have ShibUseHeaders commented out. Instead it is advisable to use AJP and have shibboleth pass in the attributes as environment variables in tomcat. Reference: Avoid ShibUseHeaders

There are many online examples on how to configure apache to proxy requests to tomcat via AJP. Here's one reference: Apache and Tomcat AJP configuration 

Since I am using Liferay portal server, I protect the login url '/c/portal/login'



Again, restart httpd

/etc/init.d/httpd restart

To test that the shibboleth web service is running, in your browser visith the following URL:

http://your.server/Shibboleth.sso/Metadata

You should get back a response to download a Metadata file
You will use this Metadata file to now configure and test a live Shibboleth connection by following instructions here:

http://www.testshib.org/configure.html

Configuration attribute-map.xml

To map shibboleth attributes to an alias you can configure the /etc/shibboleth/attribute-map.xml file.
For my configuration I had uncomment the list of attributes at the bottom:

    <Attribute name="urn:oid:2.5.4.3" id="cn"/>
    <Attribute name="urn:oid:2.5.4.4" id="sn"/>
    <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
    <Attribute name="urn:oid:2.5.4.20" id="telephoneNumber"/>
    <Attribute name="urn:oid:2.5.4.12" id="title"/>
    <Attribute name="urn:oid:2.5.4.43" id="initials"/>
    <Attribute name="urn:oid:2.5.4.13" id="description"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.1" id="carLicense"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.2" id="departmentNumber"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.3" id="employeeNumber"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.4" id="employeeType"/>
    <Attribute name="urn:oid:2.16.840.1.113730.3.1.39" id="preferredLanguage"/>
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.10" id="manager"/>
    <Attribute name="urn:oid:2.5.4.34" id="seeAlso"/>
    <Attribute name="urn:oid:2.5.4.23" id="facsimileTelephoneNumber"/>
    <Attribute name="urn:oid:2.5.4.9" id="street"/>
    <Attribute name="urn:oid:2.5.4.18" id="postOfficeBox"/>
    <Attribute name="urn:oid:2.5.4.17" id="postalCode"/>
    <Attribute name="urn:oid:2.5.4.8" id="st"/>
    <Attribute name="urn:oid:2.5.4.7" id="l"/>
    <Attribute name="urn:oid:2.5.4.10" id="o"/>
    <Attribute name="urn:oid:2.5.4.11" id="ou"/>
    <Attribute name="urn:oid:2.5.4.15" id="businessCategory"/>
    <Attribute name="urn:oid:2.5.4.19" id="physicalDeliveryOfficeName"/>

The attribute I used to identify my users is by their email address. So I needed to map

urn:oid:0.9.2342.19200300.100.1.3

to

mail

The 'mail' attribute will then be included in the request headers which will be used to log the user into my webapp.

Configuring shibboleth2.xml

• For configuration modify the /etc/shibboleth/shibboleth2.xml file
• Look for the root element ApplicationDefaults and assign the entityID which must match what was assigned to you by the federation authority that you've registered with. I registered with the following: https://manager.test.aaf.edu.au/federationregistry/.  
• For AJP configurations we'll need to set the AJP prefix as attributePrefix="AJP_" as follows:

 

entityID

="https://your_domain/shibboleth.sso/shibboleth" attributePrefix="AJP_" REMOTE_USER="eppn persistent-id targeted-id">

• Once you've submitted your request to register, then they will respond to grant you access. They'll provide you some information on how to manage your server as a 'Service Provider' and choose some attributes you want to expose. 
• https://manager.test.aaf.edu.au/federationregistry/membership/serviceprovider
• In the Sessions element, set handlerSSL to true and cookieProps to https as follows:

        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="true" cookieProps="https">

• Look for the SSO element and remove the entityID attribute and set the discoveryURL as follows:

<SSO
     discoveryProtocol="SAMLDS" discoveryURL="https://ds.test.aaf.edu.au/discovery/DS">
  SAML2 SAML1
</SSO>

• Look for the MetadataProvider element and edit the uri attribute

        <MetadataProvider type="XML" uri="https://manager.test.aaf.edu.au/metadata/metadata.aaf.signed.complete.xml"
              backingFilePath="metadata.aaf.signed.complete.xml" reloadInterval="7200">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>

        </MetadataProvider>

• Look for the CredentialResolver element and make sure it looks like the following

<CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>

This is what will be used decode/encode communication between the service provider (you) and the IdP (Identity provider).
When registering with the federation authority you be asked for a certificate. Use the SSL certificate provided by your authority as the sp-cert.pem file, and use your private key as sp-key.pem for decoding.

If you encounter errors with shibboleth, you can find error logs at

/var/log/shibboleth/shibd.log 

Other intersting ways to configure shibboleth:
http://www.switch.ch/aai/support/serviceproviders/sp-access-rules.html

Configuring Apache mod_proxy_ajp with tomcat: https://confluence.sakaiproject.org/display/~steve.swinsburg/Fronting+Tomcat+with+Apache+via+mod_proxy_ajp

References:

https://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPJavaInstall
http://shibboleth.1660669.n2.nabble.com/AJP-to-Tomcat-for-an-SP-td6441551.html
http://serverfault.com/questions/432418/forward-shibboleth-environment-variables-to-tomcat-via-apache