IdPRelyingConfig

Relying Parties

The basic unit for defining the other half of exchanges with the IdP is the relying party. A relying party can be comprised of an entire federation, a single enterprise, or even one application, and is treated the same way by the identity provider. Any specifications made regarding a relying party will be applied for all transactions to which it applies on a closest-match basis. This allows for more specific definitions for individual relying parties within a broader relying party, e.g. one service provider in a federation.

The RelyingParty element is used to specify one or more relying parties that this IdP must recognize. This includes any federations the IdP is a member of, any SP's that have established bilateral agreements with the IdP, or any other trust structure that IdP must be aware of. It allows the IdP to vary its use of names and credentials on a transactional basis to accommodate different relying parties.

The IdP performs validation against federation metadata to ensure that a particular relying party cannot construct requests that cause another SP's relying party information to be used.

The proper RelyingParty element to handle a given attribute request is selected by the following algorithm. If at any point a match is found, processing is complete; only one relying party will be used for any given request.

• If the requesting provider is unauthenticated – due to a lack of SSL client authentication because the AA is not protected by an https:// URL – the default relying party is always used.
• If the requesting provider is Shibboleth 1.1 or less, the default relying party is used.
• If a RelyingParty element's providerId attribute matches the name sent by the SP, then that element is used.
• A metadata lookup is performed using the metadata.xml files supplied by MetadataProvider elements to determine whether the SP is a member of a common federation. If there is a RelyingParty element that has the same providerId as the URI of the the federation, it is used. If not, the default relying party handles the request.

  <RelyingParty name="URI" providerId="URI" signingCredential="string" AAUrl="URL" defaultAuthMethod="URN" passThruErrors="true/false" providerId="string" signAssertions="true/false">

  In addition to its attributes, this element may contain a NameID element to specify a naming mechanism for assertions sent to this relying party.

• name: Each RelyingParty element is differentiated by a URI specified in the name attribute. An SP will send its providerId with its requests; if the URI it provides here matches the name attribute, this element will be used in the transaction. If there is no direct match, the !IdP uses metadata to try to find a federation that the service provider is a member of.
• providerId: If the IdP should perform transactions with this relying party using a different providerId than the default for the IdP as a whole, it may be specified individually using a providerId attribute on this element.
• signingCredential: This attribute specifies the signing credential that will be used by the SSO handler for requests from this relying party and must match the identifier of the appropriate FileResolver ID. A separate set of credentials may be specified for the IdP's signing of assertions and SSL session identification with this relying party. An incorrect signing key will lead to trust failures.
• AAUrl: Different AAs may be specified for different relying parties using this attribute. It over-rides, is populated, and operates in the same manner as the AAUrl attribute of the IdPConfig element.
• defaultAuthMethod: The value of this attribute represents the mechanism by which the user's authentication was performed. It is used to populate authenticationMethod in SAML assertions passed to this relying party if no other authentication method is passed to the HS. For a brief list of authentication methods, consult the same attribute as part of the IdPConfig element.
• passThruErrors: This boolean attribute determines whether the IdP will relay errors in flows to this SP for use in displaying these errors to the browser in the case of an unsuccessful transaction.
• providerId: If the !IdP must assert under a different name to this relying party, specify a providerId attribute which will over-ride the one specified in IdPConfig.
• signAssertions: If this boolean attribute has a value of true, all assertions generated for transport to this relying party will be signed. This is mostly useful for using the attribute assertion in contexts outside of the Shibboleth flows and defaults to false.

Federations

Federations are collections of IdPs and SPs that agree to exchange information according to a set of rules with a list of acceptible root certificate authorities, often utilizing a common set of attributes. Membership in a federation does not limit bi-lateral agreements with other sites inside or outside the federation, although the political and mechanical framework of the federation can make these interactions easier.

Shibboleth supports the use of federations in order to simplify trust interactions and policy in support of these exchanges. It is not necessary to be part of a Federation to utilize Shibboleth, nor is a federation necessarily confined to supporting only Shibboleth. A federation from the point of view of an identity provider is just a construct that behaves in many ways like any other relying party.

Most federations will distribute a metadata.xml file to facilitate trust interactions which must be pointed to by IdP.xml. This file identifies certificates and root CAs that are considered authoritative for that federation, and identify service locations, contact and error handling information, URNs, and certificate naming for individual sites in that federation. In addition, there will often be a ca-bundle.crt naming signing authorities for SSL server certificates that must be referenced by a SSLCACertificateFile element in Apache's configuration for the attribute query handler, typically the port 8443 vhost.

Membership and participation in multiple federations can be accomplished in most cases by simply pointing to other metadata files with additional MetadataProvider elements. If it is necessary to trust or use a different set of certificates for SSL, then a separate Apache virtual host most be defined on another port to protect the attribute query handler with a separate set of SSL directives. Metadata entries for this identity provider will then differ between federations.

MetadataProvider

This configuration element supplies metadata to the IdP to identify relying parties in transactions. It may appear as many times as necessary.

Additionally, it is frequently necessary to define differential use of credentials or other behaviour using RelyingParty elements. The use of different name types is the most critical change, but other changes may be made. These can be used to point to all members the entire federation by using the federation's URI: for example,

<RelyingParty name="urn:mace:inqueue" signingCredential="foo">
	<NameID nameMapping="crypto"/>
</RelyingParty>

These settings may be over-ridden on an individual site basis. The closest match for any given URI is used.

metadatatool

The Shibboleth IdP leverages metadata distributed by relying parties and federations to validate the identity of requesters and the resource providers on whose behalf the request is being made. This metadata is cached locally in the form of metadata.xml. Shibboleth includes a simple utility called metadatatool which can be used to refresh a metadata.xml file. These files are then pointed to by MetadataProvider elements in idp.xml and shibboleth.xml.

The metadatatool can verify the the metadata's signature if the signing certificate is in a Java keystore. Download the signing certificate (e.g., into inq.pem), then import it into a keystore using the Java keytool.

keytool -import -file inq.pem -keystore internet2.jks -alias sitesigner

The following command is appropriate for most deployments and is run from the $SHIB_HOME directory. This should be frequently run by adding it to a crontab to ensure that the data is fresh.

bin/metadatatool -i https://wayf.internet2.edu/InQueue/IQ-metadata.xml -k conf/internet2.jks -a sitesigner -p shib123 -o /your_path_here/IQ-metadata.xml

This is a list of all the command-line parameters that may be specified:

when signing:

-i <uri> -s -k <keystore> -a <alias> -p <pass> [-o <outfile>]

when updating:

-i <uri> [-k <keystore> -a <alias> OR -N ] [-o <outfile>]

Shibboleth 1.2 still utilizes mod_ssl for verification of certificates presented by SHARs when processing attribute requests. This requires an updated ca-bundle.crt to ensure that all appropriate certificate authorities used by relying parties are recognized.