Internet2 is investigating a security incident involving a compromise to a confluence server that affected https://spaces.at.internet2.edu on April 10, 2019, which was successfully mitigated on April 12, 2019. If you did not receive an email from us, it’s unlikely that any of the content you submitted to the Internet2 Spaces Wiki needs to be re-entered. We apologize for any inconvenience this may have caused. Should you have any questions or require further assistance, please email collaboration-support@internet2.edu.
Child pages
  • Linux Identity Provider IdPv3 (RHEL 7)
Skip to end of metadata
Go to start of metadata



Section 0: Preconfiguration

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

 

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 of 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
      • SQL
    • Do you have the needed service accounts
      • LDAP service account for the attribute resolver
      • For LDAP 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.
3. Prepare to install the Shibboleth IdP software

  • Objective:
    • Obtain the Shibboleth IdP software
  • Tasks:
    • Download the latest version of the IdP software to /opt/shibboleth-identity-provider-3.3.1.tar.gz.
    • Unzip the file using 'tar -zxvf shibboleth-identity-provider-3.3.1.tar.gz'  (run this from the /opt/ directory).

      cd /opt/
      curl -O http://shibboleth.net/downloads/identity-provider/latest/shibboleth-identity-provider-3.3.1.tar.gz
      tar -zxvf shibboleth-identity-provider-3.3.1.tar.gz
      
4. Install Shibboleth

  • Objective:
    • Install the Shibboleth IdP software
  • Tasks:
    • Set JAVA_HOME for all users by adding it to /etc/profile, and then export it into the current shell so you don't need to relog:

      echo "export JAVA_HOME=/usr/lib/jvm/jre" >> /etc/profile
      export JAVA_HOME=/usr/lib/jvm/jre
      
    • Run the install.sh script found in the location you unzipped the shibboleth installfest download in step 3.

      cd /opt/shibboleth-identity-provider-3.3.1
      ./bin/install.sh
      

      The installer script has a "bug" where it adds extraneous newlines at a couple of the user input prompts. If you think the installer is hung, try hitting "enter" or "return" to proceed.

    • Accept default values with the exception of hostname and Attribute Scope. For hostname, enter the fully-qualified hostname (FQDN) for your IdP host (my.special.name which you chose earlier). 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. For Attribute Scope, enter the domain part of your FQDN. For example, if your chosen hostname is my.special.name, you should set Attribute Scope to special.name.
    • Enter a password for the java keystore created by the installer at the Backchannel PKCS12 Password: prompt.  In the default configuration and installation, this refers specifically to a key used by the IdP for direct TLS-secured communications with SP's rather than TLS with the User Agent, e.g. the browser.   Please remember the password you use.  We'll overload these credentials and use them on the front channel until we get real certificates and keys from a service such as the InCommon Certificate Service.  This is entirely configurable, but this will get us started.
    • Enter a password to be used to protect a java keystore containing a key used by the IdP to encrypt cookie values it sets at the Cookie Encryption Key Password: prompt.  We'll talk later about what this encryption is useful for.  Please remember the password you use.
    • You will be warned that bindistdocsystem, and webapp don't exist.  We would not expect them to exist at this point, but it's a tripwire that can alert you to path mismatches in situations where you would expect to find them.  For now, please refrain from relaying these or issuing fresh warnings to the instructors.
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 9.3.  The Training Team has created a template jetty_base folder to make your life better.  These files contains much of the configuration of the web server that is necessary, but you'll be tweaking them.

  • Objective:
    •  Prepare java and jetty to run the IdP software.
      • Web environment configured
      • Context deployment fragment properly placed
  • Tasks:
    • Download and install Jetty 9.3.

      Prior to each workshop, we upload a copy of the latest Jetty distribution at the link shown in the example below. This is to minimize the chances of a new version coming out during the workshop and creating issues (yes, this has actually happened before). If you prefer, you can download Jetty directly from Eclipse at http://www.eclipse.org/jetty/download.html.

      cd /opt
      curl -Lo jetty-distribution-9.3.17.tar.gz https://internet2.box.com/shared/static/dlatofiug7l7vyiw4y7z2z69vnfrk7bi.gz
      tar xzvf jetty-distribution-9.3.17.tar.gz
      ln -s jetty-distribution-9.3.17.v20170317 jetty
    • Download the Jetty base prepared for you by the Training Team from https://github.com/Internet2/inc-train-jetty-base/archive/longbeach.tar.gz to /opt/shibboleth-idp/jetty-base.  If you prefer to write your own, please start from this template or use the official documentation, but most deployments will find this to be a great starting point.

      cd /opt
      curl -LO https://github.com/Internet2/inc-train-jetty-base/archive/longbeach.tar.gz
      tar xzvf longbeach.tar.gz
      cp -R inc-train-jetty-base-longbeach/jetty-base/ /opt/shibboleth-idp/jetty-base
    • Configure Jetty's usage of port 443.
      • We will be appropriating the back-channel keypair and certificate generated by the Installer for expediency.  In production, you'll want to obtain a real and separate keypair from a CA trusted by browsers, and point trustStore to a valid CA certificate bundle.
         
      • Open the file /opt/shibboleth-idp/jetty-base/start.d/ssl.ini in your preferred editor
        • Change jetty.sslContext.keyStorePath and jetty.sslContext.trustStorePath to /opt/shibboleth-idp/credentials/idp-backchannel.p12
        • Change jetty.sslContext.keyStorePassword and jetty.sslContext.trustStorePassword to match the value you entered at the Backchannel PKCS12 Password prompt when you ran the installation script.
        • Verify that jetty.sslContext.keyStoreType and jetty.sslContext.trustStoreType are both set to PKCS12
    • Create a systemd configuration file to load and manage the Shibboleth IdP using Jetty as the servlet container
      • Create the file /etc/systemd/system/shibboleth-idp.service using your favorite editor and save the following there.  This is case sensitive.

        [Unit]
        Description=Shibboleth Identity Provider
        
        [Service]
        WorkingDirectory=/opt/shibboleth-idp/jetty-base
        ExecStart=/usr/bin/java -jar /opt/jetty/start.jar jetty.home=/opt/jetty jetty.base=/opt/shibboleth-idp/jetty-base
        
        [Install]
        WantedBy=multi-user.target
    • Reload the configuration for systemd:

      systemctl daemon-reload

       

    • Enable the Shibboleth.service:

      systemctl enable shibboleth-idp


    • Start your IdP and Jetty: 

      The first time you do this, you may need to run the following command twice.


      systemctl start shibboleth-idp

       

       

    • If the IdP started up correctly, there should now be a running Java process. If you don't see one, check the journal for errors: 

      pgrep -lf java
      journalctl | tail -100

      You can also verify the IdP's status with systemctl:

      systemctl status shibboleth-idp


  • Resources:
  • Success Factors:

    • The provided base Jetty configuration has been installed at /opt/shibboleth-idp

      Production Tip

      The Shibboleth project does not distribute a jetty-base with the IdP.  We constructed one for this class based on the documentation and our knowledge, but it's not officially recommended for use in production.

    • You can visit https://<my.special.name>/idp and after you get past the browser SSL warnings you will see a page that says "Our Identity Provider" in orange at the top.

    • The IdP doesn't really log anything special to indicate that it has started successfully.  Typically, there is a line about REMOTE_USER that only appears at the end of a successful initiation, and many deployers use that to determine that the IdP is mostly initialized.

    If you ever want to uninstall the IdP, just rm the packages under /opt.

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.
    • Installation directory (/opt/shibboleth-identityprovider-3.3.1)
      • The distribution lives at a path distinct from the rest of the installation by design.  It's intended to be replaced completely during the upgrade process, no matter how minor the change, and it's not used by the IdP in flight.
    • Primary configuration (/opt/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 file.
        • 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.  If nothing exists, you'll get an org.apache.velocity error denoting the missing view in your logs, but other resources will continue to function.  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 any 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.sh, typically with the build target of upgrade.
    • 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 /opt/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, /opt/shibboleth-idp/metadata/idp-metadata.xml). It can also be downloaded from https://<MySpecialName>/idp/shibboleth
    • Create a local copy of your idp-metadata.xml file on your host machine.
    • Upload a copy of your IdP's metadata at the classroom metadata aggregator page: https://sp.training.incommon.org/mdupload/
    • 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 /opt/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 -->
      <!-- By copying and pasting this clickthrough agreement, I pledge on my -->
      <!-- mom's favorite food to never, ever use untrusted metadata in production -->
      <MetadataProvider id="ShibbTrainMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
      metadataURL="http://md.training.incommon.org/downloads/ShibTrain1-metadata.xml"
      backingFile="/opt/shibboleth-idp/metadata/ShibTrain1-metadata.xml"/>
      
    • When you are finished, restart Shibboleth using systemctl restart shibboleth-idp.  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 /opt/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.
  • Tasks:
    • Change /opt/shibboleth-idp/conf/idp.properties.
      • Set idp.authn.flowsMFA
    • Configure the ldap.properties file in your shibboleth install.
      • Edit /opt/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 uncomment idp.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 (not needed for this training session). In such cases, you may need to copy the LDAP server's certificate to the IdP.  By default, just placing it into /opt/shibboleth-idp/credentials/ldap-server.crt should be sufficient.
      • 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 /opt/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 Shibboleth.
  • 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  

      cp 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 Shibboleth 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:

      <logger name="idp.loglevel.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 servlet container(via the shibboleth-idp service definition).

      After setting this, log in again and check /opt/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 ID's 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 Shibboleth 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 /opt/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 /opt/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 form-based native support for 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("foo.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 /opt/shibboleth-idp/bin/build.sh.
  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 changes 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.

Protip

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, /WEB-INF/jsp/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 is 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 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.

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.

Discussion Topics