NetID Login Service - Configuration

This document describes configuration steps for Application Administrators who are looking to integrate their Web-based application with the UW-Madison NetID Login Service.

Overview

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:

  1. User attempts to access a NetID Login protected web application. This resource is called a Service Provider (SP).
  2. User is redirected to the NetID Login Identity Provider (IdP) at https://login.wisc.edu/.
  3. The IdP authenticates the user (prompting the user for NetID and password and multifactor, as appropriate). If the user successfully authenticates, they are redirected to the original SP.

Configuring Shibboleth Service Provider

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

NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

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:
  2. Metadata Signing Certificate for Wisconsin Federation:

Service Provider Activation

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.

Prerequisites

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

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

NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

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:
  2. Metadata Signing Certificate for Wisconsin Federation:

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 (IDK about this section. We would need a different one for each environment)

    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.

Service Provider Activation

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.

Prerequisites

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

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

NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

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:
  2. Metadata Signing Certificate for Wisconsin Federation:

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 (IDK about this section. We would need a different one for each environment)

    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.

Service Provider Activation

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.