NetID Login Integration Overview

1. NetID Login Service - Getting Started
   1. OIDC
   2. SAML
   3. FERPA and Population Scope
2. Manifest and User Access
3. Shibboleth Configuration
   1. Obtaining attribute-map.xml
   2. Shibboleth SP Configuration File (shibboleth2.xml)
   3. Single Logout
   4. Enable Shibboleth Authentication for a Specific Path
   5. Secure Cookies
   6. Server Variables and Mapped Attributes
   7. Advanced Configuration Settings
   8. Integrating Shibboleth SP with Manifest

NetID Login Service - Getting Started with Single-Sign On

Looking to integrate an application with NetID Login? Start here by submitting an IAM intake request: https://it.wisc.edu/services/identity-access-management-work-request/

Otherwise if you are new to SSO or haven't integrated a service with IAM before, please continue below and refer back to the form when ready.

What is Single-Sign On?

Single-Sign On is an authentication process that allows a user to log into multiple applications or systems using a single credential. At UW Madison we use NetID as this credential.

Common terminology

• Service Provider (SP) - An SP is a web service that provides services/resources to a user that has been authorized to use it (your application).

• Identity Provider (IdP) - An IdP acts as a data source for user information and an authenticator to validate users before they can access the SP (NetID Login).

• Attribute - A means for delivering information to the Service Provider about the authenticated user after logging into the application/resource. For example, NetID, first name, last name, student ID are all examples of attributes.

• Identifier - An attribute that is selected to be the unique identifier for each user. Most often this is tied to the user account within your application as their username, NetID or NetID@wisc.edu (scoped NetID) are commonly used. It is important to consider an attribute that does not change (immutable) otherwise you risk a situation where a user could be locked out of their account within your service.
  
  

OIDC and SAML - protocols for SSO

• OIDC (OpenID Connect) - A modern and lightweight option for enabling SSO within applications.
  
  
• SAML (Security Assertion Markup Language) - Standard protocol for SSO authentication in many legacy applications.

NetID Login supports both OIDC and SAML protocols for SSO, depending on your use-case you may prefer one over the other. However if both are available, OIDC is our recommendation.

Madison and Universities of Wisconsin

If your user population includes non-Madison campuses you will need to connect your service to the UW Proxy IdP and the WAYF (where are you from) service which will enable users to select a UW campus from a drop-down menu when logging in. Consider this when deciding on which configuration options to follow below.

Configure SSO with OIDC

UW Madison: Point your service to the NetID Login OIDC URL: https://login.wisc.edu/.well-known/openid-configuration

Universities of Wisconsin: Point your service to the UWProxy Login OIDC URL: https://idp.iam.wisconsin.edu/.well-known/openid-configuration

Alternatively, your SP may auto-configure if you can provide the issuer URL.

UW Madison: https://login.wisc.edu

Universities of Wisconsin: https://idp.iam.wisconsin.edu

For all OIDC integrations, the IAM team will need you to provide the following details:

• A client_id that is descriptive and unique, in most cases the URL is sufficient as long as it won't be used for something else in the future (in which case there may be a conflict).
• A redirect_uri or in some cases multiple if there's more than 1 hostname and one each for SSL and non-SSL sites. These must include the http:// or https:// preface, otherwise it can cause issues.
• token_endpoint_auth_method options, if unsure let us know:
  • basic
  • post
• Once we have this information and it is configured on our end we will reach out with a client_secret.

OIDC Scopes and Attributes

There are a number of scopes available to customers each with a set of one or more attributes, let us know if your application will need any of these attributes and we will include the proper scope. Scopes (in bold) with their included attributes are listed below:

Madison OIDC Scopes and Attributes

Universities of Wisconsin (UW Proxy IdP) OIDC Scopes and Attributes

Configure SSO with SAML

SSO with SAML requires an exchange of metadata between IdP and SP. If you do not have any metadata XML to share with us we will need at-minimum the following details.

• entityID: The unique ID (often but not always a URL) of your service.
• ACS endpoint: The site we send the user to after authentication to complete the login flow.

Signing and encryption certificates are optional. Below are the metadata locations for our IdPs, depending on the service you may be able to give it the URL to parse automatically or you can visit the link and manually extract the details you need.

IdP metadata URL for UW Madison: https://login.wisc.edu/idp/shibboleth

IdP metadata URL for Universities of Wisconsin: https://idp.iam.wisconsin.edu/uwproxy/shibboleth

SAML Attributes

Default Attribute Release for UW Madison

Default Attribute Release for Universities of Wisconsin

If your service provider needs additional attributes beyond what is provided by default please mention these when completing the IAM work request form.

FERPA and Population Scope

If students are expected to use this service then you will most likely need to request approval for FERPA which will require additional review by Cybersecurity and the Registrar's office. Without FERPA approval, students that have elected for it may not be able to log into it if the service requires attributes that are protected behind FERPA. Those attributes include:

• First name
• Last name
• Email
• Phone number
• Addresses

If the application does not need any of these then it might not be necessary to submit a review for approval. Be sure to mention any need for FERPA data when submitting an IAM work request form.

We also release data using population scopes, you will need to determine if your user base will consist of affiliates, employees, students or all three.

Manifest and User Access

This section describes the use of Manifest groups to control user access and assumes some level of familiarity. For more thorough documentation on the Manifest tool please review this document: https://kb.wisc.edu/iam/page.php?id=27796

Once SSO is configured and working, anybody with a NetID might be able to log in if automatic account provisioning is enabled in your application and it's accessible on the network (public-facing, not behind a firewall etc). Unless the intended audience is campus-wide it's recommended to restrict access by using Manifest groups. 

You will first need to choose an existing Manifest group or create a new one, let us know if you would like one created when submitting the work request form. We will need to know what the Path value is of that group, you can find it on the main page of the group. In the example image below, the path value is: uw:etc:middleware:test:adtest

Once a group is determined, the client_id (OIDC) or entityID (SAML) will need to be tied to it. Select the 'More actions' drop-down button and then 'Edit delivery/connection options'. Enter your ID into the box and then click 'Add entity'. Ignore the SAML2-specific language if using OIDC, your client_id still goes here.

When added it will appear below the text window. A Manifest group can have multiple service providers tied to it. Publishing to campus AD or Azure AD is not necessary for this to work (ignore those options). Hit 'Save' when done.

A useful feature of this is the ability to use Workday sup org groups to automatically manage group membership. Let us know if there is a specific population within your department you would like to add, or if you would like help with figuring that out (for example, students or employees only). It's also recommended to create an 'ad hoc' group that is a member of this group tied to the service provider, that way you have the ability to add admins or special users not included by Workday.

After the group has been created, the client_id or entityID has been tied to the group, and the work is done on our end, only users that are members of that group (directly or inherited) will be able to log into the service.

Shibboleth Configuration

From this point on this article pertains to specific details for installing Shibboleth SP as an option for a self-provided SSO service provider. Unless installing and self-hosting Shibboleth SP is the goal it is not necessary to continue. If you have any questions not answered above please reach out to IAM or include them in the IAM work request form.

Extensive documentation for installing and configuring Shibboleth SP can be found here: https://kb.wisc.edu/iam/86317

Getting the attribute-map.xml

It's recommended that your application pull in attribute-map.xml url to ensure that any updates that are made to it will be passed to your application by configuring the AttributeExtractor element in your shibboleth2.xml configuration file. The attribute-map will decode SAML attributes for your application, for more information: Shibboleth documentation on AttributeExtractor.

• NetID Login attribute-map.xml (UW Madison): https://login.wisc.edu/metadata/attribute-map.xml
• Wisconsin Federation attribute-map.xml: https://wayf.wisconsin.edu/metadata/attribute-map.xml

Shibboleth SP Configuration File (shibboleth2.xml)

• NetID Login (UW Madison)
  
  
• Wisconsin Federation

No Single Logout

Single Logout in the context of the UW NetID Login Service would be the action of clicking a Logout link or button that would cause the user to be logged out of all NetID Login-protected applications at once.  Currently, Single Logout is not possible in the UW NetID Login Service.  There are many reasons for this, and if you're interested in details this document provides a good overview.

The only complete NetID logout is closing the browser and clearing all session cookies, which is the end user's responsibility.  End users can review instructions on clearing cookies and making sure their browser is safely configured here: NetID Login Service - Logout Procedure.

Logout of individual applications

Application developers can use the central NetID logout page (https://login.wisc.edu/logout) as a way of requiring users to sign back in with their NetID in order to:

• Return to the most recently used NetID-protected web application or
  
  
• Access any NetID-protected resources not previously visited during that browsing session

When the user clicks a link to the NetID logout page, their session on the login server will be cleared.  However, the central logout page will not log the user out of other NetID-protected resources they've already signed into during the current browsing session (e.g. other tabs in the same browser). Those resources will remain available without the need to sign in again until the user closes the browser and clears the session cookies.

In Shibboleth, redirection to the central logout page can be done by using the Logout property of the Shibboleth handler to perform a Local Logout and attaching a return value that redirects the user to the UW NetID Login Service logout page.

Here's a sample logout link for the application example.dept.wisc.edu:

<a href="https://example.dept.wisc.edu/Shibboleth.sso/Logout?return=https://login.wisc.edu/logout">Logout</a>

Enable Shibboleth Protection for a Specific Path

1. Linux
   

   Once the installation of the Shibboleth 2 SP is complete, you can require Shibboleth authentication for accessing any directory in your site/application by adding Apache directives in the .conf file or .htaccess. 

   A note about security: It's very important to limit cookie use to encrypted requests. SSL should be required for any URL using Shibboleth authentication. To ensure that SSL is always used, you want to redirect protected paths to SSL using native Apache functionality (i.e. redirects or rewrite rules).

   httpd.conf

   It's best to identify the directory by its physical path.  You need to require a Shibboleth session and set Require valid-user, which will make the directory available to anyone successfully logging in with a UW NetID.

   Example:

   <Directory "/var/www/yoursite.wisc.edu/html/shib">
   AuthType shibboleth
   ShibRequestSetting requireSession 1
   Require valid-user
   </Directory>

   There are a number of variations on these settings.  For example, you can use the AuthGroupFile and Require Group attributes to limit access to the directory to specific NetIDs only.  As usual with settings in the httpd.conf file, an Apache restart is required for the changes to take effect.

   .htaccess

   You can also configure Shibboleth protection for a directory using an .htaccess file.  This method is especially helpful for web developers who do not have access to the httpd.conf file or in cases where an Apache restart is not practical.  

   The syntax is almost the same as in the httpd.conf example, except that the directory information is not necessary:

   AuthType shibboleth
   ShibRequestSetting requireSession 1
   Require valid-user

   The directives will apply to the directory where the .htaccess file is located and to its subdirectories.

   The full range of configuration options for Apache can be found here on the Shibboleth wiki. 
   
   
2. Windows
   

   To require Shibboleth authentication for specific directories, you need to edit the RequestMapper section of the shibboleth2.xml. List each directory you want to protect as a Path within the application's Host element in the RequestMapper.

   Shibboleth will put together the hostname followed by the paths you define, and use this information to determine which URLs to protect. These are not physical paths, but URLs, so use forward slashes to separate subdirectories. More details here on hostnames and paths.

   In the example below, a new subdirectory new_path has been added for sp.example.org and the entire newsite.wisc.edu is protected by adding authType="shibboleth" requireSession="true" to the Host element.

   
   <RequestMapper type="Native"> 
   <RequestMap applicationId="default"> 
   
   <Host name="sp.example.org"> 
   <Path name="secure" authType="shibboleth" requireSession="true" redirectToSSL="443"/> 
   <Path name="new_path" authType="shibboleth" requireSession="true" redirectToSSL="443"/> 
   
   </Host> 
   
   <Host name="newsite.wisc.edu" authType="shibboleth" requireSession="true" redirectToSSL="443"/> 
   
   </RequestMap> 
   </RequestMapper>

   The redirectToSSL="443" attribute is important, because it forces the request for the protected path to SSL, preventing user information from being sent over the internet unencrypted.

   The RequestMapper is a reloadable resource, so the settings will be updated every time you save the shibboleth2.xml.

Secure Cookies

<ApplicationOverride id="https://www.firstapplication.wisc.edu/shibboleth" entityID="https://www.firstapplication.wisc.edu/shibboleth">
    <Sessions lifetime="28800" timeout="1800" checkAddress="false" consistentAddress="false" relayState="ss:mem" handlerURL="/Shibboleth.sso" cookieProps="https">
        <SSO entityID="https://login.wisc.edu/idp/shibboleth">
            SAML2 SAML1
        </SSO>
    </Sessions>
</ApplicationOverride>

<ApplicationOverride id="https://www.secondapplication.wisc.edu/shibboleth" entityID="https://www.secondapplication.wisc.edu/shibboleth">
    <Sessions lifetime="28800" timeout="1800" checkAddress="false" consistentAddress="false" relayState="ss:mem" handlerURL="/Shibboleth.sso" cookieProps="https">
        <SSO entityID="https://login.wisc.edu/idp/shibboleth">
            SAML2 SAML1
        </SSO>
    </Sessions>
</ApplicationOverride>

<Location />
  AuthType shibboleth
  ShibRequestSetting applicationId https://www.firstapplication.wisc.edu/shibboleth
  ShibRequestSetting requireSession 1
  require shib-session
</Location>

<Location />
  AuthType shibboleth
  ShibRequestSetting applicationId https://www.secondapplication.wisc.edu/shibboleth
  ShibRequestSetting requireSession 1
  require shib-session
</Location>

<RequestMapper type="Native">
    <RequestMap applicationId="default">
        <Host name="www.firstapplication.wisc.edu" applicationId="https://www.firstapplication.wisc.edu/shibboleth" authType="shibboleth" requireSession="true"/>
        <Host name="www.secondapplication.wisc.edu" applicationId="https://www.secondapplication.wisc.edu/shibboleth" authType="shibboleth" requireSession="true"/>
    </RequestMap>
</RequestMapper>

<ApplicationOverride id="https://www.application.wisc.edu/first/shibboleth" entityID="https://www.application.wisc.edu/first/shibboleth">
    <Sessions lifetime="28800" timeout="1800" checkAddress="false" consistentAddress="false" relayState="ss:mem" handlerURL="/first/Shibboleth.sso" cookieProps="https">
        <SSO entityID="https://login.wisc.edu/idp/shibboleth">
            SAML2 SAML1
        </SSO>
    </Sessions>
</ApplicationOverride>

<ApplicationOverride id="https://www.application.wisc.edu/second/shibboleth" entityID="https://www.application.wisc.edu/second/shibboleth">
    <Sessions lifetime="28800" timeout="1800" checkAddress="false" consistentAddress="false" relayState="ss:mem" handlerURL="/second/Shibboleth.sso" cookieProps="https">
        <SSO entityID="https://login.wisc.edu/idp/shibboleth">
            SAML2 SAML1
        </SSO>
    </Sessions>
</ApplicationOverride>

<Location /first>
  AuthType shibboleth
  ShibRequestSetting applicationId https://www.application.wisc.edu/first/shibboleth
  ShibRequestSetting requireSession 1
  require shib-session
</Location>

<Location /second>
  AuthType shibboleth
  ShibRequestSetting applicationId https://www.application.wisc.edu/second/shibboleth
  ShibRequestSetting requireSession 1
  require shib-session
</Location>

<RequestMapper type="Native">
    <RequestMap applicationId="default">
        <Host name="www.application.wisc.edu">
            <Path name="first" applicationId="https://www.application.wisc.edu/first/shibboleth" authType="shibboleth" requireSession="true"/>
            <Path name="second" applicationId="https://www.application.wisc.edu/second/shibboleth" authType="shibboleth" requireSession="true"/>
        </Host>
    </RequestMap>
</RequestMapper>

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://originalhost.wisc.edu/Shibboleth.sso/SAML2/POST" index="1"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://originalhost.wisc.edu/Shibboleth.sso/SAML2/POST-SimpleSign" index="2"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://originalhost.wisc.edu/Shibboleth.sso/SAML2/Artifact" index="3"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://originalhost.wisc.edu/Shibboleth.sso/SAML2/ECP" index="4"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://originalhost.wisc.edu/Shibboleth.sso/SAML/POST" index="5"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="https://originalhost.wisc.edu/Shibboleth.sso/SAML/Artifact" index="6"/>

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://additionalhost.wisc.edu/Shibboleth.sso/SAML2/POST" index="1"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://additionalhost.wisc.edu/Shibboleth.sso/SAML2/POST-SimpleSign" index="2"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://additionalhost.wisc.edu/Shibboleth.sso/SAML2/Artifact" index="3"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://additionalhost.wisc.edu/Shibboleth.sso/SAML2/ECP" index="4"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://additionalhost.wisc.edu/Shibboleth.sso/SAML/POST" index="5"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="https://additionalhost.wisc.edu/Shibboleth.sso/SAML/Artifact" index="6"/>
	

<Directory "/var/www/sample.wisc.edu/htdocs/protected">
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        Require shib-session
</Directory>

<Directory "/var/www/sample.wisc.edu/htdocs/protected/unprotected">
        AuthType shibboleth
        ShibRequestSetting requireSession 0
        Require shib-session
</Directory>

<Host name="sample.wisc.edu">
   <Path name="protected" authType="shibboleth" requireSession="true" redirectToSSL="443" >  
      <Path name="unprotected" requireSession="false"/>
   </Path>
</Host> 

AuthType shibboleth
ShibRequestSetting requireSession 0
Require shibboleth

Integrating Shibboleth SP with Manifest

After a user authenticates with their NetID and password, Manifest can deliver group information through a Shibboleth attribute called "isMemberOf". Only groups that have been configured with your application's SAML2 Entity ID will be delivered. In this way, we ensure that your groups are only available for your applications to consume.

Locate Your Application's SAML2 EntityID

Configure Shibboleth for the "isMemberOf" Attribute

Authorization Using Manifest Groups (IIS)

Configuration File Directives