Installation Guide

Shibboleth Identity Provider (IdP) - Installation Guide

For the Shibboleth IdP version 3, INFED recommends relying on an enterprise-grade Linux distribution with long term support: specifically, either Ubuntu Server LTS or Red Hat Enterprise Linux / CentOS.

As per above information, the sections below will configure the IdP with the following parameters:

  • the name of the University/Institute is yourdomain.org
  • the IdP URL idp.yourdomain.org
  • the IdP entityID https://idp.yourdomain.org/idp/shibboleth
  • Federation metadata available from http:// parichay.inflibnet.ac.in/metadata/infed.xml and https://parichay.inflibnet.ac.in/metadata/interfederation_sp.xml

1. System requirements

For the Shibboleth IdP 3, we recommend a system with at least 2 GB of memory (4 GB needed if you would like to avail the facility of interfederation services). The below basic tools also mandatory:

curl
It will help us to download software and configuration files.
OpenSSL
Package: openssl, the command-line tool will be used to deal with server certificates.
tar and unzip
Used to untar/unzip the archives (and also useful for listing contents of .war/.jar files).

2. Software Requirement

The Shibboleth IdP is developed under Java environment and therefore requires a Servlet container. Our recommended setup consists of the following components:

  • Apache HTTP Server 2.4 or higher
  • Apache Tomcat 7 for the Java Servlet container

3. Web Server (HTTP) installation

Before installing the Apache HTTP Server, get an SSL certificate for the service name of the IdP (idp.yourdomain.org) from a publicly trusted CA. Store the private key under /etc/pki/tls/private/idp.yourdomain.org.key and the certificate under /etc/pki/tls/certs/idp.yourdomain.org.crt, and make sure that the certificate file includes both the server certificate and any intermediate CA certificate(s). If SELinux is enabled on your system, verify that the two files have the correct context: use restorecon -nv /etc/pki/tls/private/idp.yourdomain.org.key /etc/pki/tls/certs/idp.yourdomain.org.crt to check, and if there's output from this command, rerun without -n to fix the context(s).

Then, install the Apache HTTP Server 2.4 with the following command:

sudo yum install httpd mod_ssl

We recommend to enable the headers module to make the X-Frame-Options of the VirtualHost configuration work. This will disallow embedding your IdP's login page within an iframe. Also enable HSTS so that browsers will always use HTTPS when connecting to the IdP.

Next, add a VirtualHost configuration for the IdP by creating a file named /etc/httpd/conf.d/idp.yourdomain.org.conf and populating it with the following contents:

<VirtualHost *:443>
ServerName idp.yourdomain.org
ServerAdmin idp-admin@yourdomain.org
CustomLog /var/log/httpd/idp.yourdomain.org.access.log combined
ErrorLog /var/log/httpd/idp.yourdomain.org.error.log

SSLEngine On
SSLCipherSuite HIGH:MEDIUM:!aNULL:!kRSA:!MD5:!RC4
SSLProtocol all -SSLv2 -SSLv3
SSLCertificateKeyFile /etc/pki/tls/private/idp.yourdomain.org.key
SSLCertificateFile /etc/pki/tls/certs/idp.yourdomain.org.crt
SSLCertificateChainFile /etc/pki/tls/certs/idp.yourdomain.org.crt

<IfModule headers_module>
Header set X-Frame-Options DENY
Header set Strict-Transport-Security "max-age=31536000 ; includeSubDomains"
</IfModule>

ProxyPass /idp ajp://localhost:8009/idp retry=5
<Proxy ajp://localhost:8009>
  Require all granted
</Proxy>
</VirtualHost>

In addition to adding the above VirtualHost definition, we suggest setting ServerTokens Prod and ServerSignature off in /etc/httpd/conf/httpd.conf to make the server not disclose/announce version number details etc. by default.

Finally, enable the Apache HTTP server and check its configuration with the following commands:

sudo systemctl enable httpd.service
sudo apachectl configtest

If the output of the last command states Syntax OK, then proceed with restarting the Apache HTTP server:

sudo systemctl restart httpd.service

4. Java Servlet installation

Please install in the order indicated below (otherwise Tomcat will pull Java 8 as dependency)

4.1. Java runtime environment: OpenJDK 8

Both Linux distributions supported in this guide provide OpenJDK 8 as their default Java runtime environment. To install, execute the following command:

sudo yum install java-1.8.0-openjdk
If you need to install Java 8 for some reason, you need to check your scripted attribute definitions and probably adapt them.

4.2. Servlet container: Apache Tomcat 7

Download and install the Apache Tomcat Servlet container:

sudo yum install tomcat

As a next step, adapt the following configuration defaults in /etc/tomcat/conf/server.xml:

  • Disable the HTTP/1.1 connector on port 8080 by commenting out the <Connector port="8080" ...>element
  • Add an AJP connector on port 8009, by adapting the <Connector port="8009" ...> line:
    <Connector port="8009" address="127.0.0.1" protocol="AJP/1.3" />
  • Disable automatic application deployment by changing autoDeploy="true" to autoDeploy="false" on the <Host name="localhost" ...> element

We recommend to allocate a large part of the memory for Tomcat and spare one 1024 MB for the OS and Apache. Configure JAVA_OPTS in /etc/tomcat/tomcat.conf as follows:

JAVA_OPTS="-server -Xmx1024m -Djava.security.egd=file:/dev/./urandom"

-Xmx1024m - this is the maximum amount of heap memory that Tomcat may use.

If your system is not short of “true” entropy (cf. cat /proc/sys/kernel/random/entropy_avail), you can leave out the -Djava.security.egd setting (for further background, see the FasterStartUp page in the Tomcat Wiki).

If you need to install Tomcat 8 for some reason, please refer to the ShibWiki.

5. Shibboleth IdP installation

Deployment of the Shibboleth IdP is a two-part procedure: first, the distribution is unpacked and its installer is run, and second, the default configuration needs to be customized for an IdP in the INFED federation. The next subsection is about the first part, while the remaining ones cover various aspects of the configuration in more detail. Generally speaking, this section is focusing on the specifics for an IdP in the INFED federation, it should not be considered a systematic description of the vast number of configuration options provided by the Shibboleth IdP version 3.

Readers interested in a comprehensive documentation of the IdP configuration settings are referred to the Configuration page in the Shibboleth Wiki, and might find the ConfigurationFileSummary page useful to get an overview of the fairly complex configuration file structure. Making oneself familiar with some SpringConfiguration basics is also helpful when trying to get a better understanding of the syntax used in the IdP configuration files.

5.1. IdP installation

Download the latest distribution archive in the tar.gz format from the Shibboleth site. We recommend creating a /usr/local/files directory for storing the downloads:

sudo mkdir /usr/local/files
cd /usr/local/files
sudo curl -O https://shibboleth.net/downloads/identity-provider/latest/shibboleth-identity-provider-3.3.2.tar.gz
sudo tar -zxf shibboleth-identity-provider-3.3.2.tar.gz
cd shibboleth-identity-provider-3.3.2/bin

By running the install.sh script you will be able to setup the IdP

./install.sh
Please enter the name of your home organization [yourdomain.org]: yourdomain.org
Please specify the service name for your IdP [idp.yourdomain.org]: idp.yourdomain.org

Proceed with the installation using the following parameters?

Service name:             idp.yourdomain.org
Home organization name:   yourdomain.org
Installation directory:   /opt/shibboleth-idp

Enter 'yes' to continue: yes

Warning: /opt/shibboleth-idp/bin does not exist.
Warning: /opt/shibboleth-idp/dist does not exist.
Warning: /opt/shibboleth-idp/doc does not exist.
Warning: /opt/shibboleth-idp/system does not exist.
Warning: /opt/shibboleth-idp/webapp does not exist.
Creating cookie encryption key files...
...done
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done

BUILD SUCCESSFUL
Total time: 4 seconds

Creating self-signed certificate...
...done
ls -ld /opt/shibboleth-idp/{credentials/{*.key,sealer.*},logs,metadata}

The output should look similar to:

-rw------- 1 tomcat root 1675 Jul 25 13:05 
-rw------- 1 tomcat root 1675 Jul 25 13:05 /opt/shibboleth-idp/credentials/idp.key
-rw-r--r-- 1 tomcat root  500 Jul 25 13:05 /opt/shibboleth-idp/credentials/sealer.jks
-rw-r--r-- 1 tomcat root   47 Jul 25 13:05 /opt/shibboleth-idp/credentials/sealer.kver
drwxr-xr-x 2 tomcat root 4096 Jul 25 13:05 /opt/shibboleth-idp/logs
drwxr-xr-x 2 tomcat root 4096 Jul 25 13:05 /opt/shibboleth-idp/metadata

5.2. General IdP settings

In /opt/shibboleth-idp/conf/metadata-providers.xml need adjustment(Without Proxy):

<MetadataProvider id="infed_sp"
                xsi:type="FileBackedHTTPMetadataProvider"
                backingFile="%{idp.home}/metadata/infed.xml"
                metadataURL="http://parichay.inflibnet.ac.in/metadata/infed.xml"/>
<MetadataProvider id="InterFederation_SP"
                xsi:type="FileBackedHTTPMetadataProvider"
                backingFile="%{idp.home}/metadata/interfederation_sp.xml"
                metadataURL="http://parichay.inflibnet.ac.in/metadata/interfederation_sp.xml"/>

If proxy is running beside your IdP server then follow the below code:

<MetadataProvider id="infed_sp"
                xsi:type="FileBackedHTTPMetadataProvider"
                backingFile="%{idp.home}/metadata/infed.xml"
                metadataURL="http://parichay.inflibnet.ac.in/metadata/infed.xml" proxyHost="%{idp.http.proxyhost:}" proxyPort="%{idp.http.proxyport:8080}" maxRefreshDelay="PT1H" />
<MetadataProvider id="InterFederation_SP"
                xsi:type="FileBackedHTTPMetadataProvider"
                backingFile="%{idp.home}/metadata/interfederation_sp.xml"
                metadataURL="http://parichay.inflibnet.ac.in/metadata/interfederation_sp.xml" proxyHost="%{idp.http.proxyhost:}" proxyPort="%{idp.http.proxyport:8080}" maxRefreshDelay="PT1H" />

5.3. Federation metadata configuration

Download the configuration file(s) with the respective <> element:

cd /opt/shibboleth-idp/metadata
sudo curl -O https://parichay.inflibnet.ac.in/metadata/infed.xml

For interfederation also download the interfederation <> element:

cd /opt/shibboleth-idp/metadata
sudo curl -O http://parichay.inflibnet.ac.in/metadata/interfederation_sp.xml

Then, download the trust anchor, the “root certificate”, which is needed for verifying the signature of INFED and Interfederation metadata metadata

cd /opt/shibboleth-idp/credentials
sudo curl -O http://parichay.inflibnet.ac.in/certs/infed.crt
sudo curl -O http://parichay.inflibnet.ac.in/certs/interfed.cert.pem

And verify that the fingerprint shown from the following OpenSSL command output matches exactly:

openssl x509 -in /opt/shibboleth-idp/credentials/infed.crt -noout -fingerprint -sha256
SHA256 Fingerprint=5D:15:47:E3:28:AA:12:C7:00:12:29:3B:89:3D:94:3A:40:F0:E8:D0:F2:62:F9:E6:D6:81:89:AA:DC:2D:CE:8F
openssl x509 -in /opt/shibboleth-idp/credentials/interfed.cert.pem -noout -fingerprint -sha256
SHA256 Fingerprint=92:B4:04:5E:2D:2A:0E:16:2A:97:FC:BE:87:43:2E:23:BA:A4:BB:17:CE:61:9D:15:63:95:CF:42:CE:EC:AA:E3

If your IdP server running behind the proxy you are requested to set the following two parameters to the /opt/shibboleth-idp/conf/idp.properties file:

idp.http.proxyhost = proxy.example.org
idp.http.proxyport = port(3128)

Then, insert in /opt/shibboleth-idp/conf/idp.properties the following line:

idp.metadata = infed, interfederation

5.4. User authentication

All the information related to LDAP connection are set in conf/ldap.properties configuration file. /opt/shibboleth-idp/conf/ldap.properties.

The following options are the most important ones: /opt/shibboleth-idp/conf/ldap.properties need to be adjusted as follows:

idp.authn.LDAP.authenticator               = bindSearchAuthenticator
idp.authn.LDAP.ldapURL                          = ldaps://ldap.yourdomain.org:636
idp.authn.LDAP.useStartTLS                      = false
idp.authn.LDAP.useSSL                           = true
idp.authn.LDAP.sslConfig                        = certificateTrust
idp.authn.LDAP.trustCertificates                = %{idp.home}/credentials/ldap-server.crt
idp.authn.LDAP.subtreeSearch                    = true
idp.authn.LDAP.baseDN                           = ou=People,dc=yourdomain,dc=org
idp.authn.LDAP.bindDN                           = uid=ldapbinduser,ou=users,dc=yourdomain,dc=org
idp.authn.LDAP.bindDNCredential                 = ldapbinduserpassword
idp.attribute.resolver.LDAP.returnAttributes    = givenName,sn,cn,o,schacHomeOrg,eduPersonPrincipalName,uid,mail

For additional LDAP authentication options supported by version 3 of the Shibboleth IdP, see the LDAPAuthnConfiguration page in the Shibboleth Wiki. The full list of available login flows is covered on the AuthenticationConfiguration page in the Shibboleth Wiki.

5.5. Attribute resolution configuration

It is the most complex, but also the most important part of the IdP configuration – the primary task of an IdP is to make statements about its users and their attributes. There isn't a one-size-fits-all approach to configuring attribute resolution on an IdP in the INFED federation, as it very much depends on what attributes are available within the organization, and what sources they are retrieved from.

Documentation can be found in the Shibboleth Wiki under AttributeResolverConfiguration and the respective subpages, in particular the description of the various AttributeDefinitionConfiguration options.

Users' attributes will be obtained from an LDAP server. As a basic for such configuration it is wise to take an take advantage of the prepared configuration file attribute-resolver-ldap.xml which contains an LDAP connector. The original file attribute-resolver.xml can be safely overwritten as it will not be needed anymore

cd /opt/shibboleth-idp/conf
cp attribute-resolver-ldap.xml attribute-resolver.xml
vi attribute-resolver.xml

Following attributes are user-specific and are to be obtained from an LDAP server. There is no need to specify “scope” for eduPersonPrincipalName since it is loaded from idp.properties configuration file. The scope is defined during Shibboleth IdP installation

5.6. Enabling support for generating persistent IDs

To enable support for generating persistent IDs through the new method recommended for version 3 of the Shibboleth IdP the following configuration changes are required:

  1. In /opt/shibboleth-idp/conf/saml-nameid.properties enable/configure the following parameters:
    • To generate StoredPersistentId through the database connection:
    idp.persistentId.generator = shibboleth.StoredPersistentIdGenerator
    idp.persistentId.sourceAttribute = infedEduPersonUniqueID
    • To generate ComputedPersistentId through the LDAP connection:
    idp.persistentId.sourceAttribute = uid
    idp.persistentId.algorithm = SHA
    idp.persistentId.salt = random string
    idp.persistentId.generator = shibboleth.ComputedPersistentIdGenerator
    idp.persistentId.computed = shibboleth.ComputedPersistentIdGenerator
    
  2. in /opt/shibboleth-idp/conf/saml-nameid.xml, remove the comments for the shibboleth.SAML2PersistentGenerator bean reference, so that it looks as follows:
       <util:list id="shibboleth.SAML2NameIDGenerators">
    
            <ref bean="shibboleth.SAML2TransientGenerator" />
    
            <ref bean="shibboleth.SAML2PersistentGenerator" />
    
            [...]
  3. in /opt/shibboleth-idp/conf/credentials.properties, add a line which specifies the salt to use for generating the persistent ID. A suitable value can be generated with openssl rand -base64 36.
    idp.persistentId.salt = ...random value...

5.7. Enabling support for eduPersonTargetedID

The eduPersonTargetedID attribute is designed to satisfy applications where the Service Provider needs to recognise the unique user .

  1. Add the foolowing code in /opt/shibboleth-idp/conf/attribute-resolver.xml:
        <resolver:AttributeDefinition xsi:type="ad:SAML2NameID" id="eduPersonTargetedID"
            nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" sourceAttributeID="computedID">
            <resolver:Dependency ref="computedID" />
            <resolver:AttributeEncoder xsi:type="enc:SAML1XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
            <resolver:AttributeEncoder xsi:type="enc:SAML2XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" friendlyName="eduPersonTargetedID" />
        </resolver:AttributeDefinition>
        <resolver:DataConnector xsi:type="dc:ComputedId"
                                id="computedID"
                                generatedAttributeID="computedID"
                                sourceAttributeID="uid"
                                salt="random value">
          <resolver:Dependency ref="myLDAP" />
        </resolver:DataConnector>
        
    
    In the above example,myLDAP refers to the DataConnector id used for the LDAP connection configuration. For the LDAP, uid is used as asourceAttributeID. For the Active Directory sAMAccountName is used as asourceAttributeID. Please refer the LDAP Connector documentation on the Shibboleth wiki for the appropriate placing of the LDAPProperty.
  2. in /opt/shibboleth-idp/conf/attribute-filter.xml:
      <AttributeRule attributeID="eduPersonTargetedID">
          <PermitValueRule xsi:type="ANY" />
    </AttributeRule >
     
    

5.8. Login form customization

In version 3 of the Shibboleth IdP, the default mechanism for rendering the login and error pages has been changed from JSP to Velocity templates, with the benefit that modifications to the login page do no longer require a restart of the Servlet container (Tomcat), but become active immediately after the editing the respective .vm file.

Download infed-template.zipand follow the below instructions.

infed-template.zip

Please keep the following .vm files in/opt/shibboleth-idp/views directory.

login.vm

error.vm

logout.vm

Please keep the following main.css files in /opt/shibboleth-idp/edit-webapp/css directory.

main.css

  • Logo configuration:
    Configure the following parameters in /opt/shibboleth-idp/system/messages/messages.properties . Insert the new parameter idp.logo.target.url since it is not included in the default configuration.
    idp.logo = /images/logo.png
    idp.logo.alt-text = Friendly name of your organization
    idp.logo.target.url = http://www.yourdomain.org
    
    please keep the following images at location/opt/shibboleth-idp/edit-webapp/images/
  • infedlogo

    esodhsindhu

    You also need to place a suitable PNG image with your organization's logo under the location referenced by idp.logo, i.e. /opt/shibboleth-idp/edit-webapp/images/logo.png, with a maximum suggested size of 200 by 100 pixel.
  • configure three target link parameters:
    Add three lines which define the target for the Forgot your password?, Change your password and Need Help? links:
    idp.login.forgotPassword.url = https://support.yourdomain.org/password-assistance
    idp.login.needHelp.url = https://support.yourdomain.org/help
    idp.login.changePassword.url = https://support.yourdomain.org/password-assistance
     
Rebeuild the Shibboleth Idp war file:
/opt/shibboleth-idp/bin/build.sh

5.9. IdP status URL configuration

The IdP status page depends on the JSP Standard Tag Library (JSTL), which is not part of the Shibboleth IdP distribution. The status page provides useful diagnostic information, and it's strongly recommended to enable this feature. To do so, download the jstl-1.2.jar file to the /opt/shibboleth-idp/edit-webapp/WEB-INF/lib directory, and rebuild the idp.war file:

cd /opt/shibboleth-idp/edit-webapp/WEB-INF/lib
sudo curl -O https://repo1.maven.org/maven2/jstl/jstl/1.2/jstl-1.2.jar
sudo JAVACMD=/usr/bin/java /opt/shibboleth-idp/bin/build.sh -Didp.target.dir=/opt/shibboleth-idp

which should result in the following output:

Warning: JAVA_HOME environment variable is not set.
If build fails because sun.* classes could not be found
you will need to set the JAVA_HOME environment variable
to the installation directory of java.
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done

BUILD SUCCESSFUL
Total time: 3 seconds

reload feature (permitting fine-grained control over the reloads of specific configuration changes), so we recommend either adding specific IP addresses only, or switching to separate accessPolicy settings, as documented in the Shibboleth Wiki under AccessControlConfiguration.

5.10. Web application enablement

Enable the IdP Web application in the Tomcat configuration by creating a file /opt/tomcat/conf/Catalina/localhost/idp.xml and populating it with the following contents:

<Context docBase="/opt/shibboleth-idp/war/idp.war"
       unpackWAR="false"
       swallowOutput="true">
<Manager pathname="" />
</Context>

Finally, (re)start Tomcat with:

service tomcat start

5.11. Testing the status page

At this point, you're able to check if the IdP Web application is at least starting properly. On the IdP, execute

curl --interface lo https://idp.yourdomain.org/idp/status

which should give output like

### Operating Environment Information
operating_system: Linux
operating_system_version: 3.10.0-123.20.1.el7.x86_64
operating_system_architecture: amd64
jdk_version: 1.7.0_75
available_cores: 1
used_memory: 494 MB
maximum_memory: 494 MB

### Identity Provider Information
idp_version: 3.2.1
start_time: 2015-12-21T07:10:32+01:00
current_time: 2015-12-22T09:18:12+01:00
uptime: 94059315 ms

[...]

If the status page is not shown as expected, then something went wrong when Tomcat was trying to load the IdP Web application. In such a case, you should examine the following log files, in this recommended order:

  • /opt/shibboleth-idp/logs/idp-warn.log: messages from the IdP of level WARN or ERROR, i.e. a (small) subset of the idp-process.log file which can be useful in getting a quick overview of potential issues.
  • /opt/shibboleth-idp/logs/idp-process.log: the log file written by the IdP itself. Depending on what startup problem you're experiencing, the files in /opt/shibboleth-idp/logs might not have been created yet, or there could be a problem with the directory or file permissions (make sure that it is writable by the tomcat user).
  • /var/log/tomcat/localhost.YYYY-MM-DD.log: messages from Tomcat's Servlet implementation
  • /var/log/tomcat/catalina.out: console output from Tomcat.

In case the problem does not become apparent from examining the log messages, the first step we recommend is having a look at the Troubleshooting Tips page in the Shibboleth Wiki, or search for the error message in the Identity Provider 3 Wiki space. Alternatively, feeding the error message to your favourite search engine and limiting the results with +site:shibboleth.net/pipermail/users (or similar) can be helpful in determining if the problem has already been brought up on the Shibboleth users mailing list.

Last but not least, it is worth mentioning that syntax errors in XML files also happen to be the source of (sometimes fairly cryptic) error messages. To make sure that your configuration files are well-formed XML documents, we recommend using the xmllint --noout somefile.xml command, which will print out syntax errors (if there are any) in a relatively human-friendly form. Use apt-get install libxml2-utils to install this utility in case it is not yet available on your system. Alternatively you can also use the command xmlwf somefile.xml to check the syntax of your XML files.

6. IdP Registration with INFED

You are requested to upload your idp-metadata.xml file along with below details which is available in /opt/shibboleth-idp/metadata directory to https://parichay.inflibnet.ac.in/rr3/providers/idp_registration

1. About Institute , 2. Administrative Contact and 3. Technical Contact.

After completion of this step, the INFED team will check the information you provided and approve your request (or contact you in case the data need to be modified).