NetID Login Service - Getting Started

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.

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.

1. Installing Shibboleth Service Provider

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

  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. 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)
    4. 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.
    5. 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.

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.

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

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.

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.

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

4. User Attributes from Identity Provider

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:

  • 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

5. Using Manifest Grouping Services for Authorization

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

UW-Madison NetID Login Identity Provider Information

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




Keywords:netid login service sso saml2 shib shibboleth SP service provider Apache IIS   Doc ID:86317
Owner:Shreyash S.Group:Middleware
Created:2018-10-09 12:17 CSTUpdated:2018-12-07 10:06 CST
Sites:Access Management Services, DoIT Help Desk, Middleware
Feedback:  0   0