Authentication

Authenticating Your Duke Site

Resources for getting your site or service protected by Shibboleth

In accordance with Duke security offices service authentication statement , OIT supports electronic authorization to resources via Shibboleth, an open-source authorization provider created by Internet2, a community of academic, research, industrial, and governmental institutions.

Locally-Developed Sites/Services

Guidelines for protecting sites or services developed at or specifically for Duke.

Before you get started with installing/configuring Shibboleth, you need to able to modify files on your server. If this is not the case, consult with an administrator so that you can make changes.

Familiarize yourself with the vocabulary

The steps below outline the process of getting your site protected with shibboleth.

  1. Install the Shibboleth Service Provider (SP) software
  2. Configuration to protect your site
  3. Register your site with the Duke Identity Provider (IdP)
  4. Test authentication and authorization
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, eduPersonPrinciplaName 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.

It is now time to collect information from the Service Provider (SP) you just configured.

The below items are to be found under the Shibboleth directory on your application server

Windows default directory is: c:\opt\shibboleth-sp\etc\shibboleth

Linux default directory: /etc/shibboleth

  • EntityID: The EntityID in the shibboleth2.xml file.
  • Certificate: Find the sp-cert.pem file inside the shibboleth directory. When registering your Service Provider (SP), make sure you paste the text inside BEGIN CERTIFICATE - END CERTIFICATE into the certificate field.
  • Assertion Consumer Service URL (ACS): The assertion consumer url is usually the fully qualified domain name plus Shibboleth.sso/SAML2/POST for example: https://mysite.duke.edu/Shibboleth.sso/SAML2/POST
    Download the SAML tracer plugin if you are unsure what the Assertion Consumer Service URL is.
  • The default directory protected by Shibboleth is the /secure path on your server.
  • Using a web browser that is not already logged into Shibboleth, attempt to navigate to a part of your site that should be protected by Shibboleth. If everything was configured correctly, you should see a redirect to a login page that begins with https://shib.oit.duke.edu
  • You can now make configuration changes to protect a certain path within your server. Take a look at our attributes and authorization document to make such changes.
  • If you encountered an error, take a look at our common errors page.
  • Take a look at the Shibboleth Documentation for further reference.

Vendor Sites/Services

Guidelines for protecting sites or services offered by vendors.

  • Make sure the vendor completes the Vendor risk assessment. This is important since this will inform us what the vendor supports and if it meets the requirements for integrating with Duke.
  • Visit the Duke Security website if you have questions with regard to choosing a vendor.
  • It is advisable that you familiarize yourself with the vocabulary. This will help connect the dots if problems arise at any time during the integration.
  • Check the following list to see if your vendor is part of InCommon: InCommon participants
  • If your vendor is an InCommon participant, please submit a Shibboleth integration support request with the vendor's EntityID and any attributes the vendor needs to be provided about users upon login.
  • If the above does not apply to your vendor, move on to the Getting Started section.

Provide your vendor contact with the following:

  • The Duke metadata is important since it contains information that identify the Identity Provider (Duke). Your Service Provider (vendor) will use this information to redirect users to the Duke Shibboleth NetID login page.
    The certificate in the Duke metadata is used to sign the responses and assertions produced by the Identity Provider (IdP).
  • Give your vendor the Metadata Signing Certificate. This certificate is used to sign the Identity Provider's (IdP) Metadata.
  • Occasionally, vendors require a SHA256 signing certificate.This can be obtained with a ServiceNow ticket to Identity Management-OIT

It is time to collect information that will be used in the Register Service Provider (SP) section below.

For reference, take a look at our vocabulary document.

Request a copy of the vendors metadata. This can be uploaded as a file in the registration interface.

If the vendor cannot provide this file, you will need them to provide the following elements so you can register the Service Provider (SP) manually:

  1. EntityID
  2. Certificate used for encryption
  3. Assertion Consumer Service URL (ACS)
  4. Attributes the Service Provider (SP) will need
  • Duke sponsor - create a guest account for the vendor. The guest account can also serve as an account for testing authentication. Note: You will need to request NetID credentials.
  • Register your Service Provider (SP)
  • If you have more than one environment (test, production), you can have multiple registrations.
  • Using a web browser (private/incognito window) that is not already logged into Shibboleth, attempt to navigate to a part of your site that should be protected by Shibboleth.
  • You should be prompted with the Duke Shibboleth NetID login page. If you see an error stating that the Identity Provider (IdP) does not recognize your Service Provider (SP), make sure you registered the correct EntityID during registration.
  • If you authenticated successfully with your NetID and password but received an error afterwards, contact your vendor for help with the issue. You can submit a help request if the vendor requires custom changes for their Service Provider (SP).