NetID Login Integration Overview

A collection of information and documents in reference to integrating a service provider with one of our Shibboleth IdPs

NetID Login Service - Getting Started
Manifest and User Access
Shibboleth Configuration

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

profile
- displayName
- givenName
- surname
email
- mail
openid
- sub
- uid
- eduPersonPrincipalName
- wiscEduPVI
offline_access
- Optional: This scope can be used to issue refresh tokens, though the use of refresh tokens is not exclusive to using the offline_access scope

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

profile
- displayName
- givenName
- surname
email
- mail
openid
- sub
- eduPersonPrincipalName
- eduPersonAssurance
- eduWisconsinSPVI

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

The default attribute release consists of the attributes that are released to the Service Provider without any form of data request

uid
- User's NetID
ePPN (eduPersonPrincipalName)
- Appears as a scoped username
- The 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
- Another 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

Default Attribute Release for Universities of Wisconsin

Minimal Attribute Bundle
- Name Identifier: SAML2 Transient NameID
- User Attribute: eduPersonScopedAffiliation
Additional bundles found at InCommon - Default Attribute Release.

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 the release of person data (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. The list below contains types of data that require FERPA approval and is not a list of actual attribute names in a particular source.

Name
- The Preferred Name, if an individual has one set
- Source of Record name if no preferred name has been specified

Email Address
- Business email address for employees
- Campus email address for students
Note: Email addresses are not validated, and should NOT be used as an account identifier.
NetID or other account name

Public Contact Information / Directory Information
- For Employees: Title, department, and campus phone
- For Students: Local phone and campus email

Affiliation Data
- For Employees: Title, classification, and employing department
- For Students: Enrollment status, degree sought, and program of study
- For Others: non-sensitive information describing their relationship to the institution (e.g. volunteer, guest, affiliate)

Internal Identifiers to crosswalk between IT systems
- PVI
- Workday and / or SIS EmplID
- SIS Campus ID or photo ID #
Group Memberships
- Manifest group information that is derived from the data above

An application's use of person data must be consistent with campus policy: https://policy.wisc.edu/library/UW-517

Be sure to mention any need for person 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

manifest_group_path_example

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.

delivery_connection_example

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 Installation and 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.

Getting Started with Shibboleth

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. In addition to SAML2, NetID Login supports OIDC.

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:

User attempts to access a NetID Login protected web application. This resource is called a Service Provider (SP).
User is redirected to the NetID Login Identity Provider (IdP) at https://login.wisc.edu/.
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.

Installing Shibboleth Service Provider

Windows Server IIS

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

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/
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

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'
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.
6. OPTIONAL: If Shibboleth / IIS has been migrated from another server to a new one check to make sure that the ISAPI filters are in the correct directories. This is a somewhat common issue and can result in redirecting to the wrong location after SSO POST.

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.

Windows Server Apache

The Shibboleth SP installer will install a set of Apache modules for each major version. It will also install the standalone Shibboleth daemon, shibd. Actual integration with Apache is a simple, but manual, process.

Installing Shibboleth

Download the DoIT Supported version of the .msi Shibboleth SP installer from the Shibboleth download site here.

Run the installer. The installer will prompt for an install path, change default configuration files as appropriate for Windows, and set various environment variables for you. A default shibd service can also be installed.

Installing Apache

The versions of Apache available from the http://httpd.apache.org/ web site are known to work with the modules that come with the Windows version of Shibboleth, specifically the Apache 2.0 and 2.2 packages that include SSL support.

Other versions might work, but they also might not work. Versions with significantly altered header files, such as IBM's or Oracle's will definitely not work unless you build the Shibboleth module from source.

RHEL or UBI 9 with Apache

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 dnf -y install httpd
```
Only Apache 2.4 are supported.
Root Access
You should have the ability to run commands as a user with root privileges.
SSL Enabled for Apache
The Apache SSL module must be enabled and configured to support HTTPS.
```
sudo dnf -y install mod_ssl
```

Recommendations

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

Download the Shibboleth Service Provider from the repository

UBI 9 (We can use the RockyLinux 9 package)

sudo curl -o /etc/yum.repos.d/security:shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=RockyLinux9

Install the repository
```
sudo dnf -y install shibboleth
```

Start and enable the shibd daemon

sudo systemctl start shibd.service

sudo systemctl enable shibd.service

Verification

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

Ubuntu with Apache

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 apt-get install -y apache2
```
Only Apache 2.4 are supported.
Root Access
You should have the ability to run commands as a user with root privileges.
SSL Enabled for Apache
The Apache SSL module must be enabled and configured to support HTTPS. Replace shib-ssl with your website's conf file (e.g. /etc/apache2/sites-available/shib-ssl.conf).
```
sudo a2enmod ssl && a2ensite shib-ssl
```

Recommendations

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.
```
sudo apt-get install ntp
```

Shibboleth Installation

Ubuntu / Debian is not officially supported by Shibboleth, however we can install it with this package: The installation guide from Shibboleth can be found here: Install on Linux

Here are the standard non-Debian installation docs on linux, for reference: Install on Linux

Install Shibboleth

sudo apt-get install -y libapache2-mod-shib

Enable shibd to activate on startup

sudo chmod +x /etc/init.d/shibd 
sudo update-rc.d shibd defaults

Start the Shibboleth daemon and examine the logs for any errors

sudo service shibd start

grep E 'CRIT|ERROR' /var/log/shibboleth/shibd.log

You may see the following item in the shibd log, you can ignore it for now

CRIT Shibboleth.Application : no MetadataProvider available, configuration is probably unusable

You may also see the following error indicating that your Shibboleth key pair is missing

ERROR OpenSSL : error data: fopen('/etc/shibboleth/sp-key.pem','r')

CRIT Shibboleth.Application : error building CredentialResolver: Unable to load private key from file (/etc/shibboleth/sp-key.pem)

If you encounter this error you can generate a key-pair for Shibboleth with the following command

sudo openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:2048 -subj "/CN=$HOSTNAME" -keyout /etc/shibboleth/sp-key.pem -out /etc/shibboleth/sp-cert.pem

Then restart the Shibboleth service

sudo service shibd restart

Verification

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

Result

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

Open a web browser and point to your site with the following Shibboleth path:

https://www.yoursite.wisc.edu/Shibboleth.sso/Session

Verify that you see this message:

A valid session was not found.

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.
/var/cache/shibboleth Cache directory where metadata backup and CRL files are stored.

Configuring Shibboleth Service Provider

Windows Server IIS

Prerequisites

Shibboleth Service Provider is installed.
SSL enabled for IIS

Requirements

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

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

Example and Explanation of Shibboleth2.xml file

UW Madison application administrators: NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

Wisconsin federation application administrators: Wisconsin Federation 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

Metadata Signing Certificate for UW-Madison:
Metadata Signing Certificate for Wisconsin Federation:
- Wisconsin Federation Metadata Signing Certificate

Windows Server Apache

Basic Configuration

Edit httpd.conf: Shibboleth bundles configuration directives in the files

\etc\shibboleth\apache.config,
\etc\shibboleth\apache2.config, and
\etc\shibboleth\apache22.config

which can be added to httpd.conf using the Include command. Be wary of placing the configuration in the wrong VirtualHost.

Other considerations:

The UseCanonicalName directive should be set to On.
Ensure that the ServerName directive is properly set, and that Apache is being started with SSL enabled.
The primary configuration file for the module and the Shibboleth daemon, shibd, will be located at \etc\shibboleth\shibboleth2.xml (within the directory used to install the SP software). shibd creates its own log at \var\log\shibboleth\shibd.log and must have appropriate read and write permissions itself for the entire installation directory.
Apache also will need read access to most of the installation, with the exception of your Shibboleth private key file(s). It also needs write access to \var\log\shibboleth to create the native.log file.

Download Metadata Signing Certificate

Save this file in the Shibboleth installation directory (Default: \etc\shibboleth)

UW-Madison and UW-Madison Federation (eg. PubCookie Replacement)
- Production: https://login.wisc.edu/metadata/login.wisc.edu-signing.pem
- QA: https://loginqa.wisc.edu/metadata/loginqa.wisc.edu-signing.pem
- Test ("ITE"): https://logintest.wisc.edu/metadata/logintest.wisc.edu-signing.pem
Wisconsin Federation (eg. Approved IAA Request)
- Download the Signing Certificate
- Or Copy&Paste this address into your address bar: https://wayf.wisconsin.edu/metadata/wayf.wisconsin.edu-signing.pem

Generate Shibboleth2.xml File

After installing the SP software for Shibboleth you'll need to configure the shibboleth2.xml file correctly to work with the NetID Login Service. We recommend you use the automatic shibboleth2.xml generator.

Automatic Shibboleth2.xml Generator

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

RHEL / UBI / CentOS

Prerequisites

Shibboleth Service Provider is installed.
SSL enabled for Apache

Requirements

Root Access - Must be possible to execute commands as user with root privileges or with sudo command.
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:

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

Example and Explanation of Shibboleth2.xml file

UW Madison application administrators: NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

Wisconsin federation application administrators: Wisconsin Federation 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

Metadata Signing Certificate for UW-Madison:
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

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>
			
```
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
UseCanonicalName
Set UseCanonicalName On by editing the httpd.conf file
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.
Restart Apache
The last step is to restart apache after the configuration.
```
sudo apachectl restart
```

Verification

Verify SHA256 Checksum
Execute: sha256sum /etc/shibboleth/login.wisc.edu-signing.pem

You should see: b1d9fba910de2984bf679d30d1858d39794916fe41f98d1a37ed77e318ef7a3e /etc/shibboleth/login.wisc.edu-signing.pem
If you do not see this please contact help@login.wisc.edu.

Restart Shibboleth and Apache

sudo systemctl restart shibd.service

sudo systemctl restart httpd.service

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)
Access Metadata
Navigate to: https://www.yoursite.wisc.edu/Shibboleth.sso/Metadata

Verify that there is XML metadata content at this path.

Ubuntu

Prerequisites

Shibboleth Service Provider is installed.
SSL enabled for Apache

Requirements

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

Shibboleth Service Provider Configuration File - shibboleth2.xml

shibboleth2.xml generator:

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

Example and Explanation of Shibboleth2.xml file

UW Madison application administrators: NetID Login Service - Shibboleth Service Provider Configuration File (shibboleth2.xml)

Wisconsin federation application administrators: Wisconsin Federation 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

Metadata Signing Certificate for UW-Madison:
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

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>
			
```
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
UseCanonicalName
Set UseCanonicalName On by editing the httpd.conf file
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.

Restart Apache

The last step is to restart apache after the configuration.

sudo apachectl restart

Verification

Verify SHA256 Checksum
Execute: sha256sum /etc/shibboleth/login.wisc.edu-signing.pem

You should see: b1d9fba910de2984bf679d30d1858d39794916fe41f98d1a37ed77e318ef7a3e /etc/shibboleth/login.wisc.edu-signing.pem
If you do not see this please contact help@login.wisc.edu.

Restart Shibboleth and Apache

sudo service shibd restart

sudo service httpd restart

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)
Access Metadata
Navigate to: https://www.yoursite.wisc.edu/Shibboleth.sso/Metadata

Verify that there is XML metadata content at this path.

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

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. Refer to the SAML section of this document for more information on the default attribute set.

If your application requires data about users other than the default set, you will need to submit an IAM work request.

For more information about data elements that are approved for authorized applications see: APPROVED ATTRIBUTES FOR RELEASE TO APPLICATIONS

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

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)

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

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

For Shibboleth to provide secure authentication, users must be required to communicate with the application server and the login server over an encrypted connection, so that user-specific data is not passed over the internet in plain text. There are just a couple steps to requiring an encrypted connection for all Shibboleth traffic:

Force SSL on all Paths

Any path you define as requiring Shibboleth authentication should be accessible only over SSL.

On a Windows server, you can accomplish this by adding the redirectToSSL="443" attribute to all Path elements in the RequestMap of your shibboleth2.xml (NetID Login Service - Requiring Shibboleth Authentication). If you're using a port other than 443 for SSL, use that value instead. (Note that to configure Shibboleth to use a non-standard SSL port, the port number and scheme "https" must be specified in the Host element.)

In Apache, you can force SSL in a variety of ways using native functionality.
Use cookieprops

You can use the cookieprops attribute in the Sessions element of your shibboleth2.xml to limit cookie use to requests made over SSL. To do this, you add cookieProps="; path=/; secure; HttpOnly" to your Sessions element and set handlerSSL="true".

Example Sessions element using cookieprops:
```
<Sessions lifetime="28800" timeout="3600" checkAddress="false" handlerURL="/Shibboleth.sso" handlerSSL="true"
cookieProps="; path=/; secure; HttpOnly" exportLocation="localhost/Shibboleth.sso/GetAssertion" exportACL="127.0.0.1"
idpHistory="false" idpHistoryDays="7">
```

Server Variables and Mapped Attributes

Once you've set up Shibboleth authentication for your web application, you can easily check which mapped Shibboleth attributes your application is receiving and the full list of server variables available to your application.

Attributes

Once you've authenticated into your web application and established a Shibboleth session, you can use the Shibboleth handler's Session property to get a summary of the values for the Session. If your application were example.wisc.edu, you would access the Session info like this: https://example.wisc.edu/Shibboleth.sso/Session. By default, this will display the number of values the session has for each attribute, but it will not show the actual value of the attribute. To show the value of each attribute, configure the Session handler in Shibboleth2.xml such that showAttributeValues is true, as follows:
```
<Handler type="Session" Location="/Session" showAttributeValues="true"/>
```
HTTP Header Size Limit

In some cases the size of an HTTP request header sent to a webserver from the service provider may exceed its default size limit. HTTP header size is affected by things such as the amount of SAML attributes sent by your Shibboleth SP or client browsers sending their own headers. This can result in an HTTP 400 error when users try to access your site if the number of request headers exceeds your web server's limit. With the ever-growing size of HTTP headers it is recommended to increase the limits of what is acceptable, some further information can be found below:

Apache: The default HTTP header size is 8kb. To increase the limit, adjust the parameter LimitRequestFieldSize for the virtual host or other location in the Apache configuration. https://httpd.apache.org/docs/2.4/mod/core.html#limitrequestfieldsize

IIS: Set MaxFieldLength and MaxRequestBytes registry entries so that the user's request headers don't exceed these values: https://learn.microsoft.com/en-US/troubleshoot/developer/webapps/iis/www-administration-management/http-bad-request-response-kerberos

Server Variables

To see the full list of server variables available to your application, place a dynamic page inside one of your application's directories that requires Shibboleth authentication and then access the page.

If you have PHP installed on your server you can use the following:

<html>
<head>
<title>Server Variables</title>
</head>
<body>

<?PHP

foreach($_SERVER as $key_name => $key_value) {
print $key_name . " = " . $key_value . "<br>";
}

?>
</body>
</html>

For Windows, you can use an ASP page containing the following:

<html>

<head>
<title>Shibboleth Attributes - <%= Request.ServerVariables("SERVER_NAME") %></title>
  <META HTTP-EQUIV="Pragma" CONTENT="no-cache">
  <META HTTP-EQUIV="Expires" CONTENT="-1">
<script language"JavaScript" type="text/JavaScript">
<!--
  function decodeAttributeResponse() {
 	var textarea = document.getElementById("attributeResponseArea");
  	var base64str = textarea.value;
	var decodedMessage = decode64(base64str);
	textarea.value = tidyXml(decodedMessage);
	textarea.rows = 15;
	document.getElementById("decodeButtonBlock").style.display='none';
  }

  function tidyXml(xmlMessage) {
	//put newline before closing tags of values inside xml blocks
	xmlMessage = xmlMessage.replace(/([^>])</g,"$1\n<");
	//put newline after every tag
	xmlMessage = xmlMessage.replace(/>/g,">\n");
	var xmlMessageArray = xmlMessage.split("\n");
	xmlMessage="";
	var nestedLevel=0;
	for (var n=0; n < xmlMessageArray.length; n++) {
		if ( xmlMessageArray[n].search(/<\//) > -1 ) {
			nestedLevel--;
		}
		for (i=0; i<nestedLevel; i++) {
			xmlMessage+="  ";
		}
		xmlMessage+=xmlMessageArray[n]+"\n";
		if ( xmlMessageArray[n].search(/\/>/) > -1 ) {
			//level status the same
		}
		else if ( ( xmlMessageArray[n].search(/<\//) < 0 ) && (xmlMessageArray[n].search(/</) > -1) ) {
			//only increment if this was a tag, not if it is a value
			nestedLevel++;
		}
	}
  	return xmlMessage;
  }

  var base64Key = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
  function decode64(encodedString) {
    var decodedMessage = "";
    var char1, char2, char3;
    var enc1, enc2, enc3, enc4;
    var i = 0;

    //remove all characters that are not A-Z, a-z, 0-9, +, /, or =
    encodedString = encodedString.replace(/[^A-Za-z0-9\+\/\=]/g, "");
    do {
	enc1 = base64Key.indexOf(encodedString.charAt(i++));
	enc2 = base64Key.indexOf(encodedString.charAt(i++));
	enc3 = base64Key.indexOf(encodedString.charAt(i++));
	enc4 = base64Key.indexOf(encodedString.charAt(i++));

	char1 = (enc1 << 2) | (enc2 >> 4);
	char2 = ((enc2 & 15) << 4) | (enc3 >> 2);
	char3 = ((enc3 & 3) << 6) | enc4;

	decodedMessage = decodedMessage + String.fromCharCode(char1);
	if (enc3 != 64) {
		decodedMessage = decodedMessage + String.fromCharCode(char2);
	}
	if (enc4 != 64) {
		decodedMessage = decodedMessage + String.fromCharCode(char3);
	}
    } while (i < encodedString.length);
    return decodedMessage;
  }
// -->

</script>
</head>


<body>

<b>-all SHIB headers-</b> (<code>HTTP_SHIB_ATTRIBUTES</code> is not shown in this list)

<table>
<% For Each strKey In Request.ServerVariables %>
<% if InStr(1, strKey, "SHIB", 1) and not strKey="HTTP_SHIB_ATTRIBUTES"  then %>
<tr>
<td><%= strKey %></td>
<td><%= Request.ServerVariables(strKey) %></td>
</tr>

<% end if %>
<% Next %>
<tr><td>(REMOTE_USER)</td><td><%= Request.ServerVariables("REMOTE_USER") %></td></tr>
<tr><td>(HTTP_REMOTE_USER)</td><td><%= Request.ServerVariables("HTTP_REMOTE_USER") %></td></tr>

</table>
<br/>

attribute response from the IdP (<code>HTTP_SHIB_ATTRIBUTES</code>):<br/>
<textarea id="attributeResponseArea" onclick="select()" rows="1" cols="130"><%= Request.ServerVariables("HTTP_SHIB_ATTRIBUTES") %></textarea><br/>

<span id="decodeButtonBlock"><input type="button" id="decodeButton" value="decode base64 encoded attribute response using JavaScript" onClick="decodeAttributeResponse();"><br/></span>

<br/>

<small>
notes:<br/>
The AAP throws away invalid values (eg an unscopedAffiliation of value "myBoss@&lt;yourdomain&gt;" or a value with an invalid scope which scope is checked)<br/>

The raw attribute response (<code>HTTP_SHIB_ATTRIBUTES</code>) is NOT filtered by the AAP and should therefore be disabled for most applications (<code>exportAssertion=false</code>).<br/>
</small>


<br/>

<hr/>
<br/>


<table>
<% For Each strKey In Request.ServerVariables %>
<tr>
<td><%= strKey %></td>
<td><%= Request.ServerVariables(strKey) %></td>

</tr>
<% Next %>
</table>

</body>
</html>

For Linux/Apache, you can place the following Shell script in your cgi-bin directory:

#!/bin/sh
echo Content-type: text/html
echo ""
/bin/cat <<EOM
<HTML>
<BODY text="#000000">
<PRE>
EOM

/bin/env
CAT <<EOM
</PRE>
</BODY>
</HTML>
EOM

If you have Perl installed, you can use the following:

#!/usr/bin/perl

print "Content-type: text/html\n\n";
print "<pre>\n";

foreach $key (sort keys(%ENV)) {
    print "$key = $ENV{$key}<p>";
}

print "</pre>\n";

Advanced Configuration Settings

The following are advanced configuration options for Shibboleth SP when integrating with NetID Login or Wisconsin Federation IdPs.

Clustering Applications

To cluster an SP, you need to use the same private and public key pair on all servers, as well as the same entityId. However, there is session data stored in the shibd process, which is not automatically replicated to all the hosts. A load-balancer with sticky sessions can be used to keep users on the same cluster host for their entire session.

Shibboleth documentation: Clustering

Multiple Applications

Shibboleth allows you to define and run multiple applications on a single host using <ApplicationOverride> blocks.

Multiple Hostnames

If there are multiple applications running on a server with different hostnames, each application will need its own Application Override block with distinct EntityID and applicationId attributes.

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

These should be accompanied by their own Apache configurations to map them to the appropriate resources on the server.

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

In case of IIS this needs to be set up in the Request Mapper element of the shibboleth2.xml file

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

Multiple Paths

If there are multiple applications running on a server with different paths under the same hostname, each application will need its own Application Override block with distinct EntityID and applicationId attributes along with a modified handlerURL for Shibboleth handlers.

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

These should be accompanied by their own Apache configurations to map them to the appropriate resources on the server.

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

In case of IIS this needs to be set up in the Request Mapper element of the shibboleth2.xml file

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

Shibboleth documentation: ApplicationModel

Shibboleth documentation: RequestMapper

Forcing Reauthentication

You can require the user to reauthenticate at the IdP before getting an SP session by requesting forced reauthentication.

shibboleth2.xml - In the "SSO"" element, within the "Sessions" element, add the forceAuthn attribute and set it to "true".
Apache - Add ShibRequestSetting forceAuthn 1 in your httpd.conf or .htaccess file.
IIS - Add forceAuthn="true" in the "Host" element within "RequestMapper".

Domain Name Alias Configuration

If you have additional domain names pointing to an SP, that is integrated with the NetID Login Service, that can accept the SAML Authentication Response from the Shibboleth IDP, you will need to add the domain name as additional AssertionConsumerService endpoints in the SP Metadata

<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"/>

Once the Metadata has been updated please email help@login.wisc.edu with the Metadata attached and let us know the EntityID of the SP for which the Metadata to be updated.

Additionally we can also update the existing Metadata we have for your SP with the Alias you provide us

Unprotect Location Under a Protected Location

Apache

Here's an example of setting up a Shibboleth-authentication required directory https://sample.wisc.edu/protected and a subdirectory https://sample.wisc.edu/protected/unprotected with no authentication required in the Apache .conf file:

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

IIS

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

Lazy Sessions

Apache

AuthType shibboleth
ShibRequestSetting requireSession 0
Require shibboleth

IIS

Set requireSession="false" in the <RequestMapper> section for that application.

Integrating Shibboleth SP with Manifest

Note: This service is not available for Wisconsin Federation service providers.

This section outlines the different ways that application administrators can connect with their Manifest groups through the NetID Login Service without additional configuration required from IAM.

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

The SAML2 Entity ID is the unique identifier for your service provider which is located in the shibboleth2.xml configiuration file on your application's host. Common locations are found below:

Windows:

C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml

Linux:

/etc/shibboleth/shibboleth2.xml

Once you have located the shibboleth2.xml file, open it in your preferred editor and find the entityID attribute in the <ApplicationDefaults> tag. If you have specified an <ApplicationOverride> tag in your XML file, use the value located there instead.

Examples:

<ApplicationDefaults [...] id="myapp.wisc.edu" entityID="https://myapp.wisc.edu/shibboleth">

<ApplicationOverride [...] id="myapp.wisc.edu" entityID="https://myapp.wisc.edu/shibboleth">

Now that you have located your SAML2 Entity ID, copy it into your Manifest group(s) using the instructions outlined in Manifest - Manage SAML2 EntityIDs. Note that Entity IDs are case sensitive.

Configure Shibboleth for the "isMemberOf" Attribute

In order for your application to use the "isMemberOf" attribute, it must be part of your Shibboleth Service Provider's attribute map. If you have not configured your Service Provider to pull attributes from login.wisc.edu/metadata/attribute-map.xml, you must edit your attribute-map.xml file manually. This file should be located in the same folder as shibboleth2.xml. The following should be added to attribute-map.xml:

<Attribute name="urn:mace:dir:attribute-def:isMemberOf" id="isMemberOf"/>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="isMemberOf"/>

Authorization Using Manifest Groups (IIS)

Shibboleth2.xml Directives

Once you have configured Manifest and your Shibboleth Service Provider, you will be ready to utilize the "isMemberOf" attribute for authorization decisions. A typical means of doing this is via the <RequestMapper> tag in your shibboleth2.xml file. A basic example is provided below; if you would like additional assistance with authorization decisions, please contact manifest@doit.wisc.edu.

<RequestMapper type="Native">
   <RequestMap applicationId="default">
      <Host name="myapp.wisc.edu" applicationId="myapp.wisc.edu" authType="shibboleth" requireSession="true" redirectToSSL="443">
         <Path name="private" requireSession="true">
            <AccessControl>
               <Rule require="isMemberOf">uw:domain:myapp.wisc.edu:private_users</Rule>
            </AccessControl>
         </Path>
      </Host>
   </RequestMap>
</RequestMapper>

The example above restricts access to myapp.wisc.edu/private to members of the group uw:domain:myapp.wisc.edu:private_users (note that this is the Manifest Group ID Path).

Configuration File Directives

Alternate Apache 2.2 and below Configuration

Apache users can take advantage of the "require" directive to enforce group restrictions. This can be done in the Apache configuration. An example Apache config is provided below.

<Location "/myApp">
	AuthType shibboleth
	ShibRequestSetting requireSession 1
	ShibUseHeaders On
	ShibRequestSetting applicationID "myhost.wisc.edu/myApp"
	Require isMemberOf uw:domain:dept:myapp:mygroup
</Location>

Apache 2.4 Configuration

For Apache 2.4 and above the syntax to restrict access to a Manifest group changes: see below. This can be done in the Apache configuration. An example Apache config is provided below.

<Location "/myApp">
	AuthType shibboleth
	ShibRequestSetting requireSession 1
	ShibUseHeaders On
	ShibRequestSetting applicationID "myhost.wisc.edu/myApp"
	Require shib-attr isMemberOf uw:domain:dept:myapp:mygroup
</Location>

.htaccess Directives

.htaccess files provide a way to make configuration changes on a per-directory basis. A file, containing one or more configuration directives, is placed in a particular directory, and the directives apply to that directory, and all subdirectories thereof. Because of this, the <Location> directive is not used. An example is provided below

Apache 2.2 and below Directives


AuthType shibboleth
ShibRequestSetting requireSession 1
ShibUseHeaders On
ShibRequestSetting applicationID "myhost.wisc.edu/myApp"
require isMemberOf uw:domain:dept:myapp:mygroup

Apache 2.4 Directives


AuthType shibboleth
ShibRequestSetting requireSession 1
ShibUseHeaders On
ShibRequestSetting applicationID "myhost.wisc.edu/myApp"
require shib-attr isMemberOf uw:domain:dept:myapp:mygroup

Keywords:

netid login saml shibboleth attributes cookies sso oidc integration

Doc ID:

130404

Owned by:

Justin V. in Identity and Access Management

Created:

2023-08-16

Updated:

2026-02-16

Sites:

Identity and Access Management

3 0 Comment Suggest new doc

NetID Login Integration Overview

NetID Login Service - Getting Started with Single-Sign On

What is Single-Sign On?

Common terminology

OIDC and SAML - protocols for SSO

Madison and Universities of Wisconsin

Configure SSO with OIDC

Madison OIDC Scopes and Attributes

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

Configure SSO with SAML

SAML Attributes

Default Attribute Release for UW Madison

Default Attribute Release for Universities of Wisconsin

FERPA and Population Scope

Manifest and User Access

Shibboleth Installation and Configuration

Getting Started with Shibboleth

Installing Shibboleth Service Provider

Windows Server IIS

Installation

Verification

Result

Windows Server Apache

Installing Shibboleth

Installing Apache

RHEL or UBI 9 with Apache

Recommendations

Installation

Verification

Result

Ubuntu with Apache

Recommendations

Shibboleth Installation

Verification

Result

Configuring Shibboleth Service Provider

Windows Server IIS

Prerequisites

Requirements

Shibboleth Service Provider Configuration File - shibboleth2.xml

Example and Explanation of Shibboleth2.xml file

Download Metadata Signing Certificate

Windows Server Apache

Basic Configuration

Download Metadata Signing Certificate

UW-Madison and UW-Madison Federation (eg. PubCookie Replacement)

Wisconsin Federation (eg. Approved IAA Request)

Generate Shibboleth2.xml File

Automatic Shibboleth2.xml Generator

RHEL / UBI / CentOS

Prerequisites

Requirements

Shibboleth Service Provider Configuration File - shibboleth2.xml

Example and Explanation of Shibboleth2.xml file

Download Metadata Signing Certificate

Apache Configuration

Verification

Ubuntu

Prerequisites

Requirements

Shibboleth Service Provider Configuration File - shibboleth2.xml

Example and Explanation of Shibboleth2.xml file

Download Metadata Signing Certificate

Apache Configuration

Verification

Shibboleth Service Provider Activation

User Attributes from Identity Provider

UW-Madison NetID Login Identity Provider Information

Getting the attribute-map.xml

Shibboleth SP Configuration File (shibboleth2.xml)

No Single Logout

Logout of individual applications

Enable Shibboleth Protection for a Specific Path

httpd.conf

.htaccess

Secure Cookies

Force SSL on all Paths

Use cookieprops

Server Variables and Mapped Attributes

If you have PHP installed on your server you can use the following: