Child pages
  • Windows Identity Provider IdPv3
Skip to end of metadata
Go to start of metadata



Section 0: Preconfiguration

Complete the preparation required in Windows Preparation for Participants before you continue.

Disable IE "Enhanced Security Configuration"

If you will be using Internet Explorer on the VM, you should disable IE's Enhanced Security Configuration (ESC) which is turned on by default for the Administrator account. If ESC is enabled, it will be difficult to complete the course using IE, because it will interfere with the operation of most of the web sites we use throughout the curriculum.

  1. Open the Server Manager by going to Start > Server Manager (should be the top left box on the Start page)
  2. In the left pane, select "Local Server" (second from top)
  3. In the right pane, "Properties" section, there should be a line labeled "IE Enhanced Security Configuration" on the right side. Click the link labeled "On" (see image).

  4. Check the "Off" button in both places, to disable ESC for both administrators and regular users
  5. Click "OK"
  6. Restart IE

As an alternative, you may want to download a browser such as Firefox or Chrome, and use that instead of IE to complete the curriculum.

General Curriculum Notes

For convenience, the VMs include web shortcuts for downloading several software packages we will need for the class, as well as uploading metadata. You can find these links in the directory C:\ShibbTraining. There is also a shortcut to this directory on the Start page.

The values in .properties files are not trimmed.  Beware of white space, particularly at the end of lines, as it will generally cause things to explode. .properties files are not reloaded unless the webapp is restarted.

  • Read each task completely (to the end of the numbered step) prior to executing the commands. Often times examples are a bit further down.
  • Some tasks in which you edit configurations will have portions of the config you are editing "commented out." Be certain to remove these enclosing comment tags to allow the IdP to pick up the configuration. In situations like this, error messages may be accurate but misleading.

Outcomes:

  • A working Shibboleth Identity Provider (IdP) Service, capable of authenticating users and releasing specific attributes to specific service providers.
  • Familiarity with the IdP documentation available on the Shibboleth wiki (http://wiki.shibboleth.net)

Notes: This document is not meant to be a complete discussion on anything you might ever do with an IdP. There are many topics of potential interest that are left out of this document in an attempt to keep it more focused on getting a basic IdP up and running. This document is meant as a guide to help you get your IdP working and understand how to care for it. Please read authoritative Shibboleth IdP documentation linked to from this document.

Section 1: Install

1. Understand the model and the Big Picture
  • Objective:
    • Understand the basics about Shibboleth, how it integrates into a modern IT infrastructure, and what advantages it has over other SSO Systems.
  • Success Factors:
    • Able to explain the basic concepts of federated identity management
    • Able to explain the components of the Shibboleth IdP software
    • Able to explain how Shibboleth fits into the IT infrastructure
    • Able to explain what makes Shibboleth different from other SSO Systems
2. Plan/Think/Decide
  • Objective: Decide on the basic configuration and integration options for your new IdP.
  • Options to consider:
    • Authentication Type
      • LDAP
      • Kerberos
      • X.509
      • Active Directory can do either Kerberos or LDAP
    • Authentication integration
      • Native LDAP
        • Offers the best integration with the IdP
        • Supports forced re-authentication
        • Supports local single logout (SLO) and will eventually support global SLO
      • Java Authentication and Authorization Service (JAAS)
      • REMOTE_USER
      • External Authentication
      • Multi-Factor Authentication (MFA)
        • Allows for scripted relationships and conditions to be defined, combining multiple authentication factors in a single identity proofing event.
        • Very powerful tool
      • Duo Authentication
        • As close to plug-n-play as you'll get, but it leaves you all the hard process problems to solve.
    • What is your data/attribute store
      • LDAP / Active Directory
      • SQL
    • Do you have the needed service accounts
      • LDAP or AD service account for the attribute resolver
      • For LDAP or AD Authentication, an LDAP service account for LDAP authentication (can be same as above)
      • NOTE: It may be important to consider FERPA when creating your LDAP service account. If your LDAP service account has access to restricted information, you may need to consider the potential implications for FERPA when releasing attributes from your IdP.
    • SSL Certificate
      • You will want an SSL certificate for your user login page. We will use a dummy certificate for this course, but you will want a certificate from a commonly trusted root when you go to production.
      • This will need to be a cert trusted by your users' browsers (a commercial cert, most likely).
      • This cert will not be used by Shibboleth for anything (although some deployment scenarios will protect their SOAP handler with a commercial cert)
      • Jetty can use a variety of different credential stores, but it's most straightforward to use a Java keystore .jks
    • Uninstallation
      • Uninstallation of the IdP simply requires deleting the path to which it was installed, along with any support in the OS you've added that you would like to remove.
2a. Install Java


  • Objective:
    • Install the latest version of the Oracle Java Development Kit (JDK).
  • Tasks:
    • Browse to the directory C:\ShibbTraining (there's a shortcut to it on the Start page) and double-click on "Download Java".
    • Run the installer and accept all of the default options.
  • Resources:
  • Success Factors:
    • The latest Oracle Java JDK is installed at C:\Program Files\Java\jre1.8.0_121 (or similar)
3. Prepare to install the Shibboleth IdP software

4. Install Shibboleth

  • Objective:
    • Install the Shibboleth IdP software
  • Tasks:
    • Set JAVA_HOME for all users.

      • Right-click on the Start menu icon and select "System" (fourth option from the top)
      • On the left sidebar, click "Advanced system settings"
      • Click the "Environment Variables..." button
      • In the top section (User variables for Administrator), click "New..."
      • For variable name, enter JAVA_HOME
      • For variable value, enter the path where Java is installed (for example, C:\Program Files\Java\jre1.8.0_121confirm the version number, as it will likely differ from this example)
      • Click "OK" to accept and dismiss each of the 3 pop-up menus
    • Double-click on the Shibboleth MSI installer that you downloaded in step 4 (it's probably located in C:\Users\Administrator\Downloads). If an "Unknown Publisher" warning appears, click "Run" to continue.

    • Click "Next" to begin the installation.
    • Read through the end-user license agreement, check the box to accept the terms, and click "Next" to continue.

    • Accept the default installation folder (C:\Program Files (x86)\Shibboleth\IdP\) and check the box to install Jetty. Leave "Configure for Active Directory" unchecked. For DNS name and scope, enter the fully-qualified hostname for your IdP host (my.special.name which you chose while setting up your VM). This value should typically be the external host name that your users' browsers will display, because it's used to generate a number of configuration files that should match the web hosting environment, including any virtualization that may be present. Example screenshot:

      When finished, click "Next".
    • Click "Install" to begin the installation. Wait for the installer to complete, and then click "Finish".
  • Resources:
  • Success Factors:
    • The Shibboleth IdP software is now located at C:\Program Files (x86)\Shibboleth\IdP

    • Jetty is installed at C:\Program Files (x86)\Shibboleth\Jetty
    • The Shibboleth 3 IdP Daemon is running and visible in the list of Windows services (Start > Administrative Tools > Services). If you don't see it initially, try exiting and restarting the Services utility.
5. Prepare Jetty

The identity provider is written as a standard web application against the Servlet API 3.0 specification, and as such it runs in a servlet container.  Apache Tomcat 8.2, Jetty 9.2, and Jetty 9.3.1+ are supported by the Shibboleth Project.  We will use Jetty, because the MSI installer can install it automatically, and includes a jetty_base folder that contains much of the configuration of the web server that would be necessary. As of IdP version 3.2.1.1 (released June 23, 2016), the Windows Installer comes bundled with Jetty 9.3. Previous versions used Jetty 9.2.

Section 2: Configure

1. Understand the IdP's configuration files and options
  • Objective:
    • Understand the different configuration files and what's contained in each of them.
  • Configuration Files:
    • There are many different configuration files for the IdP, a design that was selected for clearer delineation between configuration files.  Configuration files for the IdP can be located in many different places, depending on what aspect of IdP behavior you might like to modify.
    • Primary configuration (C:\Program Files (x86)\Shibboleth\IdP\conf):
      • There are over 20 different major configuration files for the IdP documented in the official Wiki at https://wiki.shibboleth.net/confluence/display/IDP30/ConfigurationFileSummary. Although it can appear intimidating at the outset, most of the configuration changes you'll make on a day-to-day basis are limited to a small handful of these files.
      • Many of the configuration directives are intended for narrow or specific use cases. This class is focused specifically on the options we think will be most useful for you.
      • Each file is described below:
        • access-control.xml
          • This file controls access to administrative pages such as the stats page, resolver testing tool, service-reload endpoints, etc.
        • attribute-filter.xml
          • This is where you configure attribute release policies. The Shibboleth IdP has a very flexible rules engine. You can release (or block) attributes to a single SP, a list of SPs, or all SPs in a given federation. This is the file you will touch most often.
        • attribute-resolver.xml
          • This is where you configure how the IdP gets or builds attributes. This is perhaps the most powerful feature of the IdP software. The attribute resolver is very flexible, allowing you to retrieve attributes, both textual and binary (jpegPhoto, userCertificate, etc), in the conventional sense from either LDAP or SQL data sources, but also able to create attributes in a variety of interesting ways, ranging from the use of regular expressions to writing custom scripts. allowing you to do almost anything. There are three template attribute resolver files included in the distribution, mainly to avoid forcing LDAP or education-specific defaults into the main distribution. These variously pull from property files or can be directly configured.
        • audit.xml
          • This file controls how audit information is written to the audit logs.  You would edit this file if you're looking to add or remove information from Shibboleth's audit logs
        • authn\
          • A directory that allows for detailed configuration of many different styles of authentication and controls when any given flow is used. The configuration in this directory allows you to configure various authentication behavior, including MFA scripting.
        • cas-protocol.xml
          • This configures various features of the IdP's built-in support for the Central Authentication Service (CAS) protocol.  Support for CAS is new in IdPv3.
        • c14n\
          • c14n is short for "canonicalization", the process of mapping ambiguous objects on the wire to specifically determined objects within the IdP.  The c14n directory offers many different ways to map principal names.
        • credentials.xml
          • This file contains configuration related to your SAML keys and certificates.  You'll likely not need to touch this unless/until you need to perform a key-rollover.
        • errors.xml
          • In here you control how the IdP handles various errors.  This is useful if your users find themselves hitting a condition that results in a very bad experience.  You could, for instance, adjust that particular event to, instead of sending the user on to the service with a SAML Error, show a local page with a potentially more helpful error message.
        • global.xml
          • By default, this file is empty.  It is used to override default behavior of low-level components such as session or storage management.
        • idp.properties
          • This file is used to more easily make changes to the IdP's config without having to edit the other .xml files.  Look here before looking in other config files if what you're looking to do is generally affect a global setting.
        • intercept\
          • Intercept flows are used to modify the processing of flows.  Examples included in this directory are attribute consent, terms of use, and attribute release.
        • ldap.properties
          • This handy file is a central configuration area for all things LDAP.  
        • logback.xml
          • The file is where all of the logging activity of the IdP is configured. The default settings are usually fine, but you may want to make changes in this file if you need DEBUG logging for the LDAP Authentication module, if you need DEBUG logging on your authentication events, or if you want to be notified via email when the IdP logs a message with a level of ERROR.
        • metadata-providers.xml
          • Here is where you add sources of SAML metadata.  It is also where you configure how to validate SAML metadata.  For those who are familiar with the older IdP version 2, this information used to reside in the relying-party.xml.
        • relying-party.xml
          • This is where you control which profiles of SAML will be presented to which services & how the IdP will handle authentication for various services.  In here you'll control things like whether to sign / encrypt assertions, what the preferred authentication method is, and/or what to use for the SAML NameID
        • saml-nameid.properties
          • Java properties file for controlling SAML NameID generation & consumption.
        • saml-nameid.xml
          • Controls generation of SAML NameIDs.  This provides more fine-grained control over what is found in the saml-nameid.properties configuration file
        • services.properties
          • The IdP will automatically reload many of its configuration files allowing you to make changes to the configuration without causing an outage.  This file controls many aspects of this reloading mechanism.
        • services.xml
          • This file controls how various sub-systems within the IdP load their configuration.  For instance, you could configure the IdP to pull its relying-party.xml or attribute-resolver/filter.xml files from a central web-server or subversion repository rather than use the local copy in this directory.
        • session-manager.xml
          • In here you can configure how the IdP handles user sessions.
    • Webapp configuration (views, edit-webapp, messages):
      • The web interface that the IdP displays to users in most conditions is primarily expressed using Velocity templates. These velocity templates are in turn are able to pull from a variety of files and classes which themselves define properties for macro expansion. web.xml is the reference authority, but in most cases, the code first looks for a Velocity template in /views/foo.vm and falls back to foo.jsp in the webapp (e.g. idp.war or the expanded edition) if /views/foo.vm doesn't exist. It is recommended that Velocity always be used, but know that jsp remains an option.
      • Some sites may choose to use externalized authentication mechanisms, in which case most of the login pages will not be visible.  However, some of the error pages may still be visible, so please be sure to skin it anyway.
      • If response will need the client to have access to a file, whether rendered by Velocity or not, that file must be included in either (highly preferably, to expedite upgrades) edit-webapp in the IdP's directory path created after installation, or in the webapp directory in the build. Regardless of which approach is taken, the WAR file encompassing the IdP must be rebuilt using $INSTALL_HOME\bin\build.bat.
    • Flows configuration: (\flows)
      • The IdP processes web requests using Spring Web Flow.  These flows are defined primarily in the system/flows directory, which is not intended for direct user modification.  However, there is another flows directory in the top level of $IDP_HOME which offers the ability to turn on and off some of the various processing stages that may be involved in any given request.  In general, you won't need to modify this.
    • IdP metadata configuration: (\metadata)
      • This is metadata that the IdP provides to SPs in order to identify itself.  The IdP operator may be required to maintain a metadata file that describes the functionality of the IdP.  This should include any web virtualizations, special keys, specific entityIDs, endpoint locations, URLs, and so forth that may be useful in delivering an optimal federating experience.  Some federations provide this service for IdPs, but some IdPs manage their own metadata files as well.  This is most appropriately done using the template in C:\Program Files (x86)\Shibboleth\IdP\metadata\idp-metadata.xml, and the IdP will host it by default at https://<my.special.name>/idp/shibboleth .
    • Credential management (\credentials):
      • Most deployers will be able to manage their SAML keys using idp.properties, but Shibboleth includes a directory that can be used for storage of credentials.  The installer will generate credentials if it finds no existing configuration. The default includes a large number of credentials, each one for a specific task, to limit the impact of compromise of one keypair.  You may want to add some certificates to this directory, specifically user-facing web certificates that can be used by Jetty for presentation of content over TLS. From a SAML perspective, you will likely only be interested in the signing key.
  • Resources
  • Success Factors:
    • Understanding of the IdP's configuration files.
2. Register your IdP with the classroom federation for your training session.

  • Objective:
    • Make your IdP's metadata trusted by the centralized metadata service for this training session so that you can login to the classroom SP using your new IdP.
  • Tasks:
    • Your IdP's metadata can be found in the IdP's installation directory in the \metadata folder as idp-metadata.xml (by default, C:\Program Files (x86)\Shibboleth\IdP\metadata\idp-metadata.xml). It can also be downloaded from https://<MySpecialName>/idp/shibboleth
    • Upload a copy of your IdP's metadata at the classroom metadata aggregator page: https://sp.training.incommon.org/mdupload/ (for convenience, we've included a link to this page in C:\ShibbTrain)
    • The upload page requires a password.  The classroom instructors will communicate the top-secret upload password to you.
    • Classroom metadata is built approximately every 2 minutes.  This is designed as a special test for the impatient, so please wait a couple of minutes before trying to test your new IdP.
  • Success Factors:
    • You can check to see whether your IdP is recognized by the test SP by accessing https://sp.training.incommon.org/secure and using the ugly discovery interface. Don't try to login yet: your IdP doesn't trust the classroom SP yet, and it will say that by indicating that there was no valid signature on the inbound message and security requirements thus fail. This prevents any attribute or authentication data from leaking to unidentified SPs.
    • Your IdP's metadata is visible in the training session metadata (after a few moments).
3. Define/load a source of SAML metadata

  • Objective:
    • Configure at least one source of SAML metadata for your IdP.
  • Tasks:
    • Configure the following MetadataProvider sub-element inside the main ChainingMetadataProvider element in your C:\Program Files (x86)\Shibboleth\IdP\conf\metadata-providers.xml config file. This might be placed next to the commented-out HTTPMetadata example, but beware the <!-- --> comment structure. You can put it right before the closing </MetadataProvider> tag for the ChainingMetadataProvider. If you want to know why this is needed, ask an instructor.

      <!-- Shibboleth Training classroom metadata -->
      <MetadataProvider id="ShibbTrainMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
      metadataURL="http://md.training.incommon.org/downloads/ShibTrain1-metadata.xml"
      backingFile="C:\Program Files (x86)\Shibboleth\IdP\metadata\ShibTrain1-metadata.xml"/>
      
    • When you are finished, restart the "Shibboleth 3 IdP Daemon" service. The IdP should download the classroom metadata and cache a copy in the metadata directory (as specified by the backingFile setting above). This directory does nothing special, but it's a convenient place for you to store cached copies. After restarting, check for the presence of this file to confirm that the IdP restarted successfully and downloaded the metadata (it may take a minute or two to show up, depending on VM and network latency).
  • Resources:
  • Note:
    • For all non-test installations, it is important to require both the maxValidityInterval filter and Signature Validation filter on the metadata sources that you configure. These both help to improve the integrity of the federation metadata and make the environment more secure.  See the default IdP configuration files or the above URL for examples.
  • Success Factors:
    • Your IdP has retrieved and loaded SAML metadata from the configured source.
    • Check the C:\Program Files (x86)\Shibboleth\IdP\metadata directory to see if a cached copy of the metadata shows up as ShibTrain1-metadata.xml.
4. Configure User Authentication

  • Objective:
    • Configure your IdP to authenticate your users using the Password authentication mechanism via the MFA framework. We recommend always using this framework, even if your initial use cases are nominal, because it will allow you to build in the future.
    • The Password mechanism is enabled out of the box and usable with multiple protocols, including LDAP and Kerberos, but we will use LDAP for this class.
  • Tasks:
    • Change C:\Program Files (x86)\Shibboleth\IdP\conf\idp.properties.
      • Set idp.authn.flows = MFA
    • Configure the ldap.properties file in your Shibboleth install.
      • Edit C:\Program Files (x86)\Shibboleth\IdP\conf\ldap.properties
      • Uncomment idp.authn.LDAP.authenticator and change the value to bindSearchAuthenticator
      • The training LDAP server is found at idp.training.incommon.org on port 389 with no TLS or port 636 with TLS. (idp.authn.LDAP.ldapURL = ldap://idp.training.incommon.org)
        • be sure to uncommentidp.authn.LDAP.useStartTLS and set it to false (idp.authn.LDAP.useStartTLS = false)
      • Configure your IdP to search for the user using a idp.authn.LDAP.bindDn of uid=IdPServiceAcct,ou=people,dc=example,dc=org and a idp.authn.LDAP.bindDNCredential of password.
      • For production-grade scenarios, it's important to use LDAPS or startTLS, so that passwords do not traverse your network in clear text.  We will use plaintext for this class.
        • Make idp.authn.ldap.trustCertificates point to a real file.  It doesn't matter what is in the file.
    • Add a basic MFA script that just handles one factor using Password right now. It consists of a map of login flows with a pointer to logic governing transitions and the logic itself in Javascript.. Edit the file C:\Program Files (x86)\Shibboleth\IdP\conf\authn\mfa-authn-config.xml, delete all existing content, and replace with the following:

      <?xml version="1.0" encoding="UTF-8"?>
      <beans xmlns="http://www.springframework.org/schema/beans"
             xmlns:context="http://www.springframework.org/schema/context"
             xmlns:util="http://www.springframework.org/schema/util"
             xmlns:p="http://www.springframework.org/schema/p"
             xmlns:c="http://www.springframework.org/schema/c"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.springframework.org/schema/beans 
      http://www.springframework.org/schema/beans/spring-beans.xsd
      http://www.springframework.org/schema/context 
      http://www.springframework.org/schema/context/spring-context.xsd
      http://www.springframework.org/schema/util 
      http://www.springframework.org/schema/util/spring-util.xsd"
             default-init-method="initialize"
             default-destroy-method="destroy">
       
       
          <util:map id="shibboleth.authn.MFA.TransitionMap">
              <!-- First rule runs the Password login flow. -->
              <entry key="">
                  <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Password" />
              </entry>
       
              <!--
              Second rule runs a function, if Password succeeds, to determine whether an additional factor is required.
              -->
              <entry key="authn/Password">
                  <bean parent="shibboleth.authn.MFA.Transition" p:nextFlowStrategy-ref="checkSecondFactor" />
              </entry>
       
              <!-- An implicit final rule will return whatever the final flow returns. -->
       
          </util:map>
       
       
          <!-- Script to check if Duo is required.  Duo configuration parameters are in /authn/conf/duo.properties. -->
          <bean id="checkSecondFactor" parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript">
              <constructor-arg>
                  <value>
                  <![CDATA[
                      nextFlow = "authn/Duo";
                      authCtx = input.getSubcontext("net.shibboleth.idp.authn.context.AuthenticationContext");
                      mfaCtx = authCtx.getSubcontext("net.shibboleth.idp.authn.context.MultiFactorAuthenticationContext");
                         if (mfaCtx.isAcceptable()) {
                                nextFlow=null;      
                            }
                      nextFlow;  // pass control to second factor or end with the first
                  ]]>
                  </value>
              </constructor-arg>
          </bean>
      </beans>
    • Restart the "Shibboleth 3 IdP Daemon" service.
  • Resources:
  • Test:

  • Success Factors:
    • IdP is able to successfully authenticate users
5. Configure User Attributes/Attribute Resolver
  • Objective:
    • Familiarize yourself with the IdP's attribute resolver.
  • Tasks:
    • Copy the attribute-resolver-full.xml file to attribute-resolver.xml  

      cd 'C:\Program Files (x86)\Shibboleth\IdP\conf'
      copy attribute-resolver-full.xml attribute-resolver.xml

      Note: OK to overwrite the original version of attribute-resolver.xml

    • Uncomment the attribute definitions for CoreinetOrgPerson, and eduPerson in the IdP's conf/attribute-resolver.xml file.
    • Uncomment and configure the resolver:DataConnector called myLDAP (towards the bottom of the file) to connect to the LDAP directory and retrieve information for the authenticated user.  By default, this DataConnector will use the LDAP properties you set in the ldap.properties file. Comment out the <StartTLSTrustCredential> section. As the classroom LDAP server does not use StartTLS, this section is not needed; and will cause an error on startup if the associated certificate is not present in the 'credentials' directory.
    • This is also the file where you would define any custom or campus-specific attributes that you intend to use with Shibboleth. Of particular note here: be careful to not create arbitrary names for your attributes. They must be in a namespace you control. There are examples in the file and on the Shibboleth wiki (see here: https://wiki.shibboleth.net/confluence/display/CONCEPT/SAMLAttributeNaming).
    • If you're familiar with Shibboleth >3.3, you'll notice no more need to use many XML namespaces. The old way will work too. You may need to rename your Script attribute definitions to leverage the new format. It's worth it.
    • Restart the Shibboleth 3 IdP Daemon service when you are done.
  • Resources:
  • Success Factors:
    • Your IdP is able to retrieve basic user attributes. It will not release any attributes to any SP yet, but you can see the IdP gathering attributes if you adjust your logging levels in logback.xml to DEBUG:

      <!-- Logs IdP, but not OpenSAML, messages -->
      <logger name="net.shibboleth.idp" level="DEBUG"/>

      Changes to logging will be automagically reloaded every 5 minutes, so be careful before changing logging on production machines. This can be configured in conf/services.properties, or you can force a reload, or you can just restart the Shibboleth IdP service.

      After setting this, log in again and check C:\Program Files (x86)\Shibboleth\IdP\logs\idp-process.log. You should see numerous logs related to attribute resolution. If you do a search for during resolution, you'll see the intermediate results.

6. Configure Attribute Release Policies

  • Objective:
    • Successfully create and test an attribute release policy.
  • Tasks:
    • Create a new rule to release eduPersonPrincipalName, displayName, and email to the classroom's test SP, by adding this to your attribute-filter.xml inside the main <AttributeFilterPolicyGroup> element:

      <AttributeFilterPolicy id="releaseForClassroomSP" >
        <PolicyRequirementRule xsi:type="Requester" value="https://sp.training.incommon.org/shibboleth" />
        <AttributeRule attributeID="eduPersonPrincipalName">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="displayName">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="mail">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
         <AttributeRule attributeID="surname">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="givenName">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="eduPersonAffiliation">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="uid">
          <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
      </AttributeFilterPolicy>
      
    • Each <AttributeFilterPolicy> element that you create should have a locally unique ID.
      • These IDs must be unique, should be set, and are never exposed to the world. They're useful so you can track which policy or policies caused which behavior.
    • Filter policies are all evaluated together. All the rules that apply to a given SP (either through direct reference or by inclusion in a group or regex) are processed. The specific processing rules are discussed later on.
    • You can also block/deny an attribute to a given SP which would have been released under a different policy.  You could create release policies for a specific SP, a list of SPs, or all SPs in a given federation.
    • Remember to restart the Shibboleth Identity Provider Service after making edits.
  • Test:

    • https://sp.training.incommon.org/secure(this time, it should display some user attributes after logging in)
    • You should be able to authenticate as staff1/password, student1/password, staff2/password, or student2/password.

This time, you'll be prompted with an interstitial screen asking for your consent to the release of attributes to this service.  It didn't appear for prior logins because we were not releasing any attributes.  If you want to turn off consent, remove the p:postAuthenticationFlows attribute from the SAML2SSO bean in relying-party.xml.

Section 3: Advanced Tasks

For individuals who complete the basic curriculum quickly and want to learn more about the IdP, here are some suggestions.

1. Customize the IdP's Login Page

The web interface is invoked by web.xml, bundled in the main idp.war file or webapps\idp directory, and most content is supplied through Apache Velocity templates in C:\Program Files (x86)\Shibboleth\IdP\views. These views can in turn rely on a wide variety of data.  Each view includes comments that enumerate some basic information that should be available.

For "relatively" short snippets of anything or anything that needs localization, HTML included, using Spring will usually be the better choice. Messages displayed on these templates, such as errors, are defined as name value pairs in C:\Program Files (x86)\Shibboleth\idp\messages\messages.properties, cached for 300 seconds by default. For larger stanzas or ones that require dynamism, Velocity Template Language (VTL) has both unparsed (#include) and parsed (#parse) includes.

All sites should customize error pages and messages.  If you will be using the IdP's native support for Kerberos- or LDAP-based authentication, then login.vm is the actual webpage presented. #springMessageText will preferentially use the message referenced, but default to the string if the message is not defined. HTML may be included directly in messages, and internationalization is handled.

Content can be supplied through many mechanisms. You can just put a foo.vm in the /views directory with the distributed templates, and refer to it from other templates with a simple relative path, e.g. #parse("voo.vm"). To add additional web resources to pages hosted by the IdP, such as graphics, CSS files, or JavaScript files, consider your deployment methodology to decide how and where to store these files.

  1. If you're following a "cattle not pets" deployment model in which everything gets rolled into a disposable VM or container, you might prefer to keep everything related to the IdP self-contained.  If so, consider placing additional resources into the /opt/shibboleth-idp/edit-webapp directory.  Anything that is found both in the webapp distribution and in edit-webapp will be overwritten with the version in edit-webapp, such as web.xml.  Explicitly deleting files is generally unnecessary, but the build process will not flush files that once appeared in edit-webapp.  Then, rebuild the idp.war file or redeploy the changes to your webapps folder, which will typically happen anyway as part of a build process that creates the final artifact to be deployed.  You can trigger the creation of a new .war by running C:\Program Files (x86)\Shibboleth\IdP\bin\build.bat.
  2. If your servers are intended to exist indefinitely, then it can often make more sense to place static content outside of the IdP's webapp, but available to the servlet container.  This allows you to update static content relatively easily, without touching the IdP or rebuilding it.  Consider using a second webapp, perhaps ROOT, and storing static content there.

The distribution change over time, but the developers endeavor to maintain forward compatibility throughout major releases, such as IdP 3.x. Changes typically only add new features, such as incorporating user interface elements from metadata, but rarely, vulnerabilities such as XSS attacks may be fixed. Major changes that deployers should or must watch for will be in the release notes. Changes to views or files will be adopted in real-time without a restart of the IdP, while changes to messages take effect when Spring reloads configuration.

Pro Tip

Place additional web resources in the edit-webapp directory, not the webapp directory. The webapp directory is replaced upon every upgrade and is not a safe location for modification. Expanding the .war into a webapp directory for runtime is not recommended, primarily due to unpredictable caching behavior across servlet containers.

If you are uncomfortable using Velocity, the code will, by convention, check to see if there is a view for a particular page in the views directory, such as login.vm. If that file doesn't exist, it will fall back to looking for a JSP page in the web environment, such as \WEB-INF\login.jsp, which must be built into idp.war. If neither exists, a 404 error will be rendered.

Please use the Shibboleth name and logo sparingly.  There is a reason it nowhere on the default templates.  Your users write to the project often.  Sometimes, it writes back.

2. IdP-Initiated SSO

Normal federated identity transactions begin with the user accessing the SP, and the SP then issues a SAML 2.0 AuthnRequest for the user to deliver to the IdP. Authentication occurs, an assertion is generated, and the user is launched back to the SP in a redirect.

Many commercial providers are unable or unwilling to issue these AuthnRequests. Furthermore, initiating the federated identity transaction at the IdP eliminates the need for discovery. Thus, in a variety of situations, it's desirable to start the federated identity transaction with the authentication of the user and issuance of the assertion, bypassing the use of an AuthnRequest.

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPUnsolicitedSSO (no 3.x page equivalent yet exists, and this didn't change, so never fear)

Try creating a webpage that will log you into the training SP, which has the entityID of https://sp.training.incommon.org/shibboleth. The invocation URL will look like:

https://my.special.host/idp/profile/SAML2/Unsolicited/SSO?providerId=https://sp.training.incommon.org/shibboleth

An SP might want you to perform authorization at the IdP. Occasionally. Please see the Authorization discussion topic.

3. Attribute Release to Another SP

We only have one SP for you to release attributes to. However, there's a general use SP that you can also use at TestShib.

http://www.testshib.org

Try registering your IdP with TestShib. After registering your IdP, you just need to load the TestShib SP's metadata, and set up attribute release. Go here to try it once you're done:

https://sp.testshib.org/

This is a good example of trivial onboarding.

Attribute release based on entity attributes

You can configure the IdP to release attributes based on information in metadata (so-called "entity attributes").  This can greatly simplify the onboarding process as attributes would automatically be released to new SPs with configured entity attributes in their metadata without the IdP operator having to configure a specific attribute release rule for these new SPs.

For information on how to configure this in the IdP, see this page: https://wiki.shibboleth.net/confluence/display/IDP30/AttributeRuleConfiguration

InCommon's most popular entity attribute at the moment is the Research and Scholarship entity attribute.

4. Fancy Attribute Filter Policies

Our simple attribute release rule sends a lot of attributes to a single provider. Try creating a rule that will release EPPN (eduPersonPrincipalName) when affiliation is staff, but not for an affiliation of student. You might start from the examples in the following Wiki page, or the main IdPv3 Wiki space.

https://wiki.shibboleth.net/confluence/display/IDP30/AttributeFilterPolicyConfiguration

https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttributeFilterExamples (no 3.x page equivalent yet exists, but the configuration basically didn't change, so never fear)

Given the power of the vocabulary, attribute filter policies are not always evaluated as you expect. Depending on your expectations, this may or may not have served as an example(SC-197). Always check that all rules you define behave as you intend them to behave before using them with real data.

https://issues.shibboleth.net/jira/browse/SC-197

5. Scripted Attributes

Script attribute definitions give you the capability to craft attributes using almost any means imaginable using the attribute resolver, typically configured in attribute-resolver.xml.

https://wiki.shibboleth.net/confluence/display/IDP30/ScriptedAttributeDefinition

They are executed using the Nashorn engine bundled with most Java 8, which  replaced the Rhino engine in Java 7.  The engine is typically used to parse ECMAScript/JavaScript for basic operations, but it's capable of far more when needed.  In general, it's good to push any attribute consolidation as far upstream in your identity management system as possible, so it's good to avoid simply habitually using these powerful tools.  Here are some example scripts.  You can try using them or writing your own.

This first script converts a richly valued affiliation set to just staff or student for a specific service provider that needs the smaller set.

 <Script><![CDATA[
 
		// Convert a richly valued affiliation set to a monochromic set

        dualUserClass = new BasicAttribute("dualUserClass");


        staff = false;
        student = false;


        if(eduPersonAffiliation.getValues().contains("staff") ||
        eduPersonAffiliation.getValues().contains("faculty") ||
        eduPersonAffiliation.getValues().contains("academic") ||
        eduPersonAffiliation.getValues().contains("emeritus") ||
        eduPersonAffiliation.getValues().contains("hospital") ||
        eduPersonAffiliation.getValues().contains("postdoc") ||
        eduPersonAffiliation.getValues().contains("affiliate") ||
        eduPersonAffiliation.getValues().contains("medical_associate")){
                staff = true;
        }


        if(eduPersonAffiliation.getValues().contains("student") ||
        eduPersonAffiliation.getValues().contains("new student") ||
        eduPersonAffiliation.getValues().contains("graham_student")) {
                student = true;
        }


        //is the person both?  Then they're a staff
        if(staff && student){
                dualUserClass.getValues().add("staff");
        }
        else if(staff){
                dualUserClass.getValues().add("staff");
        }
        else if(student){
                dualUserClass.getValues().add("student");
        }
        else {
                //do nothing
        }


        ]]>
        </Script>

This script sets the UID in any given transaction.  If the principal is a person, this is the username of the person's primary account.  If the principal is an account, it's the account's username.

        <Script>
             <![CDATA[

                uid = new BasicAttribute("uid");

                if (umbcPrimaryAccountUid.getValues().size() > 0)
                    uid.getValues().add(umbcPrimaryAccountUid.getValues().get(0));
                else if (accountUsername.getValues().size() > 0)
                    uid.getValues().add(accountUsername.getValues().get(0));
            ]]>
        </Script>
6. Deliberate Failure

Debugging failing federated identity transactions is difficult because you only have access to half of the logs and a fraction of the configuration. In this controlled environment, we encourage you to deliberately screw up some likely parts of your configuration (forgetting to add metadata, forgetting to do attribute release, using the wrong certificate, skewing your clock) to see what failure looks like in each common case. The trainers are available to suggest more ways to fail, and to help you understand the debugging process involved with each failure situation that you can create.

Here is a Wiki article on error handling.

https://wiki.shibboleth.net/confluence/display/IDP30/ErrorHandlingConfiguration

In the real world, excellent communication between you and the SP will be necessary to rapidly diagnose and remedy any issues. Phone calls are helpful.

Section 4: Okay, so what now?

We're glad you asked: you can pause here until today's closing discussion. When you're ready, click on the link below to view the discussion topics. The discussion topics are not dependent on any particular operating system; as such, everything there applies equally to Windows and Linux-based IdP installations. The only exception is the section on upgrading. When upgrading, Windows installations will typically make use of the packaged MSI installer, while Linux installations must upgrade manually via an installer script. We'll make note of this difference during the closing discussion.

Discussion Topics