The Shibboleth V1 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only.

BilateralDeployment

Owned by Scott Cantor
Last updated: May 09, 2012 by ChadCVersion comment
5 min read

This page describes an approach to configuring a single Shibboleth IdP and SP to recognize each other and interoperate successfully with each other. There are a number of ways to do this; this page describes just one straightforward approach.

Essentially, you have to create a new metadata file describing the IdP and the SP, and make this available to both components. Then, you have to edit the idp.xml file to use this new metadata file and to associate SSL and signing credentials with this new relationship. Lastly, you have to perform essentially the same steps with the SP's shibboleth.xml config file. This document recommends having both components use newly minted keys and self-signed certificates when communicating with each other.

This page assumes that you are working with newly installed !IdP and SP components, and that these components will ONLY be used with each other.

The New Metadata File (partner-metadata.xml)

  1. Copy example-metadata.xml to partner-metadata.xml
  2. Generate and save a key and cert for the !IdP
    A. openssl genrsa -out idp.key 2048
    A. openssl req -new -key idp.key -x509 -days 365 -out idp.crt
  3. Repeat the above two steps, generating a key and cert for the SP
  4. Edit the IdP EntityDescriptor. The easiest way to do this is to use the Metadata Generator and replace the !IdP EntityDescriptor in the metadata file with the descriptor the generator creates. You can also hand edit the metadata file's default EntityDescriptor by doing the following:
    A. Enter a providerId (the entityID attribute in the EntityDescriptor element). We recommend values of the form https://idp.hostname/shibboleth , where hostname is replaced by the full DNS name of your host. Remember that this is a logical name; the Shibboleth software will not attempt to use this URL to retrieve anything.
    A. If you intend to use eduPerson attributes such as eduPersonScopedAffiliation or EduPersonPrincipalName, then change the value inside the two Scope extension elements in the file to a domain name associated with your security domain.
    A. There are two KeyDescriptor elements. In the first one, replace the data within the X509Certificate element with the contents of idp.crt (created above). Delete the second KeyDescriptor element to reduce later confusion.
    A. There are two ArtifactResolutionService elements. In the first one, within the Location Attribute, change the hostname part of the url to be the name of the host where you are running your !IdP. Delete the second ArtifactResolutionService element to reduce later confusion.
    A. There are two SingleSignOnService elements. In the first one, within the location Attribute, change the hostname part of the url to be the name of the host where you are running your !IdP. Delete the second SingleSignOnService element to reduce later confusion.
    A. Within the AttributeAuthorityDescriptor element, within the !X509Certificate element, replace the data with the contents of idp.crt.
    A. Within the AttributeService element, within the Location Attribute, change the hostname part of the url to be the name of the host where you are running your IdP.
  5. Edit the SP !EntityDescriptor. You should hand edit the metadata file's default EntityDescriptor by doing the following:
    A. Enter a providerId (the entityID attribute in the EntityDescriptor element). We recommend values of the form https://sp.hostname/shibboleth , where hostname is replaced by the full DNS name of your host. Remember that this is a logical name; the Shibboleth software will not attempt to use this URL to retrieve anything.
    A. In the X509Certificate element, replace the data with the contents of sp.crt.
    A. In all of the AssertionConsumerService elements, within the Location Attribute, change the hostname part of the url to be the name of the host where you are running your SP.
    A. Optionally, duplicate the first AssertionConsumerService element (the one whose URL contains SAML/POST), and change https to http. Be sure to modify the index attribute in the new element.

Edit mod_ssl Configuration

Wherever you have defined the settings for the SSL vhost that will be hosting the IdP's SOAP services, usually on port 8443, modify the SSLCertificateFile and SSLCertificateKeyFile settings to the file system path to idp.crt and idp.key respectively. The Apache process identity (e.g. apache, nobody, www) will need read access to those files.

Edit idp.xml

  1. Change the following Attributes on the IdPConfig element:
    A. AAUrl - change the hostname within the url to be the full DNS name of the host where you are running your !IdP. (This value is only important when interacting with very old versions of Shibboleth.)
    A. Change the !providerId value to be the value you entered into partner-metadata.xml for your !IdP.
  2. In the RelyingParty element, change the value of the !signingCredential Attribute to be "bilateral"
  3. Within the Credentials element, duplicate the FileResolver element:
    A. In the new FileResolver element, change the value of the id attribute to "bilateral"
    A. In the Key element, change the value of the Path element to be the file system path to idp.key
    A. In the Certificate element, change the value of the Path element to be the file system path to idp.crt
  4. In the MetadataProvider element, change the value of the uri attribute to be the file system path to partner-metadata.xml

Edit shibboleth.xml

  1. Within the RequestMapProvider element, within the RequestMap element, on the Host element, change the value of the name attribute to be the full DNS name of the machine where you are running your SP. It should match the hostname you used when modifying the metadata file.
  2. In the !Applications element:
    A. Change the value of the !providerId Attribute to be the !entityID value you previously assigned to your SP, within partner-metadata.xml
    A. In the homeURL attribute, change the hostname portion of the URL to be the full DNS name of the machine where you are running your SP.
  3. In the SessionInitiator element, change the value of the wayfURL attribute to match the value of the SingleSignOnService element's Location attribute in partner-metadata.xml. This will bypass the use of a WAYF page, and will redirect browser users directly to your new IdP.
  4. In the CredentialUse element, change the values of both the TLS and Signing attributes to be "bilateral"
  5. In the MetadataProvider element, change the value of the uri attribute to be the file system path to the partner-metadata.xml file.
  6. In the CredentialsProvider element, within the Credentials element, duplicate the FileResolver element:
    A. In the new FileResolver element, change the value of the Id attribute to be "bilateral"
    A. In the Key element, change the value of the Path element to be the file system path to sp.key
    A. In the Certificate element, change the value of the Path element to be the file system path to sp.crt

Test Your New Configuration

  1. Restart your !IdP and SP components, and check the logs for config file errors.
  2. Attempt to access https://sp.hostname/secure using a web browser. If everything is successful, your request should be intercepted, you'll be asked to authenticate on the IdP machine, and eventually a 404 will be returned unless there really is a resource present there. If there is no interception, check the web server logs to ensure the SP is loaded properly and examine the configuration to make sure there are no problems such as the configuration being loaded for the wrong virtual host. If other problems arise, check the CommonErrors.

-- Main.StevenCarmody - 27 Jul 2005