Welcome Guest / Please Login

Metadata & WAYF

Multiple Federations

The Federation management interface for the University of North Carolina Identity Federation has the ability to run multiple federations.  For example, it can run a system-wide federation for both production and development (two federations).  Furthermore, it can run intra-campus federations as campuses choose to utilize SAML 2 for its single sign on needs.

Current Federations

UNC-GA IDP Metadata

WAYF Documentation

As indicated above, this application can manage multiple federations each of which require at least one WAYF.  Therefore, we have written a special WAYF application to handle this functionality.  Specifically, this WAY be seamlessly integrated into an application via an <iframe>, it provides a wide array of customization with respect to the Identity Providers and how they are displayed, and it enables for federated logout.  The following sections outline the parameters for which one can pass into the WAYF listed above to achieve the desired functionality:

How to Call the WAYF

The WAYF (also known as the discovery service) must be invoked by the Shibboleth Middleware.  Assuming you have the SP  installed and configured on an apache server, the following general steps will enable you to invoke the WAYF:

  1. Configure a directory (or file) within your webserver to be controlled by the Shibboleth Service Provider.
    <Location /secure>
         AuthType shibboleth
         ShibRequireSession On
         require valid-user 
    </Location> 
  2. Next, you must configure the Shibboleth Discovery Service to point the correct WAYF.
    1. Edit the Shibboleth configuration file (/etc/shibboleth/shibboleth2.xml).
    2.  Define the discovery service, which will resemble something like:
      <SessionInitiator type="Chaining" Location="/DS" id="DS" relayState="cookie">
           <SessionInitiator type="SAML2" defaultACSIndex="1" template="/etc/shibboleth/bindingTemplate.html"/>
           <SessionInitiator type="Shib1" defaultACSIndex="5"/>
           <SessionInitiator type="SAMLDS" URL="https://federation.northcarolina.edu/wayf/index.php?fed=FED_SHIB_UNC_PROD"/>
      </SessionInitiator>
    3. Restart the Shibboleth daemon (service shibd restart).
  3. When you want to authenticate using Shibboleth, then you must point the user to this secure file.  This can be done using a standard web browser URL redirection, or it can be done within an iframe.  For example:
    <iframe src="/secure/index.php" width="100%" height="800">
         No Iframe, please click here ...
    </iframe>

Following these steps will enable you to seamlessly integrate the WAYF into your application.

Content Customization

&fed - This is the code name of the federation that determines which set of federation metatdata the WAYF application will query when displaying the results.  This option enables the application to customize which set of Identity Providers from which its users will be able to select.  The current valid values are:
  • FED_SHIB_UNC_PROD - The production UNC system federation
  • FED_SHIB_UNC_DEV - The development UNC system federation
&wayf - (Optional) Another parameter that will further enable an application service provider to provide a subset of identity from which its users are allowed to select.  When used properly, this parameter will ensure users are only presented with valid options.  Currently, no valid options exist, but these codes can be created from the administrators section of this website.

&show_name - A parameter to turn on and off the official name of the selected federation from the actual display on the screen.
  • Y - Print the official federation name on the screen.
  • N - Hide the name from the user (default)
&body_id - The value of <body id=""> in the generated page.  This is helpful to apply different CSS styles.
  • home - The default value
  • truncated  - Minimizes the layout of the WAYF to fit in a smaller screen size and removes some formatting.

Visual Customization

&version - This parameter determines who the identity providers will be listed to the user.  The valid values are:
&css_url - If you wish to override the default look and feel of the WAYF using a customized CSS file, then you may simply pass in the fully qualified URL to your custom file.  The WAYF will detect this inclusion and ensure this file is also called when rendering the page.

Federated Single Logout (SLO)

While defined in the SAML 2.0 specification, Shibboleth currently does NOT implement federated single logout (SLO).  However, this is major security concern for the University of North Carolina.  The user semantically expects clicking a logout link will actually log them out of the system.  Without federated SLO, this assumption is violated as the user could still be logged into other applications or worse his/her identity provider.

To ensure security and privacy for its  users, the University of North Carolina has implemented the following scheme to successfully implement federated SLO across all applications belonging to the UNC Federation.

  1. WAYF Tracking - Each time a user tries to access an SP/IDP combination via the federation WAYF (which should happen 100% of the time), the WAYF will track the services for which this user is accessing.  This tracking will enable the WAYF to ensure the user is successfully logged out of each application when the time arises.
  2. IDP Logout - Each identity provider implements a logout page and releases a corresponding attribute URL to each service provider. (example: HTTP_SHIB_LOGOUTURL = https://idp.northcarolina.edu/idp/logout.jsp).  This special logout page will:
    1. Invalidate the Session - This will effectively log the user out of the identity provider.
    2. Logout from the Federation - This is done by redirecting to the WAYF logout page (https://federation.northcarolina.edu/wayf/logout.php).
  3. Federation Logout - Since the federation WAYF knows the services being accessed by the user (from step #1), it will sequentially list each one of these services and call the corresponding logout URL.  This logout URL is specified in the administrative section of this  site during the initial creation of the service provider.
  4. Service Provider Logout - Each service must provide a URL that will log the user out of the application and present them with a short, concise completed message.  We recommend the following HTML be returned on completion of this function:
    [Destory the session in whatever programming language
    you use]
    <html>
         <head>
              <style type="text/css">
                 body{
                   margin:0px; color: red;
                 }
              </style>
         </head>
         <body>
              Done.
         </body>
    </html>

Implementing these simple steps will ensure users are fully logged out of all applications when they attempt to log out of any application.