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
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: