Shibboleth Service Provider Setup

This document is intended for system administrators that will be installing and configuring the Shibboleth Service Provider (SP) software to work with UNC Charlotte's Identity Provider (IdP). It is primarily targeted for installation in Linux environment with Apache as a web server. You will need root access to your server to perform the installation.

NOTE:  If your application is hosted on an OneIT bucket server, the SP will already be installed and ready for your application to use.

Install the Shibboleth SP Software

The Shibboleth project provides detailed instructions on installation and configuration of the native SP package for various platforms.

Configure the Shibboleth SP Software

After Shibboleth has been installed you will need to configure it to point to the UNC Charlotte test IdP (test-webauth.uncc.edu) and consider attributes needed for your application. The location of the configuration varies by OS, but typically can be found at:

  • Windows: c:\opt\shibboleth-sp\etc\shibboleth
  • RedHat or Ubuntu Linux: /etc/shibboleth  
  • Other UNIX systems: /opt/shibboleth-sp/etc/shibboleth

Web Server Configuration

During installation the SP software will install modules for your web server which enable Shibboleth to protect your application or service. Refer to the Shibboleth wiki documentation for proper configuration of your web server, this is crucial to securing your application.

NOTE:  For Apache you MUST supply the AuthType and Require commands at or above the "level" of the content you want to protect in the document tree, or the module won't run. You CANNOT rely solely on the  because of Apache's internal design.


The following Location directives are meant as an example, this can be specified in an .htaccess file or main Apache conf. Typically webapps (such as Drupal) will utilize passive authentication or "lazy" sessions to allow both authenticated and unauthenticated user access. Additional info: https://wiki.shibboleth.net/confluence/display/SP3/Apache

Example Active Authentication
 
AuthType Shibboleth
#Enable active session, use Off for passive
ShibRequireSession On
require valid-user
#Comment out entityID for IdP
#ShibRequestSetting entityID https://test-webauth.uncc.edu/idp/shibboleth
#ShibRequestSetting entityID https://webauth.uncc.edu/idp/shibboleth
 
Example Passive Authentication
  AuthType Shibboleth
  ShibRequireSession Off
  ShibUseHeaders Off
  require shibboleth
 

Certificates

An X.509 (SSL) certificate is required to sign and decrypt SAML messages between the SP and IdP. The public-private key pair generated during installation (sp-key.pem and sp-cert.pem) should be sufficient for most applications and are referred to in the shibboleth2.xml file. Use the key pair exclusively for Shibboleth and do not share with other services on the server (i.e. for Apache SSL) and make sure the key file is readable by the shibd service.

Note: Depending on the installation method you may need to generate your own self-signed public-private key pair, you can use the keygen script available in the /etc/shibboleth directory to do this. 

Create an entityID

The entityID is a unique, persistent identifier for your SP. We recommend you use a URI-style entityID https://(application).uncc.edu/shibboleth. For example:

Example entityID
https://my.uncc.edu/shibboleth 

Note: These are URI-style entityID strings not necessarily working URLs. Aways use the https prefix in the entityID, even if your server is not running https. 

Example Config Files

Below are example files configured to work with our UNCC IdP environment to use as a reference when modifying the files installed by the Shibboleth software. Most configuration changes will be made in the shibboelth2.xml file These provide a basic configuration for a single application deployment, more advanced configuration options are documented on the Shibboleth project wiki

All new SP installations will use the Shibboleth SP version 3, version 2 example files are also provided below for reference.

SP v3 Configuration Examples
wget https://spaces.uncc.edu/download/attachments/8530698/shibboleth2-v3example.xml
wget https://spaces.uncc.edu/download/attachments/8530698/attribute-map-v3example.xml
SP v2 Configuration Examples
wget https://spaces.uncc.edu/download/attachments/8530698/shibboleth2-v2example.xml
wget https://spaces.uncc.edu/download/attachments/8530698/attribute-map-v2example.xml

The Shibboleth SP configuration should automatically download, and periodically reload, the UNCC IdP metadata. The IdP metadata can also be manually downloaded at:

  • TEST: https://test-webauth.uncc.edu/idp/shibboleth
  • PROD: https://webauth.uncc.edu/idp/shibboleth
     

NOTE:  You can point your SP at the samltest.id IdP for experimental installations, or to verify setup before pointing to the UNC Charlotte IdP.

Test the Shibboleth SP Software

To test the installation and setup you will need to restart both the shibd and httpd services. 

# as root on linux:
service shibd restart
service httpd restart

 Note: You will need to restart the shibd service after making future changes to the config files. 

Generate the metadata

You should now be able to access the SP handler in a standard browser to generate the SP metadata that needs to be exchanged with the UNCC IdP. This should be attached to your your SP access request.

https://(application).uncc.edu/Shibboleth.sso/Metadata

Be sure to check your metadata for the following:

  • EntityDescriptor should contain your application entityID, not the default.
  • KeyDescriptor section containing your x509 public certificate.
  • AssertionConsumerService with binding locations relative to your service provider.

Test the Application

After your SP metadata as been included in the UNCC IdP test-webauth environment you can verify everything is working properly by testing the SP end-point handlers.

Advanced Topics and Troubleshooting

This guide is meant to be a starting pointing for Shibboleth SP maintainers. Many advanced setups are possible with the software and documented on the Native SP Configuration sections of the Shibboleth wiki. Popular options include:

 

Details

Article ID: 2468
Created
Thu 1/4/24 3:36 PM
Modified
Sat 3/9/24 12:28 AM