Enabling Single Sign-on (SSO) Authentication on www.unc.edu

Information Technology Services (ITS) has enabled the University’s single sign-on (SSO) functionality on the www.unc.edu servers.  This allows content owners to enable access controls for their web pages based on Onyen authentication.  This document will outline the basic steps for enabling SSO on web content hosted on www.unc.edu. 

Requirements

  • Your web site/web pages are hosted on www.unc.edu
  • Your web site/web pages are configured to support SSL

Notes

  • In this context, www.unc.edu is the infrastructure commonly referred to as the www cluster and serves content from AFS space.  It does NOT include the ITS Content Management System (currently WordPress) infrastructure.
  • The information contained within this document applies only to URLs in the www.unc.edu and its2.unc.edu domains.
  • If your website has a different domain name but resides on this infrastructure, you’ll need to submit a ticket to the ITS Middleware Services group to get SSO enabled for your domain before these steps will work for you.

.htaccess File

SSO authentication and access controls can be enabled for your web site/web pages using a .htaccess file.  Users can add directives to this file to handle things like page redirects, error pages, and adding authorization for content in the same directory and its subdirectories.  Full details of .htaccess functionality can be found at http://httpd.apache.org/docs/current/howto/htaccess.html, but some features may not be available on the www.unc.edu web servers.

Bare Minimum configuration

The following text is an example of the minimum configuration needed to enable SSO functionality to your web site. It provides authentication, but no authorization. That is, it restricts access to the containing directory’s content to any valid Onyen and/or UNC Guest ID. Add the following text to a file named .htaccess in the directory you want to protect.

<If "req_novary('X-SSL') == 'decrypted=true'">
   AuthType shibboleth
   ShibRequireSession On
   Require shib-user
</If>
<Else>
   RewriteEngine On
   RewriteBase /
   RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</Else>
 

Alternative:

AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
Require shibboleth

 

Limiting access to certain groups of people

If you need to restrict access to your content to certain groups or populations, this can be achieved by using an affiliation match. In the following example, the “Require shib-attr” line contains the change required to limit access to persons with the ‘staff’ role.

 

<If "req_novary('X-SSL') == 'decrypted=true'">
   AuthType shibboleth
   ShibRequireSession On
   Require shib-attr affiliation ~ ^(staff@unc.edu)
</If>
<Else>
   RewriteEngine On
   RewriteBase /
   RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</Else>

 

Alternative:

AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
Require shib-attr affiliation ~ ^(staff@unc.edu)

 

Other examples of affiliations include “student”, “staff”, “employee”, etc. This is not an exhaustive list of possibilities for group restrictions, but are the common ones.  There are other attributes as well. Some of them are: “affiliation” (member, staff, employee, etc), “isMemberOf” (based on ldap groups), “uid” (ONYEN).

Here’s an example of using the “isMemberOf” attribute:

<If "req_novary('X-SSL') == 'decrypted=true'">
   AuthType shibboleth
   ShibRequireSession On
   Require shib-attr isMemberOf ~ ^(unc:org:3103:employee)
</If>
<Else>
   RewriteEngine On
   RewriteBase /
   RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</Else>

 

Alternative:

AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
Require shib-attr isMemberOf ~ ^(unc:org:3103:employee)

 

If you have specific requirements, contact the Identity Management and/or Security group(s) to discuss those needs.

Logout

The main draw of single sign-on is to be able to sign in once and access many resources without having to sign in again.  However, logout in this environment is very complex and difficult to implement correctly.  There are several levels in an application stack where user session data is stored, and each of them needs to be invalidated in order to guarantee that a user is completely logged out.  Also, since logout is user-initiated, there is no certainty that logout will even be performed.  The only sure way to completely logout is to close all browser windows.

If you do wish to implement sign-out functionality for your application, here is what must happen.  Keep in mind that this terminates login for your application, but it does not affect sessions for other SSO enabled applications that a user may have logged into.

  1. Invalidate the application session, if one exists.

  2. Invalidate the Service Provider Session.

  3. Invalidate the global Sign-On Session.

Step 1 will require programming hooks within your application.  You will need to provide a “logout” button that a user can click on.  It will call a URL in your application that invalidates the user’s session. It must then redirect the user to the Service Provider so that Shibboleth can initiate its logout.  Please use the following URL to do this:

Shibboleth Logout URLhttps://<domain>/Shibboleth.sso/Logout?return=https://sso.unc.edu/idp/logout.jsp (E.g.: https://www.unc.edu/Shibboleth.sso/Logout?return=https://sso.unc.edu/idp/logout.jsp)

This will complete step 2 and then redirect the browser to the global logout page. The global session will be invalidated if the user selects ‘YES’ at the prompt.  In this case Step 3 will be completed.

Testing Shibboleth

While there are a number of issues that may arise with shibboleth, here are some steps for logging in to and out of a site as well as how to check to see if you have a valid session and attributes.

  • Log into the “site” – https://<domain>/Shibboleth.sso/Login  (e.g.: https://www.unc.edu/Shibboleth.sso/Login)
  • Check for attributes – https://<domain>/Shibboleth.sso/Session  (E.g.:https://www.unc.edu/Shibboleth.sso/Session)
  • Log out of the “site” – https://<domain>/Shibboleth.sso/Logout  (E.g.: https://www.unc.edu/Shibboleth.sso/Logout)

Additional Help

If you need further assistance with implementing SSO on your website, submit a Remedy ticket to the ITS-MIDDLEWARE group.

Additional info