Skip to main content

You joined the InCommon Federation, now what?

You have paid your InCommon membership dues, your federation admins have been vetted, and you even uploaded your IdP metadata in the InCommon Federation Manager website. Like many new members, you are probably asking yourself, "Now what?"

Keep in mind that the InCommon Federation is really just a way to share identity provider and service provider metadata in a centralized hub and spoke model, versus the traditional spider web model of each IdP having to directly exchange its metadata with each partnering service provider and each service provider directly exchanging its metadata with each partnering identity provider. So, the next step is to configure your IdP to consume the InCommon metadata feed. 

Configuring your IdP to utilize the InCommon metadata feed will depend upon your IdP. With Shibboleth IdP v3, this is accomplished by adding the following snippet to <IDP_HOME>/conf/metadata-provider.xml (and downloading the signing cert as instructed in the comments):

  <!-- From https://spaces.internet2.edu/display/InCFederation/Shibboleth+Metadata+Config -->
  <!--
    Refresh the InCommon production metadata aggregate every hour.

    Note: The defaults for minRefreshDelay, maxRefreshDelay, and refreshDelayFactor
    are "PT5M", "PT4H", and "0.75", respectively. The value of maxRefreshDelay
    has been modified below such that the metadata is refreshed every hour ("PT1H").
    The other properties merely regurgitate their default values. They are included
    here for convenience, in case you want to change their default values.
  -->
  <MetadataProvider id="ICMD" xsi:type="FileBackedHTTPMetadataProvider"
                    xmlns="urn:mace:shibboleth:2.0:metadata"
                    metadataURL="http://md.incommon.org/InCommon/InCommon-metadata.xml"
                    backingFile="%{idp.home}/metadata/InCommon-metadata.xml"
                    minRefreshDelay="PT5M"
                    maxRefreshDelay="PT1H"
                    refreshDelayFactor="0.75">

      <!--
        To bootstrap the trust fabric of the federation, each relying party
        obtains and configures an authentic copy of the federation operator's
        Metadata Signing Certificate (https://spaces.internet2.edu/x/moHFAg).

        Fetch the InCommon Metadata Signing Certificate and check its integrity:

        $ IDP_HOME=/opt/shibboleth-idp
        $ curl -s https://ds.incommon.org/certs/inc-md-cert.pem \
            | tee $IDP_HOME/credentials/inc-md-cert.pem \
            | openssl x509 -sha1 -fingerprint -noout
        SHA1 Fingerprint=7D:B4:BB:28:D3:D5:C8:52:E0:80:B3:62:43:2A:AF:34:B2:A6:0E:DD

        Verify the signature on the root element of the metadata aggregate 
        (i.e., the EntitiesDescriptor element) using the trusted Metadata 
        Signing Certificate.
      -->
      <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
              certificateFile="%{idp.home}/credentials/inc-md-cert.pem" />

      <!--
        Require a validUntil XML attribute on the EntitiesDescriptor element
        and make sure its value is no more than 14 days into the future.
      -->
      <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D" />

      <!-- Consume all SP metadata in the aggregate -->
      <MetadataFilter xsi:type="EntityRoleWhiteList">
        <RetainedRole>md:SPSSODescriptor</RetainedRole>
      </MetadataFilter>

  </MetadataProvider>

This configuration does a few things:

  1. It tells the IdP to download the metadata and save a local copy to the file system.
  2. It gives the IdP the certificate used to validate the signature of the downloaded metadata to ensure the file was not tampered with during transit.
  3. It tells the IdP to ignore the metadata of other IdPs and to just load SP metadata. Because the IdP does not interact with other IdPs, it is just a waste of memory to store IdP entries in memory.

So now the IdP knows about all of the SPs contained within the InCommon metadata. But that is it... just metadata. If one of your users browse to one of these InCommon member SPs, the user will be asked to choose their home IdP from a discovery service's IdP list, and the user will be sent to their organization's IdP. Once the user has been authenticated, the IdP will send a response back to the SP, but it will have no user specific attributes/information. That is because the IdP was never configured to release any attributes for this SP. 

Not releasing user attributes to the InCommon SPs may be intended. Perhaps you only joined InCommon because some SP requires your IdP to be registered with InCommon to integrate, but there is another option for organizations that want to allow users to participate with open SPs. We could go to the other extreme and release a set of basic attributes (e.g. eduPersonPrincipalName, eduPersonAffiliation, email, givenName, and surname) to all known SPs. But in U.S.-based higher education, FERPA will likely limit the applicability of that option because we cannot guarentee that all of the InCommon SPs may not be directly education specific.

When using Shibboleth IdP v3, we have some other options. The IdP has the ability to ask the user for consent to release attributes to SPs. So it is possible to instruct the IdP to check with the user and ask permission to release the attributes before releasing them to SPs not explicitly allowed by IdP admins. Additionally, we can not show the consent page for those SPs that a school has determined to be educationally related. This can all be done through the magic of relying party overrides.

To summarize, you have three attribute release options once you have loaded in the InCommon metadata:

  1. Do nothing and explicitly authorize the SPs that the organization decides to do business with.
  2. Release a minimal set of attributes to all known SPs (or just SPs in the InCommmon metadata) so that end users have a decent chance of being able to participate with those SPs without requiring IdP Admin intervention for each SP.
  3. Release the required attributes to SPs that you are explicitly doing business with and use user consent for the other InCommon SPs so a user can choose what to give up.
John Gasper

John Gasper

Software Architect
John Gasper is a wonderful mix of Identity and Access Management (IAM) consultant and DevOps implementer. By day, he is implementing, configuring, or advising on one of the many open source IAM applications including CAS Server, Shibboleth, Grouper, SimpleSAMLphp, 389 Directory Server, and occasionally on a closed source applications like Microsoft Active Directory and Active Directory Federation Services. By night, John tries to automate the world of IT using tools, such as Docker, Jenkins, and Kubernetes. He has experience with cloud providers including Amazon Web Services (AWS), Google Cloud Platform, and Microsoft Azure. Before joining Unicon in 2013, he worked in IT at Eastern Washington University covering multiple facets of IT including Banner development and administration, Active Directory administration, and pretty much everything in between. They even let him write code for Cisco IP Phone applications