NetID Login Service - Getting Started

Requirements

1. Microsoft IIS Web Server

   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.

2. IIS Management Compatibility

   The IIS Management Compatibility is required if you want the Shibboleth Installer to configure IIS for you.

   Steps to install IIS Management Compatibility

   1. Click Start and click Control Panel
   2. Click Programs
   3. Click Programs and Features
   4. Click Turn Windows Features on or off
   5. Expand the Internet Information Services item
   6. Expand the Web Management Tools item
   7. Select the IIS 6 Management Compatibility item
   8. Click OK
3. SSL Enabled for Microsoft IIS

   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

Installation

The installation guide from Shibboleth can be found here: Install on Windows

1. Download the Shibboleth Service Provider installer (.msi file) from the Shibboleth Software Repository

   • 32 bit - http://shibboleth.net/downloads/service-provider/latest/win32/
   • 64 bit - http://shibboleth.net/downloads/service-provider/latest/win64/

2. Run the installer

   1. Confirm the dialog to run the software
   2. Click "Next"
   3. Accept the license agreement
   4. Configure the location for the installation (C:\opt\shibboleth-sp\ by default)
   5. Select Configure IIS7 module
   6. click "Next", click "Install", click "Finish"
   7. Click "Yes" to restart the system

Verification

To verify that Shibboleth SP was installed successfully, navigate to Administrative Tools > Services

1. Shibboleth Service Status

   1. Find the Shibboleth Service
   2. Verify that the status is the following: 'status:running', 'startup type:automatic', 'logon as:local system'

2. ISAPI Filters

   1. Open Internet Information Server (IIS) Manager
   2. Click on the server name and open the ISAPI Filters tab

   3. NOTE: If you don't see ISAPI Filter tab,

      1. Navigate to 'Control Panel > Programs > Turn Windows Features on/off'
      2. In the tree find 'Internet Information Services > World Wide Web Services > Application Development Features' and make sure the ISAPI Extension and ISAPI Filter options are selected.

   4. You should see

      • Name = Shibboleth
      • Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi-shib.dll (for a 64-bit install)
      • Executable = C:\opt\shibboleth-sp\lib\shibboleth\isapi-shib.dll (for a 32-bit install)
   5. If you do not see this, right-click and add 'Name = Shibboleth' and 'Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll' or 'Executable = C:\opt\shibboleth-sp\lib\shibboleth\isapi_shib.dll' accordingly.

Result

The Shibboleth Service Provider should now be installed on the system.

Important Directories:

• C:\opt\shibboleth-sp\etc\shibboleth Configuration directory of Shibboleth. The main configuration file is shibboleth2.xml.
• C:\opt\shibboleth-sp\var\log\shibboleth Log directory where logs are written to. The most important log file is the shibd.log file that should be consulted in case of problems.
• C:\opt\shibboleth-sp\var\run\shibboleth Runtime directory where process ID and socket files are stored.
• C:\opt\shibboleth-sp\var\cache\shibboleth Cache directory where metadata backup and CRL files are stored.

Requirements

1. Apache Web Server

   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.

2. Root Access

   You should have the ability to run commands as a user with root privileges.

3. SSL Enabled for Apache

   The Apache SSL module must be enabled and configured to support HTTPS.

Recommendations

1. NTP

   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.

Installation

The installation guide from Shibboleth can be found here: Install on Linux, RPMInstall

1. Download the Shibboleth Service Provider from the repository

   • CentOS 7

     sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/security:shibboleth.repo
     				

   • RedHat 7

     sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/security:shibboleth.repo
     				

2. Install the repository

   • 32 bit -

     sudo yum install shibboleth

   • 64 bit -

     sudo yum install shibboleth.x86_64

3. Start and enable the shibd daemon

   • CentOS 7 / RedHat 7

     sudo systemctl start shibd.service

     sudo systemctl enable shibd.service

Verification

1. 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.

2. 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".

3. mod_shib Check

   Restart the web server:

   sudo apachectl restart

   Then access: https://localhost/Shibboleth.sso/Session

   The web server should return a page that says: "A valid session was not found".

Result

The Shibboleth Service Provider should now be installed on the system.

Important Directories:

• /etc/shibboleth Configuration directory of Shibboleth. The main configuration file is shibboleth2.xml.
• /var/log/shibboleth Log directory where logs are written to. The most important log file is the shibd.log file that should be consulted in case of problems.
• /run/shibboleth Runtime directory where process ID and socket files are stored.
• /var/cache/shibboleth Cache directory where metadata backup and CRL files are stored.

Requirements

1. Apache Web Server

   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.

2. Root Access

   You should have the ability to run commands as a user with root privileges.

3. SSL Enabled for Apache

   The Apache SSL module must be enabled and configured to support HTTPS.

Recommendations

1. NTP

   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.

Installation

The installation guide from Shibboleth can be found here: Install on Linux, RPMInstall

1. Download the Shibboleth Service Provider from the repository

   • CentOS 6

     sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/CentOS_CentOS-6/security:shibboleth.repo
     				

   • RedHat 6

     sudo curl -o /etc/yum.repos.d/security:shibboleth.repo http://download.opensuse.org/repositories/security:/shibboleth/RHEL_6/security:shibboleth.repo
     				

2. Install the repository

   • 32 bit -

     sudo yum install shibboleth

   • 64 bit -

     sudo yum install shibboleth.x86_64

3. Start and enable the shibd daemon

   • CentOS 6 / RedHat 6

     sudo service shibd start

Verification

1. 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.

2. 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".

3. mod_shib Check

   Restart the web server:

   sudo apachectl restart

   Then access: https://localhost/Shibboleth.sso/Session

   The web server should return a page that says: "A valid session was not found".

Result

The Shibboleth Service Provider should now be installed on the system.

Important Directories:

• /etc/shibboleth Configuration directory of Shibboleth. The main configuration file is shibboleth2.xml.
• /var/log/shibboleth Log directory where logs are written to. The most important log file is the shibd.log file that should be consulted in case of problems.
• /run/shibboleth Runtime directory where process ID and socket files are stored.
• /var/cache/shibboleth Cache directory where metadata backup and CRL files are stored.

Prerequisites

1. Shibboleth Service Provider is installed.
2. SSL enabled for IIS

Requirements

1. IIS Management Compatibility

   The IIS Management Compatibility is required if you want the Shibboleth Installer to configure IIS for you.

Shibboleth Service Provider Configuration File - shibboleth2.xml

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

1. Production: https://login.wisc.edu/spgen
2. QA: https://loginqa.wisc.edu/spgen
3. Test ("ITE"): https://logintest.wisc.edu/spgen
4. Wisconsin Federation: https://wayf.wisconsin.edu/spgen/

Example and Explanation of Shibboleth2.xml file

Download Metadata Signing Certificate

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

1. Metadata Signing Certificate for UW-Madison:
   • Production Metadata Signing Certificate
   • QA Metadata Signing Certificate
   • Test ("ITE") Metadata Signing Certificate
2. Metadata Signing Certificate for Wisconsin Federation:
   • Wisconsin Federation Metadata Signing Certificate

Prerequisites

1. Shibboleth Service Provider is installed.
2. SSL enabled for Apache

Requirements

1. Root Access - Must be possible to execute commands as user with root privileges or with sudo command.
2. OpenSSL - For verifying certificate finger prints or for certificate inspection OpenSSL is required.

Shibboleth Service Provider Configuration File - shibboleth2.xml

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:

1. Production: https://login.wisc.edu/spgen
2. QA: https://loginqa.wisc.edu/spgen
3. Test ("ITE"): https://logintest.wisc.edu/spgen
4. Wisconsin Federation: https://wayf.wisconsin.edu/spgen/

Example and Explanation of Shibboleth2.xml file

Download Metadata Signing Certificate

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

1. Metadata Signing Certificate for UW-Madison:
   • Production Metadata Signing Certificate
   • QA Metadata Signing Certificate
   • Test ("ITE") Metadata Signing Certificate
2. Metadata Signing Certificate for Wisconsin Federation:
   • Wisconsin Federation Metadata Signing Certificate

Example: sudo curl https://login.wisc.edu/metadata/login.wisc.edu-signing.pem -O /etc/shibboleth/login.wisc.edu-signing.pem

Apache Configuration

The apache configuration guide from Shibboleth can be found here: Apache Configuration Guide

1. Routing Handler URLs

   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>
   			

2. ServerName

   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

3. UseCanonicalName

   Set UseCanonicalName On by editing the httpd.conf file

4. Enable Authentication for a specific Directory

   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.

5. Restart Apache

   The last step is to restart apache after the configuration.

   sudo apachectl restart

Verification

1. Verify MD5 Checksum

   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.

2. Restart Shibboleth and Apache

   sudo systemctl restart shibd.service

   sudo systemctl restart httpd.service

3. Examine Logs

   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)

4. Access Metadata

   Navigate to: https://www.yoursite.wisc.edu/Shibboleth.sso/Metadata

   Verify that there is XML metadata content at this path.

Prerequisites

1. Shibboleth Service Provider is installed.
2. SSL enabled for Apache

Requirements

1. Root Access - Must be possible to execute commands as user with root privileges or with sudo command.
2. OpenSSL - For verifying certificate finger prints or for certificate inspection OpenSSL is required.

Shibboleth Service Provider Configuration File - shibboleth2.xml

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:

1. Production: https://login.wisc.edu/spgen
2. QA: https://loginqa.wisc.edu/spgen
3. Test ("ITE"): https://logintest.wisc.edu/spgen
4. Wisconsin Federation: https://wayf.wisconsin.edu/spgen/

Example and Explanation of Shibboleth2.xml file

Download Metadata Signing Certificate

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

1. Metadata Signing Certificate for UW-Madison:
   • Production Metadata Signing Certificate
   • QA Metadata Signing Certificate
   • Test ("ITE") Metadata Signing Certificate
2. Metadata Signing Certificate for Wisconsin Federation:
   • Wisconsin Federation Metadata Signing Certificate

Example: sudo curl https://login.wisc.edu/metadata/login.wisc.edu-signing.pem -O /etc/shibboleth/login.wisc.edu-signing.pem

Apache Configuration

The apache configuration guide from Shibboleth can be found here: Apache Configuration Guide

1. Routing Handler URLs

   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>
   			

2. ServerName

   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

3. UseCanonicalName

   Set UseCanonicalName On by editing the httpd.conf file

4. Enable Authentication for a specific Directory

   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.

5. Restart Apache

   The last step is to restart apache after the configuration.

   sudo apachectl restart

Verification

1. Verify MD5 Checksum

   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.

2. Restart Shibboleth and Apache

   sudo service shibd restart

   sudo service httpd restart

3. Examine Logs

   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)

4. Access Metadata

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

• uid: This is the User's NetID

• ePPN (eduPersonPrincipalName): This is the Scoped NetID. This identifier is the person's login name or userID (uid) followed by a namespace. The domain that comes after the @ sign defines a namespace (scope) which provides a uniqueness for the identifier. Example: bbadger@wisc.edu

• wiscEduPVI: An internal unique identifier attribute.

• wiscEduPrivacyFlag: This attribute indicates if the person's educational data is protected by the FERPA Policy.

• eduPersonTargetedID: A unique ID that identifies a person while preserving their privacy. This value is unique per Service Provider.

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