Download

Shibboleth Service Provider (SP) Installation V3

The following instructions will help you install the Shibboleth Service Provider (SP) on your application server.

Note: Before you install anything, make sure that you have administrative permissions on your application server.

You will also need to download a text editor when you start the configuration phase. Atom or Sublime are good choices.

Linux Installations (RHEL, CentOS, & SUSE Linux Enterprise Server)

To install Shibboleth on a Linux machine, use the official RPM from the Shibboleth team here: https://shibboleth.net/downloads/service-provider/RPMS/

if you are using EL7, an example of the generated config from the link above can look like this:

[shibboleth]
name=Shibboleth (CentOS_7)
# Please report any problems to https://shibboleth.atlassian.net/jiratype=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
       https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1

1. Once you have downloaded/added the shibboleth repo. Install the Shibboleth Service Provider (SP) with yum install shibboleth This will install the latest version of the Shibboleth Service Provider (SP) software. You will receive confirmation prompts when software is installing. Type y to allow the installation of the Shibboleth Service Provider software.

2. You can confirm the installation by typing shibd -v in the terminal. You should see the version number printed out, for example shibboleth 3.0.2

3. If you see the above version or greater, you are ready to move to the configuration step.

Other Linux distributions

The only supported Linux distributions are Red Hat Enterprise, CentOS 6, 7 and SUSE Linux Enterprise Server 11-SP3, 11SP4, 12SP3, 12SP4

If you are using Ubuntu you can install the Debian package by using the following command sudo apt-get install libapache2-mod-shib2. NOTE This will install an outdated version of the Shibboleth Service Provider (SP) with version 2.6.1.

You can reference the Shibboleth Official Wiki page here https://wiki.shibboleth.net/confluence/display/SP3/LinuxInstall

Windows/IIS Installations

1. Download and install the latest version of Shibboleth from http://shibboleth.net/downloads/service-provider/latest/. During the installation, you can choose the installation directory.
2. Depending on your system choose either the win32 or win64 folder.
3. Depending on what you chose above, click the first file ending in .msi to download.
4. Once the installer has downloaded, run the installer.
5. The installer will walk you through various prompts.
6. One of those prompts will ask you to select the desired location to install the Shibboleth software. The default location is C:\opt\shibboleth-sp\
7. Select Configure IIS7 module when prompted for directory installation. The installer will add an ISAPI filter and an SSO extension.
8. Restart IIS iisreset. You can now move to configuring your Service Provider (SP).
9. For more information: https://wiki.shibboleth.net/confluence/display/SP3/Install+on+Windows

Mac OS Installations.

Please visit the Shibboleth Website for information on Installing Shibboleth for Mac OS. https://wiki.shibboleth.net/confluence/display/SP3/MacPortInstall

Download

Shibboleth Service Provider (SP) Configuration V3

Questions?

Please be sure to look through the documents page for common problems.

If you are still having trouble, please visit https://authentication.oit.duke.edu/manager/register to request help with a Shibboleth integration.

Things to think about when setting up Shibboleth

Use SSL for your web server (Apache or IIS) - You’re using authentication to protect your site. If you do not use SSL, you are risking the security of your website by making it possible for somebody to steal assertions that are created by the Identity Provider (IdP) for the Service Provider (SP) to consume. Our generated shibboleth2.xml files assume that you will be using SSL by setting handlerSSL=true in the configuration.

Anytime you make changes to the shibboleth2.xml or attribute-map.xml files, be sure to restart the shibboleth service. For Linux, use systemctl restart shibd. If you are using Windows/IIS, use sc stop shibd_default && sc start shibd_default.

It is also useful to look at the log files the Shibboleth software creates. For Linux, the directory is /var/log/shibboleth/. For Windows, look at C:\opt\shibboleth-sp\var\log\shibboleth.

Specifically, you want to pay attention to the shibd.log file.

Verify installation

To make sure that you have installed the Shibboleth Service Provider (SP) correctly, follow the next steps based on your application server operating system.

This assumes that you used the default directory during installation. If you chose a different directory, make sure that you can see the Shibboleth files inside the directory you chose.

1. Make sure the Shibboleth directory exists.

   Linux: /etc/shibboleth

   Windows/IIS: c:\opt\shibboleth-sp\etc\shibboleth

2. Make sure that the shibd process starts & that the status is active (running). In your Terminal/PowerShell run the following command:

   Linux: systemctl start shibd | systemctl status shibd

   Windows/IIS: sc start shibd_default

If you receive an error stating that the shibd service is not found, it means that the installation did not happen successfully. Otherwise, you are ready to move to the configuration step.

Configuration

Inside the Shibboleth directory, you will see a couple of files to which you will need to make changes.

Files to change:

• shibboleth2.xml
• attribute-filter.xml

On your terminal or command prompt, use the following commands to grab the Duke Metadata and the Metadata Signing certificate:

Linux

1. Move into the Shibboleth directory cd /etc/shibboleth

2. Download Duke Metadata:

   wget -O duke-metadata-3-signed.xml https://shib.oit.duke.edu/duke-metadata-3-signed.xml

3. Download Metadata signing certificate: wget -O idp_signing.crt https://shib.oit.duke.edu/idp_signing.crt

4. Verify that both files were downloaded correctly: ls.

• ls will give you a list of files in that directory. If you see the duke-metadata-3-signed.xml and idp_signing.crt files, you are ready to make changes to the shibboleth2.xml file. Otherwise, try the command again or open the files in your browser and save the files with the appropriate name and extension, duke-metadata-3-signed.xml and idp_signing.crt inside the shibboleth directory.

Windows

Using the Command Prompt or PowerShell.

1. Move into the Shibboleth directory cd c:\opt\shibboleth-sp\etc\shibboleth

2. Download Duke Metadata: curl -o duke-metadata-3-signed.xml -k https://shib.oit.duke.edu/duke-metadata-3-signed.xml

3. Download Metadata signing certificate:

   curl -o idp_signing.crt -k https://shib.oit.duke.edu/idp_signing.crt

4. Verify that both files were downloaded correctly: dir.

• dir will give you a list of files in that directory. If you see the duke-metadata-3-signed.xml and idp_signing.crt files, you are ready to make changes to the shibboleth2.xml file. Otherwise, try the command again or open the files in your browser and save the files with the appropriate name and extension, duke-metadata-3-signed.xml and idp_signing.crt inside the shibboleth directory

Shibboleth configuration

The following steps apply both to Linux and Windows installs.

Time to update the shibboleth2.xml and the attribute-map.xml configuration files. You’ll find them in /etc/shibboleth if you’re using the Shibboleth Linux distribution from Duke.

The attribute-map.xml should be ready to use if you’re using the standard attributes, eduPersonPrincipalName and eduPersonAffiliation.

Shibboleth2.xml

Define the EntityID for your service provider

Find the entityID inside <applicationDefaults /> element.

• Replace the entityID value with a unique name that identifies your site. Remember this entityID as you will use it when you register your site. Leave the cipherSuites value and add encryption=true similar to the below XML.

<applicationDefaults id="default" policyId="default"
entityID="https://your.sp.duke.edu/shibboleth"
REMOTE_USER="eppn"
encryption="true">

The eppn (eduPersonPrincipalName) is the scoped NetID attribute, e.g. netid@duke.edu. Although eppn may look and sometimes function as an email address, it is not intended as one. EPPN is a federation identifier that signifies that a user is coming from Duke and not another institution.

If you are sure you will never need to use non-Duke identities in your application and want to use the uid attribute or unscoped NetID, make sure you have requested uid and set REMOTE_USER="uid"

Set the metadata source and metadata signing certificate.

The shibd service will check for new metadata files periodically and make updates. The Shibboleth daemon will also reload the metadata file.

• Find the commented out <MetadataProvider /> element and uncomment it by removing the <!-- and --> comment tags.
• Replace the url value with: https://shib.oit.duke.edu/duke-metadata-3-signed.xml
• Set the backingFilePath value to duke-metadata-3-signed.xml , replace maxRefreshDelay with reloadInterval
• Remove the <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/> element
• Remove the DiscoveryFilter element along with the three children attribute elements.
• Last, set the certificate value to idp_signing.crt
• Your MetadataProvider element should look like this

<MetadataProvider type="XML" validate="true"
    url="https://shib.oit.duke.edu/duke-metadata-3-signed.xml"
    backingFilePath="duke-metadata-3-signed.xml" reloadInterval="7200">
    <MetadataFilter type="Signature" certificate="idp_signing.crt"/>
</MetadataProvider>

Set encryption and signing keys

Find the <CredentialResolver type="file" use="encryption"/> element and replace the values for key and certificate to sp-encrypt-key.pem and sp-encrypt-cert.pem respectively. By default, these values are already filled out. However, if you have renamed or want to rename these files, make sure that the names match. The sp-encrypt-cert.pem is the certificate that you will use during registration. NOTE: This is not your website SSL certificate.

Optional: As of Shibboleth Service Provider V3, the SP software suggests using two different keys for the signing and encryption. If you do set the signing key, make sure to ask the Identity Management team to make the change to sign assertions for this SP.

<CredentialResolver type="File" use="signing" key="sp-signing-key.pem" certificate="sp-signing-cert.pem"/>
<CredentialResolver type="File" use="encryption" key="sp-encrypt-key.pem" certificate="sp-encrypt-cert.pem"/>

Session initiator

• Update the Sessions information by setting the handlerSSL="true". This forces the handler to use SSL and makes stealing session and cookie information more difficult.
• find the <Sessions /> element, replace it with the following:

<Sessions lifetime="28800" timeout="3600" checkAddress="false"
handlerURL="/Shibboleth.sso" handlerSSL="false"
redirectLimit="host+whitelist" redirectWhitelist="https://shib.oit.duke.edu/"
exportLocation="http://localhost/Shibboleth.sso/GetAssertion" exportACL="127.0.0.1"
idpHistory="false" idpHistoryDays="7" cookieProps="https">

• If you are testing on a local environment, then leave handlerSSL="false". Otherwise leave as handlerSSL="true" for a production environment.

Define the Duke Shibboleth IdP

The last section tells your Service Provider (SP) what Identity Provider (IdP) users will authenticate against.

• find the <SSO /> element and replace the entityID value to: https://shib.oit.duke.edu/shibboleth-idp

<SSO entityID="https://shib.oit.duke.edu/shibboleth-idp">
SAML2
</SSO>

Restart Shibboleth daemon

Anytime that you make changes to the Shibboleth2.xml or any file inside the shibboleth directory, make sure to restart the shibboleth service.

Linux: systemctl restart shibd

Windows: sc stop shibd_default and sc start shibd_default.

Alternatively, you can restart the shibboleth daemon through the services app by finding the Shibboleth Daemon (Default).

Attribute-map.xml

The attribute-map.xml

The standard attributes, eduPersonPrincipalName and eduPersonScopedAffiliation should have entries in your attribute-map.xml file resembling the below XML.

When you request an attribute to be released, make sure to uncomment that attribute here.

<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.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</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.9" id="affiliation">
<AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>

Verify configuration

You are now ready to test configuration changes.

1. Restart the shibd service:

   Linux: systemctl restart shibd

   Windows: sc stop shibd_default && sc start shibd_default. Also, make sure to restart IIS. iisreset

2. Open a web browser and access your site appending /Shibboleth.sso/Status to your sites URL. for example, http://localhost/Shibboleth.sso/Status

   You should see XML text printed out to the screen. Scroll down to the bottom and look for the element <Status><OK/></Status>.

   You can also see a copy of your metadata at http://localhost/Shibboleth.sso/Metadata. This will prompt you to save or open the file. Open the file and you will see your EntityID configured in the shibboleth2.xml file along with the Assertion Consumer Service(ACS) value and the sp-encrypt-cert.pem certificate text. You will use these values when you register your Service Provider (SP) with the Duke Identity Provider (IdP).

3. Next, access your site using: http://localhost/Shibboleth.sso/Login

   If you see a page that says, "The application you have accessed is not registered with our Identity Provider (IdP).", this means that the configuration happened successfully and you are now ready to register your site.

4. If you see any other message besides the above, check the console for possible problems.

   Check problems with shibd -t

   If you need help, submit an authentication help request at https://authentication.oit.duke.edu/manager/register/. An IdM analyst will look at your request and contact you regarding more details or provide you with reasonable steps to take to fix your problem.