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:
"(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:
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.
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.
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">
- Change the entityID to use the entityID you selected in the first step.
- Be sure to keep or add signing="true" if you need to use your SP entity on multiple vhosts. See Bypass Endpoint Checks in Metadata for more information.
- Leave REMOTE_USER="SHIB_EPPN" to use "email@example.com" as the preferred value for this variable. Or, set it to use "SHIB_UID" if you prefer the bare "unityid".
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">
- checkAddress - If you set this to "true", the client IP must match the IP address in SAML assertions sent by the IdP. This increases security, but can cause problems for people on proxied networks.
- consistentAddress - When set true, the client IP address must match the IP address assigned to the SP session. This is less likely to cause problems for proxied networks, since the client is always connecting to the same SP server.
- handerSSL - If your server or vhost is not running SSL, change this to "false", and change cookieProps to "http". Note: You will have to accept a warning on the client browsers every time they get a POST-redirect from the SSL IdP to your non-SSL SP handler.
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>
- Leave this unchanged for now. After testing, this can be changed to use a different IdP, or a Discovery Service.
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>
- Leave this unchanged for now. It is already setup to correctly download and verify the NCSU Federation metadata.
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"/>
Make sure these match the name of the files you generated in an earlier step.
Verify that the files are readable by the shibd user, if necessary.
Optional: Make sure to update this to the correct format if you are using separate keys for encryption and signing. For example:
<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"/>
Save and close the shibboleth2.xml file after you have made your changes.
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.
Linux (RHEL / CentOS) Installs:
export LD_LIBRARY_PATH=/opt/shibboleth/lib:/opt/shibboleth/lib64 shibd -t
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:
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:
- The top-level EntityDescriptor should contain your entityID, and not the default value from the sample configs.
- Fix: change the entityID in the first block of shibboleth2.xml.
- There should be a KeyDescriptor section with a block of X509 data containing your public certificate.
- Fix: if this is missing, it's probably one of:
- the key files were not generated
- the key files are not readable by the shibd process
- you are using separate signing and encryption keys generated by SP 3.x, but did not adjust the sample shibboleth2.xml to look for those keys
- or, the key files are not named correctly in shibboleth2.xml.
- Fix: if this is missing, it's probably one of:
- There should be six (usually) AssertionConsumerService tags with endpoint bindings. Each of these should have the correct URL for your handler service.
- Fix: If you have http/https problems, check the handlerSSL setting in shibboleth2.xml
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.
Once you have configured your Service Provider, the next step is Registration.