Installation Guide

INSTALLATION MANUAL DISCLAIMER:The information contained in this manual is subject to change by INFED Team without any prior notice.
INFED gives no warranty of any kind whatsoever, either explicitly or implicitly. It is created for the purpose of assisting the Institution
in more easily adopting the use of the INFED.  Make clear that the guidance are offered without warranty, and disclaiming liability for 
damages resulting from using the guide.
  1. System Requirement
  2. Software Requirement
  3. Shibboleth SP installation
  4. Shibboleth SP Configuration
  5. Quick Test
  6. SP Registration with INFED

Shibboleth Service Provider (SP) - Installation Guide

For the Shibboleth SP version 2.6, 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 SP with the following parameters:

  • The Publisher URL yourdomain.org
  • The SP URL sp.yourdomain.org
  • The SP entityID https://sp.yourdomain.org/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 SP 2.6, 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 SP 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

3. Web Server (HTTP) installation

Before installing the Apache HTTP Server, get an SSL certificate for the service name of the SP(sp.yourdomain.org) from a publicly trusted CA. Store the private key under /etc/pki/tls/private/sp.yourdomain.org.key and the certificate under /etc/pki/tls/certs/sp.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/sp.yourdomain.org.key /etc/pki/tls/certs/sp.yourdomain.org.pem 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.

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

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

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

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

ProxyPass /sp ajp://localhost:8009/sp 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. Shibboleth SP installation

Shibboleth Repository :

The Shibboleth project operates its own repository that provides the official Shibboleth Service Provider binaries and its dependencies for RPM-based Linux distributions. This repository contains always up-to-date version of the Shibboleth Service Provider. Therefore, it is recommended to prefer this repository and its packages over packages that may be provided by the OS distribution.

For Centos 7.x:

sudo curl -o /etc/yum.repos.d/security:shibboleth.repo  http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/security:shibboleth.repo

4.1. SP installation

Install the Service Provider by:

For 32-bit OS:

sudo yum install shibboleth

For 64-bit OS:

sudo yum install shibboleth.x86_64

If asked to confirm whether you really want to install Shibboleth and all dependencies, answer with 'Y' for yes.

After installation of the package, you need to start the shibd daemon:

sudo service shibd restart

Shibboleth does not support the SP in conjunction with SELinux. To disable SELinux, configure SELINUX=disabled in /etc/selinux/config and reboot the system.

4.2.Quick Test

The Service Provider should now be installed on the system contauns following directories:

/etc/shibboleth
Configuration directory of Shibboleth. The main configuration file is shibboleth2.xml.
/var/log/shibboleth
Log directory where logs are written to. The most important log file is the shibd.log file that should be consulted in case of problems.
/run/shibboleth
Runtime directory where process ID and socket files are stored.
/var/cache/shibboleth
Cache directory where metadata backup and CRL files are stored.
/etc/init.d
Init script directory where the startup script for the shibd daemon is stored.

4.3.Shibboleth Configuration Check

In the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:

sudo shibd -t
Important is that the last line of the output is: 
overall configuration is loadable, check console for non-fatal problems
If there are any ERROR log entries, it is strongly recommended to have a look at the problem.
Messages with log level WARN are generally not problematic but it is recommended to examine the causes of these warning messages.

4.3.1. Apache Configuration Check

Also test the Apache configuration with the command: or 
sudo apachectl configtest
The output of this command should be: 
Syntax OK

4.3.2.mod_shib Test

(Re-) Start the web server and then access the URL: https://sp.yourdomain.org/Shibboleth.sso/Session.

The web server (or Shibboleth module respectively) should return a page that says: 
A valid session was not found.
This message shows that the Shibboleth module is loaded by the webserver and is communicating with the shibd process.

5.Configure SP :

5.1.Configure SP Metadata and entityID:

Edit /etc/shibboleth/shibboleth2.xml and make the following changes:

Change the entityID in the <ApplicationDefaults> section to the URI of your SP. 
<ApplicationDefaults entityID="https://sp.yourdomain.org/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">
Inside the <ApplicationDefaults> section, add a MetadataProvider of IdP: 
<MetadataProvider type="XML" uri="http://idp.exampl.org/idp/shibboleth"   
 backingFilePath="file:///etc/shibboleth/example.xml" reloadInterval="1800" />
In MetadataGenerator handler , add the information about your service and your organization. 
<Handler type="MetadataGenerator" Location="/Metadata" signing="false">
<mdui:UIInfo>
<mdui:DisplayName xml:lang="en"> Shibboleth Provider </mdui:DisplayName>
<mdui:Description xml:lang="en">Description of Service Provider </mdui:Description>
<mdui:Logo height="300" width="500">https://sp.yourdomain.org/logo.png </mdui:Logo>
</mdui:UIInfo>           
<md:Organization>
      <md:OrganizationName xml:lang="en">Example</md:OrganizationName>
      <md:OrganizationDisplayName xml:lang="en"> Example</md:OrganizationDisplayName>
      <md:OrganizationURL xml:lang="en">http://yourdomain.org/en</md:OrganizationURL>
</md:Organization>
<md:ContactPerson contactType="support">
      <md:GivenName>XYZ</md:GivenName>
      <md:SurName>ABC </md:SurName>
      <md:EmailAddress>abc.xyz@yourdomain.org</md:EmailAddress>
</md:ContactPerson></Handler>
Additionally, make sure the md and mdui xml namespaces are defined in the <SPConfig> tag on the top of shibboleth.xml: 
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
    clockSkew="180">

5.2.Configure Apache

Check your Apache version and verify shibboleth configuration of apache virtualhost defined at /etc/shibboleth/apache.config: 
<Location /secure>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</Location>

5.3.Configure SP attributes:

Configure the required attribute in attribute-map.xml :

<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">        
   <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>    
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>    
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" id="affiliation">        
    <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>

<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="unscoped-affiliation">
    <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonAffiliation" id="unscoped-affiliation">
    <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
</Attribute>

<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" id="entitlement"/>
<Attribute name="urn:mace:dir:attribute-def:eduPersonEntitlement" id="entitlement"/>
    
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID" id="targeted-id">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>       
</Attribute>
Restart shibd service: 
service shibd restart

5.4.Configure Embeded-ds with Shibbboleth SP:

5.4.1.Install shibboleth Embeded-ds :

yum install shibboleth-embedded-ds
Edit the SSO tag in /etc/shibboleth/shibboleth2.xml(see NativeSPServiceSSO for details), removing the elementID attribute and adding a discoveryProtocol of "SAMLDS" and setting the discoveryURL attribute to the URL of the web page that will contain the EDS. 
<SSO discoveryProtocol="SAMLDS" discoveryURL="https://sp.yourdomain.org/EDS"> 
SAML2 SAML1
</SSO>
Modify the this.returnWhiteList in /etc/shibboleth-ds/idpselect_config.js and comment this.defaultReturn = null; 
  this.returnWhiteList = [ "https://sp.yourdomain.org/Shibboleth.sso/Login.*$" , "^https://sp.yourdomain.org/Shibboleth.sso/Login.*$","^https://yourdomain.org/.*$" ];

Restart Shibd :

service shibd restart
Test shibboleth Embeded-ds configuration by accessing URL https://sp.yourdomain.org/Shibboleth.sso/Login

6.Configure IDP attributes

Create shibacl.xml file in /var/www/html. 
  <AccessControl
 type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl">
 <OR>
  ........
  </OR>
</AccessControl>
In AccessControl tag mention the eduPersonScopedAffiliation and eduPersonEntitlement. For example student, staff, faculty, member, researchscholar are eduPersonScopedAffiliation and https://example.org/ is eduPersonEntitlement value of idp.example.org 
    <AND>
        <OR>
            <Rule require="affiliation">student@example.org</Rule>   
            <Rule require="affiliation">staff@example.org</Rule>   
            <Rule require="affiliation">faculty@example.org</Rule>   
            <Rule require="affiliation">member@example.org</Rule>   
            <Rule require="affiliation">researchscholar@example.org</Rule>
        </OR>
            <Rule require="entitlement">https://example.org/</Rule> 
    </AND>
Create index.php file in /var/www/html/shibp. 
<?php 
  session_start();
  $idp=$_SERVER['Shib-Identity-Provider']; 
  $uname=$_SERVER['displayName']; 
  $mail=$_SERVER['mail'];
  $affiliation=$_SERVER['affiliation'];
  $entitlement=$_SERVER['entitlement'];

  $array = array(
    'idp' => $idp,
    'uname' => $uname,
    'mail' => $mail,
    'affiliation'=>$affiliation,
    'entitlement'=>$entitlement
  );

  $json_data=json_encode($array);

  $enc =bin2hex($json_data);
  print $enc;

  header('Location: https://yourdomain.org');

?>
Modify shib.conf in /etc/httpd/conf.d/etc/apache2/sites-available. 
<Location /secure>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require shib-session
</Location>

<Location /shibp>
  AuthType shibboleth
  ShibRequestSetting requireSession true
  Require shib-plugin /var/www/html/shibacl.xml
</Location>

7.SP Registration with INFED

You are requested to upload your metadata file which is available at https://sp.yourdomain.org/Shibboleth.sso/Metadata to https://parichay.inflibnet.ac.in/rr3/providers/sp_registration along with below details.

1. About Publisher , 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).

CONTACT US

INFLIBNET Centre, Infocity, Gandhinagar, Gujarat, INDIA