Shibboleth at NC State » Technical Documentation » SP Configuration

Service Provider Configuration

Configuration of the server should be roughly platform-independent. These recipes were developed in the Linux environment, so some of the commands may need to be changed slightly for Windows installs.

This recipe assumes you are configuring a Service Provider to use the NC State production IdP, and you will be registering the SP with the NCSU Federation. It's a good place to start, as you can easily add cofiguration later for other IdPs, adding a Discovery Service, and joining other federations.

If you prefer to refer to the official documentation provided by the Shibboleth wiki, start with SP Getting Started.

Choose an entityID

The entityID is a unique, persistent identifier for your Service Provider. Please take a moment to read through the wiki entry on Entity Naming to make sure you understand how to select a good entityID.

We recommend you use a URI-style entityID. The format of the entityID should be:

https://(yourdomain).ncsu.edu/(application)/shibboleth

"(yourdomain)" should be a department or host provided by your group. It does not have to be a valid DNS name, but that is recommended.

"(application)" in most cases should be "sp" for a general Service Provider. If you are created an SP entity for a specific application, you should use that name instead.

For example, if we wanted to create a general SP for applications on the SysNews service, we would choose the entityID:

https://sysnews.ncsu.edu/sp/shibboleth

Note: These are URI-style entityID strings. They are not necessarily working URLs. You should always use the https prefix in the entityID, even if your server is not running https. The path after the domain is most likely not going to resolve to a valid web URL, and that is OK.

Generate the SP keys

See this Keys and Certs page if you need help deciding on whether to use a single key pair or two key pairs with SP 3.0.

The Service Provider needs to have its own public-private key pair that it will use to sign and decrypt SAML messages between the SP and the IdP. The private key should be used exclusively for shibboleth and not shared as a web service SSL certificate. Remember Heartbleed. The public key portion of the key-pair is signed as a certificate that is shared with the federation and IdPs. This certificate can be self-signed, and is usually issued for 10 years.

The Native Service Provider package should have included a key generating script. On Linux installs, this file is /etc/shibboleth/keygen.sh. It may have been run already, by the installer. If so, you already have a 10-year key assigned to the hostname of the server where it was generated. This is acceptable, or you can follow this example to generate a new key.

# on your server, as root
cd /etc/shibboleth
./keygen.sh -f -u shibd -g shibd -y 10 \
    -h yourdomain.ncsu.edu \
    -e https://yourdomain.ncsu.edu/sp/shibboleth
ls -l sp-*
    # you should see two new files:
    # -rw-r--r-- 1 shibd shibd 1164 May 15 12:36 sp-cert.pem
    # -rw------- 1 shibd shibd 1704 May 15 12:36 sp-key.pem

Note: The -u/-g options are required on linux installs to ensure the private key file is readable by the shibd service. Other platforms may skip those, or may not.

Ubuntu: The keygen script may not be installed in the /etc/shibboleth path, and they suggest a different username and group. The command for Ubuntu is:

shib-keygen -f -u _shibd -g _shibd -y 10 \
    -h yourdomain.ncsu.edu \
    -e https://yourdomain.ncsu.edu/sp/shibboleth

Optional: Two Keys with SP 3.0

Starting with SP v3.0, the service provider installation suggests using two separate keys for encryption and signing. A new installation of SP 3.0.2 automatically created these keys:

-rw-r--r-- 1 shibd shibd  1419 Aug  7 17:03 sp-encrypt-cert.pem
-rw------- 1 shibd shibd  2484 Aug  7 17:03 sp-encrypt-key.pem
-rw-r--r-- 1 shibd shibd  1419 Aug  7 17:03 sp-signing-cert.pem
-rw------- 1 shibd shibd  2484 Aug  7 17:03 sp-signing-key.pem

If you want to create and use separate keys, add the "-n prefix" option to the keygen.sh call, and make two new keys:

./keygen.sh -f -u shibd -g shibd -y 10 \
    -n sp-encrypt \
    -h yourdomain.ncsu.edu \
    -e https://yourdomain.ncsu.edu/sp/shibboleth
./keygen.sh -f -u shibd -g shibd -y 10 \
    -n sp-signing \
    -h yourdomain.ncsu.edu \
    -e https://yourdomain.ncsu.edu/sp/shibboleth

You will need to adjust the template file used below to include and use both keys. The section for using two keys is provided, but left commented out.

Download custom config files

We have provided a few files already configured for our NCSU Federation environment. It should be very easy to install our sample configs and then make a few modifications to match your environment. For up to date URLs, see SP Config File Links. 

# on your server, as root
cd /etc/shibboleth
wget https://docs.shib.ncsu.edu/docs/sample30-shibboleth2.xml
wget https://docs.shib.ncsu.edu/docs/sample30-attribute-map.xml
wget https://docs.shib.ncsu.edu/federation/ncsu_federation.pem
cp sample30-shibboleth2.xml shibboleth2.xml
cp sample30-attribute-map.xml attribute-map.xml

Note: When installing on IIS, use the sample30-iis-shibboleth2.xml file that contains additional IIS-specific configuration blocks at the top of the document. * https://docs.shib.ncsu.edu/docs/sample30-iis-shibboleth2.xml

The attribute-map.xml file should be usable as-is. It contains the recommended mappings of SAML attributes to envrionment variables, as described in Attributes Provided by NC State IdP.

The ncsu_federation.pem file contains the public certificate for the key that is used to sign the NCSU Federation metadata. The server needs to have this certificate to validate the federation metadata.

Configure shibboleth2.xml

The sample shibboleth2.xml file contains comments on each section where you may need to make changes. Edit the file, and search for the string "NCSU CHANGES" to locate each comment.

# on your server, as root
cd /etc/shibboleth
vi shibboleth2.xml

The first commented block defines your entityID, and your preferred attribute to use when populating the REMOTE_USER environment variable. 

<ApplicationDefaults entityID="https://yourdomain.ncsu.edu/sp/shibboleth"
    signing="true" encryption="false"
    REMOTE_USER="SHIB_EPPN eppn persistent-id targeted-id">

The second commented block assumes that your webserver is running SSL, and that it can use https URLs for the /Shibboleth.sso handler.

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
          checkAddress="false" 
          consistentAddress="true"
          handlerSSL="true" cookieProps="https"
          redirectLimit="exact+allow"
          redirectAllow="https://shib.ncsu.edu/ https://affil.shib.ncsu.edu/">

The third commented block defines the NC State production IdP as the default Identity Provider that will be used with this SP.

<SSO entityID="https://shib.ncsu.edu/idp/shibboleth">
    SAML2
</SSO>

The fourth commented block tells the SP where to download the federation metadata that it will use, how often to check for updates, and how to validate the data against the federation signing certificate.

<MetadataProvider type="XML" id="NCSU_Fed"
      url="https://docs.shib.ncsu.edu/federation/metadata.xml"
      backingFilePath="ncsu_fed_metadata.xml"
      validate="false">
    <MetadataFilter type="RequireValidUntil"
      maxValidityInterval="8640000"/>
    <MetadataFilter type="Signature"
      certificate="ncsu_federation.pem"/>
</MetadataProvider>

The fifth commented block tells the SP where to find its private key and certificate files.

<CredentialResolver type="File" 
   key="sp-key.pem" certificate="sp-cert.pem"/>

Save and close the shibboleth2.xml file after you have made your changes.

Test configuration

The shibd program can be called with a check flag to have it verify the configuration files without restarting the server. It's a good idea to do this every time you make changes, to ensure you haven't made typos in the XML files.

In either case, you will probably see a warning or two about the SSL / cookie settings. These are OK if you have a non-SSL or mixed-SSL site. If you get a lot of warnings about libcurl errors and errors fetching federation metadata, this means the shibd process could not find the libcurl-openssl library in your library path. The example LD_LIBRARY_PATH setting should work for 32- and 64-bit RHEL-based machines.

Test the handler

For the final test, you are going to restart the shibd service and try to use the handler to generate a sample metadata file for the new Service Provider.

Restart the shibd service and the httpd service.

# on linux, as root:
systemctl restart shibd
systemctl restart httpd

Now you should be able to use a standard browser to contact the handler and download the metadata. The handler URL path for the generator is /Shibboleth.sso/Metadata. Create a URL for your server something like this, using http or https as appropriate:

https://yourserver.ncsu.edu/Shibboleth.sso/Metadata

Enter that URL into your favorite browser, or use wget or curl to download the file from a command line. You should receive an XML file named Metadata. View the file and check for these tags:

If this all checks out, make a note of this working Metadata URL. You will need to provide it when you register with the NCSU Federation in the next step.

Next step

Once you have configured your Service Provider, the next step is Registration.