= Shibboleth SP on Ubuntu Linux LTS 18.04 =

Installation assumes you have already installed Ubuntu Server 18.04 with default configuration and has a public IP connectivity with DNS setup

Lets Assume your server hostname as '''sp.instXY.ac.lk'''

All commands are to be run as root and you may use `sudo su` to become root

1. Install the packages required: 
* 
{{{
apt install apache2 ntp ca-certificates vim openssl binutils
}}}   

2. Modify `/etc/hosts`:
* 
{{{
vim /etc/hosts
}}}
{{{
     127.0.0.1 sp.instXY.ac.lk sp
}}}
(Replace `sp.instXY.ac.lk` with your sp FQDN)

== Install Shibboleth Service Provider ==

3. Install dependancies to overcome issues with libcurl libraries. ( Credits: [https://depts.washington.edu/bitblog/2018/06/libcurl3-libcurl4-shibboleth-php-curl-ubuntu-18-04/ Josh L.'s Blog] )
* 
{{{
     apt install liblog4shib1v5 libxerces-c3.2 libxml-security-c17v5 libcurl3
     cp /usr/lib/x86_64-linux-gnu/libcurl.so.4.5.0 /usr/lib/x86_64-linux-gnu/libcurl3.so.4.5.0
     apt-get install libcurl4
     mkdir ~/temp
     cd ~/temp
     apt-get download libxmltooling7 # Ignore the warnings
     ar x libxmltooling7_1.6.4-1ubuntu2_amd64.deb
     tar xf control.tar.xz
     sed -i -e 's/libcurl3 (>= 7.16.2)/libcurl4/g' control
     tar -cJvf control.tar.xz control md5sums shlibs triggers
     ar rcs libxmltooling-local.deb debian-binary control.tar.xz data.tar.xz
     dpkg -i libxmltooling-local.deb
     mkdir /etc/systemd/system/shibd.service.d
}}}
* Create the following script to override defaults,
* 
{{{
vim /etc/systemd/system/shibd.service.d/override.conf
}}}
{{{
     [Service]
     Environment="LD_PRELOAD=libcurl3.so.4.5.0"
}}}
   
4. Install Shibboleth SP:
{{{
     apt install libapache2-mod-shib2 libapache2-mod-php
}}}

From this point the location of the SP directory is: `/etc/shibboleth`

== Configuration Instructions ==

=== Configure Apache2 ===

5. These configurations are based for test purposes with self generated ssl certificates. 
   If you have purchased ssl certificate from a commercial CA substitute self signed files with those. If you wish to get '''letsencrypt''' certificates on your production, //Skip //to '''Step 10'''.

Create a Certificate and a Key self-signed for HTTPS:
* 
{{{
openssl req -x509 -newkey rsa:4096 -keyout /etc/ssl/private/ssl-sp.key -out /etc/ssl/certs/ssl-sp.crt -nodes -days 1095
}}}

6. Create the file ```/etc/apache2/sites-available/sp-ssl.conf``` as follows:

{{{
   <IfModule mod_ssl.c>
      SSLStaplingCache        shmcb:/var/run/ocsp(128000)
      <VirtualHost _default_:443>
        ServerName sp.instXY.ac.lk:443
        ServerAdmin admin@instXY.ac.lk
        DocumentRoot /var/www/html
        
        SSLEngine On
        
        SSLProtocol All -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
        SSLCipherSuite "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"

        SSLHonorCipherOrder on

        # Disable SSL Compression
        SSLCompression Off
        
        # OCSP Stapling, only in httpd/apache >= 2.3.3
        SSLUseStapling          on
        SSLStaplingResponderTimeout 5
        SSLStaplingReturnResponderErrors off
        
        # Enable HTTP Strict Transport Security with a 2 year duration
        Header always set Strict-Transport-Security "max-age=63072000;includeSubDomains;preload"
        
        SSLCertificateFile /etc/ssl/certs/ssl-sp.crt
        SSLCertificateKeyFile /etc/ssl/private/ssl-sp.key
        #SSLCertificateChainFile /root/certificates/ssl-ca.pem
        
      </VirtualHost>
   </IfModule>
}}}

7. Enable '''proxy_http''', '''SSL''' and '''headers''' Apache2 modules:
* 
{{{
a2enmod proxy_http ssl headers alias include negotiation
}}}
* 
{{{
a2ensite sp-ssl.conf
}}}
* 
{{{
systemctl restart apache2
}}}

8. Configure Apache2 to open port '''80''' only for localhost:
* 
{{{
vim /etc/apache2/ports.conf
}}}
{{{
     # If you just change the port or add more ports here, you will likely also
     # have to change the VirtualHost statement in
     # /etc/apache2/sites-enabled/000-default.conf

     Listen 127.0.0.1:80
 
     <IfModule ssl_module>
       Listen 443
     </IfModule>
    
     <IfModule mod_gnutls.c>
       Listen 443
     </IfModule>
}}}
9. Configure Apache2 to redirect all on HTTPS:
* 
{{{
vim /etc/apache2/sites-enabled/000-default.conf
}}}
{{{
     <VirtualHost *:80>
        ServerName "sp.instXY.ac.lk"
        Redirect permanent "/" "https://sp.instXY.ac.lk/"
        RedirectMatch permanent ^/(.*)$ https://sp.instXY.ac.lk/$1
     </VirtualHost>
}}}

* 
{{{
systemctl restart apache2
}}}

10. '''Let'sencrypt''' setup (//Skip this step if you already configured SSL with self signed or CA provided certificates//) (Optional)

Disable the default configuration
* 
{{{
cd /etc/apache2/sites-available/
}}}
* 
{{{
a2dissite 000-default.conf
}}}
* 
{{{
systemctl reload apache2
}}}
Create a new conf file as `sp.conf`
* 
{{{
cp 000-default.conf sp.conf
}}}
Edit `sp.conf` with following
* 
{{{
vim sp.conf
}}}
{{{
<VirtualHost *:80>
 
        ServerName sp.instXY.ac.lk
        ServerAdmin YOUR-Email
        DocumentRoot /var/www/html
        
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>
}}}
Enable sp site by, 
*
{{{
a2ensite sp
}}}
and restart Apache 
* 
{{{
systemctl reload apache2
}}}   
Install Letsencypt and enable https
{{{
add-apt-repository ppa:certbot/certbot
apt install python-certbot-apache
certbot --apache -d sp.instXY.ac.lk
}}}
{{{
Plugins selected: Authenticator apache, Installer apache
Enter email address (used for urgent renewal and security notices) (Enter 'c' to
cancel): YOU@instXY.ac.lk

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server at
https://acme-v02.api.letsencrypt.org/directory
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(A)gree/(C)ancel: A

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about our work
encrypting the web, EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: Y

Obtaining a new certificate
Performing the following challenges:
http-01 challenge for sp.instXY.ac.lk
Waiting for verification...
Cleaning up challenges
Created an SSL vhost at /etc/apache2/sites-available/sp-le-ssl.conf
Enabled Apache socache_shmcb module
Enabled Apache ssl module
Deploying Certificate to VirtualHost /etc/apache2/sites-available/sp-le-ssl.conf
Enabling available site: /etc/apache2/sites-available/sp-le-ssl.conf


Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
Redirecting vhost in /etc/apache2/sites-enabled/sp.conf to ssl vhost in /etc/apache2/sites-available/sp-le-ssl.conf

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully enabled https://sp.instXY.ac.lk

}}}
=== Configure Shibboleth SP ===
11. Download Federation Metadata Signing Certificate:
* 
{{{
cd /etc/shibboleth/
}}}
* 
{{{
wget https://fr-training.ac.lk/metadata-signer -O federation-cert.pem
}}}
12. Edit `shibboleth2.xml` opportunely:
* 
{{{
vim /etc/shibboleth/shibboleth2.xml
}}}
{{{
     ...
     <ApplicationDefaults entityID="https://sp.instXY.ac.lk/shibboleth"
          REMOTE_USER="eppn persistent-id targeted-id">
     ...
     <Sessions lifetime="28800" timeout="3600" checkAddress="false" handlerSSL="true" cookieProps="https">
     ...
     <SSO discoveryProtocol="SAMLDS" discoveryURL="https://fds-training.ac.lk/shibboleth-ds/index.html">
        SAML2
     </SSO>
     ...
     <MetadataProvider type="XML" uri="https://fr-training.ac.lk/signed-metadata.xml" legacyOrgName="true" backingFilePath="LEARN-metadata.xml" reloadInterval="600">
           
           <MetadataFilter type="Signature" certificate="federation-cert.pem"/>
           
           <MetadataFilter type="RequireValidUntil" maxValidityInterval="864000" />
     </MetadataProvider>
}}}
13. Create SP metadata credentials:
* 
{{{
/usr/sbin/shib-keygen
}}}
* 
{{{
shibd -t /etc/shibboleth/shibboleth2.xml
}}}
(Check Shibboleth configuration)
14. Enable Shibboleth Apache2 configuration:
* 
{{{
a2enmod shib2
}}}
* 
{{{
service shibd restart
systemctl reload apache2.service 
}}}
15. Now you are able to download your Shibboleth SP Metadata on:
* 
{{{
https://sp.instXY.ac.lk/Shibboleth.sso/Metadata
}}}
(change `sp.instXY.ac.lk` to you SP full qualified domain name)

If you cannot see any metadata specific to your service, you may have to reload your URL several times for metadata to be created. Your correct metadata should contain your sp specific service url's and certificate.

16. Register you SP on LEARN test federation:
* Go to `https://fr-training.ac.lk/rr3/providers/sp_registration` and continue registration with pasting the content of your metadata file 

* When Applying for the membership of the federation the form will ask lot of questions to identify your service. Therefore, answer all of them as per the following,
   * On the SP registration page start with pasting the whole xml metadata from `https://sp.instXY.ac.lk/Shibboleth.sso/Metadata` and click next.
   * If you have correctly entered metadata you will be asked to select a Federation.
   * Select "Federation for Training"
   * Fill in your contact Details
   * Go to Organization tab and Fill in all details for language English(en) by clicking "Add in new language" button
   * Go to Contacts tab and add at least "Support" and "Technical" contacts
   * On UI Information tab you will see some data extracted from metadata. Apart from those fill-in the rest
   * On Certificates tab, make sure it contains Certificate details, if not start Over by reloading IDP's metadata and pasting them.
   * On Required Attribute Tab select any attribute your application needs. eg: email as a required and mobile as a desired attribute.
   * Finally click Register.


=== Configure an example federated resource "secure" ===
17. Create the Apache2 configuration for the application: 
* 
{{{
sudo su -
}}}
* 
{{{
vim /etc/apache2/sites-available/secure.conf
}}}
{{{
     RedirectMatch    ^/$  /secure

     <Location /secure>
       Authtype shibboleth
       ShibRequireSession On
       require valid-user
     </Location>
}}}
18. Create the "`secure`" application into the IDocumentRoot:
* 
{{{
mkdir /var/www/html/secure
}}}
*
{{{
vim /var/www/html/secure/index.php
}}}
{{{
     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
     <html>
       <head>
         <title></title>
         <meta name="GENERATOR" content="Quanta Plus">
         <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
       </head>
       <body>
         <p>
          <a href="https://www.instXY.ac.lk/privacy.html">Privacy Policy</a>
         </p>
         <?php
         
         foreach ($_SERVER as $key => $value){
            print $key." = ".$value."<br>";
         }
         /*foreach ($_ENV as $key => $value){
            print $key." = ".$value."<br>";
         }
         foreach ($_COOKIE as $key => $value){
            print $key." = ".$value."<br>";
         }*/
         ?>
       </body>
     </html>
}}}
19. Install needed packages:
* 
{{{
apt install libapache2-mod-php
}}}
*  Enable secure site and restart apache
{{{
a2ensite secure
}}}
{{{
service shibd restart
systemctl restart apache2.service
}}}
=== Enable Attribute Support on Shibboleth SP ===
20. Enable attributes by remove comment from the related content into `/etc/shibboleth/attribute-map.xml`

      Also you have to Disable `First deprecated/incorrect version` from `attribute-map.xml`
{{{
<!-- <Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID" id="targeted-id">
        <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
         <AttributeDecoder xsi:type="NameIDFromScopedAttributeDecoder" formatter="$NameQualifier!$SPNameQualifier!$Name" defaultQualifiers="true"/>
</Attribute> -->
}}}
=== Enable Single Logout ===
21. Change <Logout> element in /etc/shibboleth/shibboleth2.xml. They get passed as attributes to the SAML2 logoutInitiator that gets created by the Logout element.  The fully unfolded configuration with settings identical to default is:
{{{
<Logout asynchronous="true" outgoingBindings="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST urn:oasis:names:tc:SAML:2.0:bindings:SOAP">
  SAML2 Local
</Logout>
}}}
Setting asynchronous="false" would make the flow return back to the SP (this otherwise only happens for the SOAP binding which cannot be done asynchronously).


To initiate, create a button or link to go to a URL on the SP of the form: https://sp.instXY.ac.lk/Shibboleth.sso/Logout

You may use following as an example by putting it just above the closing body tag of `/var/www/html/secure/index.php` as

{{{
<p><a href="https://sp.instXY.ac.lk/Shibboleth.sso/Logout">Logout</a></p>
}}}

>The SLO would use an asynchronous message to the IdP and the flow would end at the IdP Logout page.  The user would be returned to the return URL only if the SLO is done in synchronous mode and the flow returns back to the SP.  To set the return URL, pass it in the return parameter as a query string to the Logout initiator - e.g.: https://sp.instXY.ac.lk/Shibboleth.sso/Logout?return=https://sp.instXY.ac.lk/logout-completed.html

=== Enable service provider from your IDP ===
22. To be able to login to your new SP, you must enable it from your IDP.

* Log in to your IDP and become root

*  You may want to enable any SP who is a member of the federation, edit `relying-party.xml` by

{{{
vim /opt/shibboleth-idp/conf/relying-party.xml
}}}

And uncomment the following from '''shibboleth.!UnverifiedRelyingParty''' bean

{{{
<bean parent="SAML2.SSO" p:encryptAssertions="false" />
}}}

Then restart the tomcat


23. Now you may visit https://sp.instXY.ac.lk/secure and try login using your IDP's credentials, check out the consent page at the first login. 

      Then you should see only the `Scoped Affiliation` attribute of the user as by default other attributes are not included in your attribute filter file.

      You will be asked to select one of the option accepting the consent. On acception check-out the passed attribute on your SP page


* To release specific attributes for a SP you can add it to `/opt/shibboleth-idp/conf/attribute-filter.xml` of your '''IDP'''

   Consult Service Provider guidelines and https://fr-training.ac.lk/attribute-filter-LEARN-Production.xml on deciding what attributes you should release.

   As an example lets allow EPPN, CN, mail and mobile  for your sp. 

   On your IDP,

{{{
vim /opt/shibboleth-idp/conf/attribute-filter.xml
}}}

   Add the following to the tail before the closing `</AttributeFilterPolicyGroup>` tag.
{{{
   <!-- Release some attributes to SP. -->
    <AttributeFilterPolicy id="sp.instXY">
            <PolicyRequirementRule xsi:type="Requester" value="https://sp.instXY.ac.lk/shibboleth" />

        <AttributeRule attributeID="eduPersonPrincipalName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>

        <AttributeRule attributeID="commonName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>

        <AttributeRule attributeID="mobile">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>

        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
    </AttributeFilterPolicy>

}}}

   Reload shibboleth.!AttributeFilterService to apply the new SP

{{{
/opt/shibboleth-idp/bin/reload-service.sh -id shibboleth.AttributeFilterService
}}}


   Re-visit `https://sp.instXY.ac.lk/secure` ,  at the login page select '''Clear prior granting of permission for release of your information to this service.''', this will redirect you to the consent page where you can check the attributes that are released by the filter created above.

   Once you accept the consent you can see the attributes that were used by your SP. If you can't see attributes like `mobile` in your page, you need to allow them on your attribute-map of the SP.

   To do that edit `/etc/shibboleth/attribute-map.xml` on your '''SP'''

{{{
vim /etc/shibboleth/attribute-map.xml
}}}

   Uncomment '''Examples of LDAP-based attributes''' section at the end and before the closing `</Attributes>` line,  include,

{{{
<Attribute name="urn:oid:0.9.2342.19200300.100.1.41" id="mobile"/>
<Attribute name="urn:mace:dir:attribute-def:mobile" id="mobile"/>
}}}
   
  And restart shibd and apache2 services and revisit.

  Additionally, You may check the session details from `https://sp.instXY.ac.lk/Shibboleth.sso/Session`


== Appendix: Useful logs to find problems ==

If you come up with errors, try to figure out the problem using log files in following locations.

* Shibboleth SP (shibd) log path `/var/log/shibboleth/`
* mod-shib2 log path `/var/log/shibboleth-www`
* Apache log path `/var/log/apache2`