- Requirements
- Software that will be installed
- Notes
- Installation Instructions
- Configuration Instructions
- Test
- Appendix A - SE Linux
- Appendix B - Enable Attribute Checker Support on Shibboleth SP
- Appendix C - Connect SP directly to an IdP
- Authors
- CPU: 2 Core
- RAM: 4 GB
- HDD: 20 GB
- SSL Credentials: HTTPS Certificate & Key & Certification Authority (CA)
- Logo:
- size: 80x60 px (or other that respect the aspect-ratio)
- format: PNG
- ca-certificates
- ntp
- vim
- httpd.x86_64 (Apache >= 2.4)
- php
- openssl
- shibboleth.x86_64
This HOWTO use example.org
as domain name and sp.example.org
as FQDN (Full Qualified Domain Name) to provide example values to this guide.
Please, remember to replace all occurence of example.org
domain name, or part of it, with the SP domain name into the configuration files and also sp.example.org
with the FQDN of your SP server.
-
Become ROOT:
sudo su -
-
Install the packages required:
yum install ca-certificates vim openssl
-
Become ROOT:
sudo su -
-
Create the Shibboleth Repository:
-
yum install httpd.x86_64
-
mv /etc/httpd/conf.d/welcome.conf /etc/httpd/conf.d/welcome.conf.deactivated
-
-
Prevent Apache from listing web directory files to visitors:
sed -i "s/Options Indexes FollowSymLinks/Options FollowSymLinks/" /etc/httpd/conf/httpd.conf
-
Start the Apache service and enable it to auto-start on boot:
systemctl start httpd.service
systemctl enable httpd.service
-
Become ROOT:
sudo su -
-
Create the Shibboleth Repository:
-
vim /etc/yum.repos.d/shibboleth.repo
[shibboleth] name=Shibboleth (CentOS_7) # Please report any problems to https://issues.shibboleth.net type=rpm-md mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7 gpgcheck=1 gpgkey=https://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/repodata/repomd.xml.key enabled=1
-
Save changes by clicking on the
Esc
button and by digiting:wq
-
-
Update the repositories with:
yum update -y
-
Discover what architecture do you have with:
echo "I am running: $(cat /etc/redhat-release) ($(arch))"
-
Install Shibboleth Service Provider:
yum install shibboleth.x86_64 -y
From this point the location of the SP directory will be:
/etc/shibboleth
-
Become ROOT:
sudo su -
-
Modify your
/etc/hosts
:-
vim /etc/hosts
VV.ZZ.XX.YY sp.example.org sp
(Replace
VV.ZZ.XX.YY
with your SP's public IP)(Replace
sp.example.org
with your SP Full Qualified Domain Name)(Replace
sp
with your SP Hostname)
-
-
Be sure that your firewall doesn't block the traffic on port 443 (or you can't access to your SP)
According to NSA and NIST, RSA with 3072 bit-modulus is the minimum to protect up to TOP SECRET over than 2030.
-
Become ROOT:
sudo su -
-
Load SSL credentials in the right place:
-
HTTPS Server Certificate (Public Key) inside
/etc/pki/tls/certs/$(hostname -f).crt
-
HTTPS Server Key (Private Key) inside
/etc/pki/tls/private/$(hostname -f).key
-
Add CA Cert into
/etc/pki/tls/certs
-
If you use GARR TCS (Sectigo CA):
wget -O /etc/pki/tls/certs/GEANT_OV_RSA_CA_4.pem https://crt.sh/?d=2475254782 wget -O /etc/pki/tls/certs/SectigoRSAOrganizationValidationSecureServerCA.crt https://crt.sh/?d=924467857 cat /etc/pki/tls/certs/SectigoRSAOrganizationValidationSecureServerCA.crt >> /etc/pki/tls/certs/GEANT_OV_RSA_CA_4.pem rm /etc/pki/tls/certs/SectigoRSAOrganizationValidationSecureServerCA.crt
-
If you use ACME (Let's Encrypt):
ln -s /etc/letsencrypt/live/<SERVER_FQDN>/chain.pem /etc/pki/tls/certs/ACME-CA.pem
(OPTIONAL) Create a Certificate and a Key self-signed for HTTPS if you don't have yet the official ones provided by the Certificate Authority:
-
openssl req -x509 -newkey rsa:3072 -keyout /etc/pki/tls/private/$(hostname -f).key -out /etc/pki/tls/certs/$(hostname -f).crt -nodes -days 1095
-
-
-
Install "mod_ssl" to enable HTTPS configuration:
yum install mod_ssl -y
-
Create the DocumentRoot:
mkdir /var/www/html/$(hostname -f)
sudo chown -R apache: /var/www/html/$(hostname -f)
echo '<h1>It Works!</h1>' > /var/www/html/$(hostname -f)/index.html
-
Create the Virtualhost file (pay attention and follow the starting comment):
-
wget https://registry.idem.garr.it/idem-conf/shibboleth/SP3/apache2/sp.example.org.conf -O /etc/httpd/conf.d/000-$(hostname -f).conf
-
-
Reload Apache2 web server:
systemctl restart httpd.service
-
Configure Apache2 to open port 80 only for localhost:
-
vim /etc/httpd/conf/httpd.conf
... # Listen 12.34.56.78:80 Listen 127.0.0.1:80
-
-
Restart Apache to apply changes
systemctl restart httpd.service
-
Verify the strength of your server on:
-
Become ROOT:
sudo su -
-
Change the SP entityID and technical contact email address:
sed -i "s/sp.example.org/$(hostname -f)/" /etc/shibboleth/shibboleth2.xml
sed -i "s/root@localhost/<TECH-CONTACT-EMAIL-ADDRESS-HERE>/" /etc/shibboleth/shibboleth2.xml
-
Create SP metadata Signing and Encryption credentials:
cd /etc/shibboleth
./keygen.sh -u shibd -g shibd -h $(hostname -f) -y 30 -e https://$(hostname -f)/shibboleth -n sp-signing -f
./keygen.sh -u shibd -g shibd -h $(hostname -f) -y 30 -e https://$(hostname -f)/shibboleth -n sp-encrypt -f
LD_LIBRARY_PATH=/opt/shibboleth/lib64 /usr/sbin/shibd -t
systemctl restart shibd.service
systemctl restart httpd.service
-
Now you are able to reach your Shibboleth SP Metadata on:
https://sp.example.org/Shibboleth.sso/Metadata
(Replace
sp.example.org
with your SP Full Qualified Domain Name)
-
Check that the Apache configuration has the "secure" Location configured:
-
vim /etc/httpd/conf.d/shib.conf
... <Location /secure> AuthType shibboleth ShibRequestSetting requireSession 1 require shib-session </Location>
-
-
Create the "
secure
" application into the DocumentRoot:-
mkdir /var/www/html/$(hostname -f)/secure
-
wget https://registry.idem.garr.it/idem-conf/shibboleth/SP3/secure/index.php.txt -O /var/www/html/$(hostname -f)/secure/index.php
-
-
Install PHP 7.x:
-
Enable Remi and EPEL yum repositories on your system:
yum install epel-release
rpm -Uvh http://rpms.famillecollet.com/enterprise/remi-release-7.rpm
-
Install PHP 7.x:
- 7.1:
yum --enablerepo=remi-php71 install php
- 7.2:
yum --enablerepo=remi-php72 install php
- 7.1:
-
Verify:
php -v
-
-
Restart
httpd
daemon to enable PHP:systemctl restart httpd.service
The Attribute Map file is used by the Service Provider to recognize and support new attributes released by an Identity Provider
Enable attribute support by removing comment from the related content into /etc/shibboleth/attribute-map.xml
.
Follow these steps IF AND ONLY IF your organization will join as a Partner or a Member into IDEM Federation
-
Retrieve the IDEM GARR Federation Certificate needed to verify the signed metadata:
cd /etc/shibboleth/
curl https://md.idem.garr.it/certs/idem-signer-20220121.pem -o federation-cert.pem
- Check the validity:
-
cd /etc/shibboleth
-
openssl x509 -in federation-cert.pem -fingerprint -sha1 -noout
(sha1: D1:68:6C:32:A4:E3:D4:FE:47:17:58:E7:15:FC:77:A8:44:D8:40:4D)
-
openssl x509 -in federation-cert.pem -fingerprint -md5 -noout
(md5: 48:3B:EE:27:0C:88:5D:A3:E7:0B:7C:74:9D:24:24:E0)
-
-
Edit
shibboleth2.xml
opportunely:-
vim /etc/shibboleth/shibboleth2.xml
<!-- If it is needed to manage the authentication on several IdPs install and configure the Shibboleth Embedded Discovery Service by following this HOWTO: https://url.garrlab.it/nakt7s --> <SSO discoveryProtocol="SAMLDS" discoveryURL="https://wayf.idem-test.garr.it/WAYF"> SAML2 </SSO> <MetadataProvider type="XML" url="http://md.idem.garr.it/metadata/idem-test-metadata-sha256.xml" backingFilePath="idem-test-metadata-sha256.xml" maxRefreshDelay="7200"> <MetadataFilter type="Signature" certificate="federation-cert.pem"/> <MetadataFilter type="RequireValidUntil" maxValidityInterval="864000" /> </MetadataProvider>
-
-
Register you SP on IDEM Entity Registry: (your entity has to be approved by an IDEM Federation Operator before become part of IDEM Test Federation):
- Go to
https://registry.idem.garr.it
and follow "Insert a New Service Provider into the IDEM Test Federation"
- Go to
Open the https://sp.example.org/secure
application into your web browser
(Replace sp.example.org
with your SP Full Qualified Domain Name)
If you'll met problem, probably they are related to SE Linux.
If you want to disable it until the next server reboot, doing this:
sudo setenforce 0
If you want to disable it forever do this:
sed -i 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config ; setenforce permissive
The SE Linux is disabled if you will find Current mode: permissive
from the command sestatus
.
-
Add a sessionHook for attribute checker:
sessionHook="/Shibboleth.sso/AttrChecker"
and themetadataAttributePrefix="Meta-"
toApplicationDefaults
:-
vim /etc/shibboleth/shibboleth2.xml
<ApplicationDefaults entityID="https://sp.example.org/shibboleth" REMOTE_USER="eppn subject-id pairwise-id persistent-id" cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1" sessionHook="/Shibboleth.sso/AttrChecker" metadataAttributePrefix="Meta-">
(Replace
sp.example.org
with your SP Full Qualified Domain Name)
-
-
Add the attribute checker handler with the list of required attributes to Sessions (in the example below:
displayName
,givenName
,mail
,cn
,sn
,eppn
,schacHomeOrganization
,schacHomeOrganizationType
). The attributes' names HAVE TO MATCH with those are defined onattribute-map.xml
:-
vim /etc/shibboleth/shibboleth2.xml
<!-- Attribute Checker --> <Handler type="AttributeChecker" Location="/AttrChecker" template="attrChecker.html" attributes="displayName givenName mail cn sn eppn schacHomeOrganization schacHomeOrganizationType" flushSession="true"/>
If you want to describe more complex scenarios with required attributes, operators such as "AND" and "OR" are available.
<Handler type="AttributeChecker" Location="/AttrChecker" template="attrChecker.html" flushSession="true"> <OR> <Rule require="displayName"/> <AND> <Rule require="givenName"/> <Rule require="surname"/> </AND> </OR> </Handler>
-
-
Add the following
<AttributeExtractor>
element under<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
-
vim /etc/shibboleth/shibboleth2.xml
<!-- Extracts support information for IdP from its metadata. --> <AttributeExtractor type="Metadata" errorURL="errorURL" DisplayName="displayName" InformationURL="informationURL" PrivacyStatementURL="privacyStatementURL" OrganizationURL="organizationURL"> <ContactPerson id="Technical-Contact" contactType="technical" formatter="$EmailAddress" /> <Logo id="Small-Logo" height="16" width="16" formatter="$_string"/> </AttributeExtractor>
-
-
Save and restart "shibd" service:
systemctl restart shibd.service
-
Customize Attribute Checker template:
cd /etc/shibboleth
cp attrChecker.html attrChecker.html.orig
curl https://raw.githubusercontent.com/CSCfi/shibboleth-attrchecker/master/attrChecker.html -o attrChecker.html
sed -i 's/SHIB_//g' /etc/shibboleth/attrChecker.html
sed -i 's/eduPersonPrincipalName/eppn/g' /etc/shibboleth/attrChecker.html
sed -i 's/Meta-Support-Contact/Meta-Technical-Contact/g' /etc/shibboleth/attrChecker.html
sed -i 's/supportContact/technicalContact/g' /etc/shibboleth/attrChecker.html
sed -i 's/support/technical/g' /etc/shibboleth/attrChecker.html
There are three locations needing modifications to do on
attrChecker.html
:-
The pixel tracking link after the comment "PixelTracking". The Image tag and all required attributes after the variable must be configured here. After "
miss=
" define all required attributes you updated inshibboleth2.xml
using shibboleth tagging.Eg
<shibmlpifnot $attribute>-$attribute</shibmlpifnot>
(this echoes $attribute if it's not received by shibboleth). The attributes' names HAVE TO MATCH with those are defined onattribute-map.xml
.This example uses "
-
" as a delimiter. -
The table showing missing attributes between the tags "
<!--TableStart-->
" and "<!--TableEnd-->
". You have to insert again all the same attributes as above.Define row for each required attribute (eg:
displayName
below)<tr <shibmlpifnot displayName> class='warning text-danger'</shibmlpifnot>> <td>displayName</td> <td><shibmlp displayName /></td> </tr>
-
The email template between the tags "<textarea>" and "</textarea>". After "The attributes that were not released to the service are:".
Again define all required attributes using shibboleth tagging like in section 1 ( eg:
<shibmlpifnot $attribute> * $attribute</shibmlpifnot>
). The attributes' names HAVE TO MATCH with those are defined onattribute-map.xml
. Note that for SP identifier target URL is used instead of entityID. There arent yet any tag for SP entityID so you can replace this target URL manually.
-
Enable Logging:
-
Create your
track.png
with into your DocumentRoot:echo "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==" | base64 -d > /var/www/html/track.png
-
Example result into
/var/log/httpd/access.log
:./httpd/access.log:193.206.129.66 - - [20/Sep/2018:15:05:07 +0000] "GET /track.png?idp=https://garr-idp-test.irccs.garr.it/idp/shibboleth&miss=-SHIB_givenName-SHIB_cn-SHIB_sn-SHIB_eppn-SHIB_schacHomeOrganization-SHIB_schacHomeOrganizationType HTTP/1.1" 404 637 "https://sp.example.org/Shibboleth.sso/AttrChecker?return=https%3A%2F%2Fsp.example.org%2FShibboleth.sso%2FSAML2%2FPOST%3Fhook%3D1%26target%3Dss%253Amem%253A43af2031f33c3f4b1d61019471537e5bc3fde8431992247b3b6fd93a14e9802d&target=https%3A%2F%2Fsp.example.org%2Fsecure%2F"
-
Thanks eduGAIN for the original "HOWTO" posted here.
Follow these steps IF you need to connect one SP with only one IdP. It is useful for test purposes.
-
Edit
shibboleth2.xml
opportunely:-
vim /etc/shibboleth/shibboleth2.xml
<!-- If it is needed to manage the authentication on several IdPs install and configure the Shibboleth Embedded Discovery Service by following this HOWTO: https://url.garrlab.it/nakt7 --> <SSO entityID="https://idp.example.org/idp/shibboleth"> SAML2 </SSO> <!-- ... other things ... --> <MetadataProvider type="XML" validate="true" url="https://idp.example.org/idp/shibboleth" backingFilePath="idp-metadata.xml" maxRefreshDelay="7200" />
(Replace
entityID
with the IdP entityID andurl
with an URL where it can be downloaded its metadata)(
idp-metadata.xml
will be saved into/var/cache/shibboleth
)
-
-
Restart
shibd
andhttpd
daemon:sudo systemctl restart shibd
sudo systemctl restart httpd
-
Jump to Test
- Marco Malavolti ([email protected])
- Barbara Monticini ([email protected])