This document is the starting point for Application Administrators who are looking to integrate their Web-based application with the UW-Madison NetID Login Service.
The NetID Login Service SAML2 Identity Provider (which runs on Shibboleth) is UW Madison's central Authentication and Authorization service. Application administrators can integrate their web-based applications with NetID Login Service and not have to set up their own authentication and authorization.
The SAML2 component of the NetID Login Service provides web-based applications a means to authenticate users with their NetIDs, consume attributes belonging to the authenticated user, and take
advantage of single sign-on and strong authentication functionality.
This document will guide you on how to set up your web-based application to use the NetID Login Service with a Shibboleth Service Provider.
If you are a customer of DoIT Shared Hosting, please contact them for help setting up NetID Login Service for your hosted application.
The NetID Login Service works as follows:
A Web server is required for shibboleth installation as shibboleth is used for web based authentication. For this section, the IIS Web Server is required.
The IIS Management Compatibility is required if you want the Shibboleth Installer to configure IIS for you.
Steps to install IIS Management Compatibility
The IIS Website should have an appropriate x509 certificate installed and SSL enabled. Please take a look at the following document provided by Microsoft: How To Set Up an HTTPS Service in IIS
The installation guide from Shibboleth can be found here: Install on Windows
Download the Shibboleth Service Provider installer (.msi file) from the Shibboleth Software Repository
Run the installer
To verify that Shibboleth SP was installed successfully, navigate to Administrative Tools > Services
Shibboleth Service Status
ISAPI Filters
NOTE: If you don't see ISAPI Filter tab,
You should see
The Shibboleth Service Provider should now be installed on the system.
Important Directories:
A Web server is required for shibboleth installation as shibboleth is used for web based authentication. For this section, the Apache Web Server is required.
The following command should install Apache Web Server:
sudo yum install httpd
Only Apache 2.2 and 2.4 are supported.
You should have the ability to run commands as a user with root privileges.
The Apache SSL module must be enabled and configured to support HTTPS.
Servers running Shibboleth must have the system time synchronized in order to avoid clock-skew errors. It is therefore recommended to install ntp or use another time synchronization mechanism.
The installation guide from Shibboleth can be found here: Install on Linux, RPMInstall
Download the Shibboleth Service Provider from the repository
sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/security:shibboleth.repo
sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/security:shibboleth.repo
Install the repository
sudo yum install shibboleth
sudo yum install shibboleth.x86_64
Start and enable the shibd daemon
sudo systemctl start shibd.service
sudo systemctl enable shibd.service
Shibboleth Check
Execute the following command to check the status of Shibboleth in your system:
sudo shibd -t
Check if the last line of the output is "overall configuration is loadable, check console for non-fatal problems".
If there are any error log entries, please have a look at the problem. If there are any warn log entries it is not problematic but it is recommended to examine the cause of the warnings.
Apache Check
Execute the following command to check the status of Apache in your system:
sudo apachectl configtest
The output of this command should be "Syntax OK".
mod_shib Check
Restart the web server:
sudo apachectl restartThen access: https://localhost/Shibboleth.sso/Session
The web server should return a page that says: "A valid session was not found".
The Shibboleth Service Provider should now be installed on the system.
Important Directories:
A Web server is required for shibboleth installation as shibboleth is used for web based authentication. For this section, the Apache Web Server is required.
The following command should install Apache Web Server:
sudo yum install httpd
Only Apache 2.2 is supported.
You should have the ability to run commands as a user with root privileges.
The Apache SSL module must be enabled and configured to support HTTPS.
Servers running Shibboleth must have the system time synchronized in order to avoid clock-skew errors. It is therefore recommended to install ntp or use another time synchronisation mechanism.
The installation guide from Shibboleth can be found here: Install on Linux, RPMInstall
Download the Shibboleth Service Provider from the repository
sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/CentOS_CentOS-6/security:shibboleth.repo
sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/RHEL_6/security:shibboleth.repo
Install the repository
sudo yum install shibboleth
sudo yum install shibboleth.x86_64
Start and enable the shibd daemon
sudo service shibd start
Shibboleth Check
Execute the following command to check the status of Shibboleth in your system:
sudo shibd -t
Check if the last line of the output is "overall configuration is loadable, check console for non-fatal problems".
If there are any error log entries, please have a look at the problem. If there are any warn log entries it is not problematic but it is recommended to examine the cause of the warnings.
Apache Check
Execute the following command to check the status of Apache in your system:
sudo apachectl configtest
The output of this command should be "Syntax OK".
mod_shib Check
Restart the web server:
sudo apachectl restartThen access: https://localhost/Shibboleth.sso/Session
The web server should return a page that says: "A valid session was not found".
The Shibboleth Service Provider should now be installed on the system.
Important Directories:
The IIS Management Compatibility is required if you want the Shibboleth Installer to configure IIS for you.
After installing the Shibboleth SP, you will need to configure the shibboleth2.xml file correctly to work with the NetID Login Service.
Our shibboleth2.xml generator (SPGEN) should provide
you the basic configuration file needed to correctly work with the NetID Login Service. Add this file to 'C:\opt\shibboleth-sp\etc\shibboleth'.
shibboleth2.xml generator
The Metadata Signing Certificate will be used to verify that the files that you load from the NetID Login Service have not been tampered with.
Save this file in the Shibboleth installation directory C:\opt\shibboleth-sp\etc\shibboleth
After installing the Shibboleth SP, you will need to configure the shibboleth2.xml file correctly to work with the NetID Login Service.
Our shibboleth2.xml generator (or SPGEN) should
provide you the basic configuration file needed to correctly work with the NetID Login Service. Add this file to '/etc/shibboleth'.
shibboleth2.xml generator:
The Metadata Signing Certificate will be used to verify that the files that you load from the NetID Login Service have not been tampered with.
Save this file in the Shibboleth installation directory /etc/shibboleth
Example:
sudo curl https://login.wisc.edu/metadata/login.wisc.edu-signing.pem -O /etc/shibboleth/login.wisc.edu-signing.pem
The apache configuration guide from Shibboleth can be found here: Apache Configuration Guide
To ensure proper routing of URL paths that Shibboleth handlers rely on, set a location directive within apache's configuration file specifying routing to mod_shib.
<Location /Shibboleth.sso> SetHandler shib </Location>
Ensure that your virtual host is configured correctly by setting the
ServerName
command to the appropriate value. If this is not set correctly the redirects generated by the shib module will be incorrect.
Example:
ServerName testapp.wisc.edu
Set
UseCanonicalName On
by editing the httpd.conf file
Add the following to either the virtual host configuration or the shibd.conf file to enable the shibboleth module and require authentication for a specific directory or application
<Location /> AuthType shibboleth ShibRequestSetting applicationId https://www.yoursite.wisc.edu/shibboleth ShibRequestSetting requireSession 1 require shib-session </Location>
The
AuthType
and
Require
commands must be included for Shibboleth to run.
The value
'https://www.yoursite.wisc.edu/shibboleth'
in the command
ShibRequestSetting applicationId
must match the value of the
id
attribute in the
ApplicationDefault
or the
ApplicationOverride
section of the shibboleth2.xml file.
Example snippet from shibboleth2.xml file:
<ApplicationOverride id="https://www.yoursite.wisc.edu/shibboleth" entityID="https://www.yoursite.wisc.edu/shibboleth" REMOTE_USER="uid"> <Sessions handlerURL="/Shibboleth.sso" cookieProps="; path=/internal; secure; HttpOnly"> <SSO entityID="https://login.wisc.edu/idp/shibboleth"> SAML2 SAML1 </SSO> </Sessions> </ApplicationOverride>
This setting associates the application with the server resource.
The last step is to restart apache after the configuration.
sudo apachectl restart
Execute:
md5sum /etc/shibboleth/login.wisc.edu-signing.pem
You should see:
478044ae7b137c1182ce7cdb9511f329 /etc/shibboleth/login.wisc.edu-signing.pem
If you do not see this please contact help@login.wisc.edu.
sudo systemctl restart shibd.service
sudo systemctl restart httpd.service
Examine the logs to verify that federation metadata was successfully downloaded:
sudo grep login.wisc.edu-metadata.xml /var/log/shibboleth/shibd.log
You should see:
INFO OpenSAML.MetadataProvider.XML : loaded XML resource (/var/cache/shibboleth/login.wisc.edu-metadata.xml)
Navigate to:
https://www.yoursite.wisc.edu/Shibboleth.sso/Metadata
Verify that there is XML metadata content at this path.
After installing the Shibboleth SP, you will need to configure the shibboleth2.xml file correctly to work with the NetID Login Service.
Our shibboleth2.xml generator (or SPGEN) should
provide you the basic configuration file needed to correctly work with the NetID Login Service. Add this file to '/etc/shibboleth'.
shibboleth2.xml generator:
The Metadata Signing Certificate will be used to verify that the files that you load from the NetID Login Service have not been tampered with.
Save this file in the Shibboleth installation directory /etc/shibboleth
Example:
sudo curl https://login.wisc.edu/metadata/login.wisc.edu-signing.pem -O /etc/shibboleth/login.wisc.edu-signing.pem
The apache configuration guide from Shibboleth can be found here: Apache Configuration Guide
To ensure proper routing of URL paths that Shibboleth handlers rely on, set a location directive within apache's configuration file specifying routing to mod_shib.
<Location /Shibboleth.sso> SetHandler shib </Location>
Ensure that your virtual host is configured correctly by setting the
ServerName
command to the appropriate value. If this is not set correctly the redirects generated by the shib module will be incorrect.
Example:
ServerName testapp.wisc.edu
Set
UseCanonicalName On
by editing the httpd.conf file
Add the following to either the virtual host configuration or the shibd.conf file to enable the shibboleth module and require authentication for a specific directory or application
<Location /> AuthType shibboleth ShibRequestSetting applicationId https://www.yoursite.wisc.edu/shibboleth ShibRequestSetting requireSession 1 require shib-session </Location>
The
AuthType
and
Require
commands must be included for Shibboleth to run.
The value
'https://www.yoursite.wisc.edu/shibboleth'
in the command
ShibRequestSetting applicationId
must match the value of the
id
attribute in the
ApplicationDefault
or the
ApplicationOverride
section of the shibboleth2.xml file.
Example snippet from shibboleth2.xml file:
<ApplicationOverride id="https://www.yoursite.wisc.edu/shibboleth" entityID="https://www.yoursite.wisc.edu/shibboleth" REMOTE_USER="uid"> <Sessions handlerURL="/Shibboleth.sso" cookieProps="; path=/internal; secure; HttpOnly"> <SSO entityID="https://login.wisc.edu/idp/shibboleth"> SAML2 SAML1 </SSO> </Sessions> </ApplicationOverride>
This setting associates the application with the server resource.
The last step is to restart apache after the configuration.
sudo apachectl restart
Execute:
md5sum /etc/shibboleth/login.wisc.edu-signing.pem
You should see:
478044ae7b137c1182ce7cdb9511f329 /etc/shibboleth/login.wisc.edu-signing.pem
If you do not see this please contact help@login.wisc.edu.
sudo service shibd restart
sudo service httpd restart
Examine the logs to verify that federation metadata was successfully downloaded:
sudo grep login.wisc.edu-metadata.xml /var/log/shibboleth/shibd.log
You should see:
INFO OpenSAML.MetadataProvider.XML : loaded XML resource (/var/cache/shibboleth/login.wisc.edu-metadata.xml)
Navigate to:
https://www.yoursite.wisc.edu/Shibboleth.sso/Metadata
Verify that there is XML metadata content at this path.
Once you have your SP application installed, configured, and integrated correctly you need to activate it with the NetID Login Service.
The process involves either sending the Metadata file or a link to your Metadata location for your application to NetID Login Service email (help@login.wisc.edu) with your preferred contact for the SP.
The Metadata for your application is located at https://localhost/Shibboleth.sso/Metadata or https://domain.wisc.edu/Shibboleth.sso/Metadata
NOTE: If you want us to retrieve your Metadata under https://domain.wisc.edu/Shibboleth.sso/Metadata, please make sure the firewall rules allow it.
Once your SP has been registered with the NetID Login Service, your application will receive a set of default attributes described below for every user that logs in (see NetID Login Service and Wisconsin Federation Attribute Information):
If your application requires data about users other than the default set, you will need to submit an IDI request.
For more information about data elements that are approved for authorized applications see: APPROVED ATTRIBUTES FOR RELEASE TO APPLICATIONS
Your application can be restricted to a specific group of people defined by a Manifest group that you control.
New to Manifest? Please take a look at our Manifest Getting Started Document
Instructions for integrating a Manifest group with your Service Provider is described in the following document: MANIFEST - INTEGRATING WITH NETID LOGIN SERVICE
NetID Login IDP EntityID: https://login.wisc.edu/idp/shibboleth
NetID Login IDP Metadata: https://login.wisc.edu/idp/shibboleth
NetID Login IDP Attribute Map: https://login.wisc.edu/metadata/attribute-map.xml
Technical Contact: help@login.wisc.edu