Federated Service Providers

Service Provider Registration

The registration process serves a number of purposes, such as tracking and record keeping within the IT Security and Policy Office and InCommon to better support users, auditing of information disclosure about users (so we know who's getting what and why), and secure binding of certificates. Some of the information is also required for the secure operation of the Shibboleth system, and must be updated in the event that it changes. Therefore accurate contact information is essential.

The current registration process is largely manual (via e-mail), but may be more automated in the future. To initiate the process, the following information must be supplied in an email to servicedesk@lsu.edu with a subject of "Shibboleth - InCommon Service Provider Registration".

1. Name of service (if multiple, just summarize)
2. Brief description of service
3. Technical, administrative, and/or support contact information for your service (names, e-mail addresses, phone, etc.)
4. Summary of platform (operating system version, web server version, etc.)
5. User attributes required by service
6. One or more hostnames at which users will be accessing your service (i.e. your web server's virtual host names)
7. Your self-signed certificate
8. A verifiable phone number at which you can be reached for verification of the information

Once your submission is processed, you will be contacted by phone in order to verify the information supplied, clarify or correct any problems, and authenticate the certificate. At that point, your certificate will be forwarded to InCommon for signing, and a unique name called an entityID will be assigned to your service provider. This name (which typically looks like a URL) will be configured into the software and is used in various ways by the software to regulate the flow of information and create policy about the release of user attributes .

Firewall Configuration

A federated deployment requires that an outbound firewall allow the server running Shibboleth to make outgoing HTTP requests on at least ports 443 and 8443 to potentially any InCommon identity provider as well as the addresses behind the DNS alias "wayf.incommonfederation.org". The federation generally requires the use of those ports to limit the number of different firewall rules required. No Shibboleth-specific inbound traffic is necessary.

Software Configuration

The following steps will enable you to (relatively) easily modify the default software configuration to support and "lock down" access to InCommon identity providers, enable your new key and certificate, and customize the settings to your web server and service provider configuration. Some of the specific changes depend on your environment, but this should provide a suitable starting point.

1. Supplement/replace default configuration files with OSU-specific versions

Download the following files (right click and save) and place them in the etc/shibboleth/ folder beneath your installation root:

lsu-attribute-policy.xml
incommon.pem
sessionError.html

Replace the default etc/shibboleth/shibboleth2.xml file with this version:

• shibboleth2.xml

Replace the default etc/shibboleth/attribute-map.xml file with this version:

• attribute-map.xml

2. Make site-specific changes to shibboleth2.xml file

The primary Shibboleth configuration file is in etc/shibboleth/shibboleth2.xml . The LSU version supplied is a starting point that includes most of the InCommon-specific settings required (but commented out), and reasonable defaults for applications. Some of the content is based on your application requirements and your particular configuration, and must be modified to reflect this. To get up and running, make these changes:

• Replace any references to the dummy hostname sp.example.org with the fully-qualified domain name of your web server. On Apache servers, this value should correspond to the Apache ServerName directive (which you may also need to set).


• If you're using IIS, and need to enable the filter for multiple virtual host names, you will need to insure that the <ISAPI> element contains a <Site> element mapping your IIS web sites' INSTANCE_ID values to the appropriate hostname(s). Failure to do this will usually cause the filter to ignore requests you expect to be secured.


• Modify the <ApplicationDefaults> element's entityID attribute, replacing the default value with the identifier assigned to you when you register your service provider.


• Modify the <Errors> element's supportContact attribute, replacing the default value with the email address of your help desk or support personnel.


• Modify the sessionError.php file such that users are directed to the proper contact (email, web link, etc.) to report errors. In most cases, this should not be the IT Service Desk (8-DESK), unless you have made specific arrangements for support to be handled there.


• Ensure that the <CredentialResolver> element near the end of the file contains the accurate filenames of your private key and certificate (and that they're located in the same directory as the configuration file).


• If you are not using SSL with your web site (this is a very bad idea, but...), you'll need to change the handlerSSL setting to "false" , and remove the cookieProps setting, from the <Sessions> element.

3. Federation-enable your installation

To switch from an LSU-specific installation to a federation-enabled system:

• Replace the LSU-supplied <MetadataProvider> element with:

  	<MetadataProvider
  	  type="XML"
  	  url="http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml"
  	  backingFilePath="InCommon-metadata.xml"
  	  maxRefreshDelay="28800">
  	
  		<SignatureMetadataFilter certificate="incommon.pem"/>
  		<MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
  	</MetadataProvider>
  	

• If you don't have a local discovery solution, you can use the InCommon service by removing the entityID setting from the <SSO> element and configure it as described by this material .

4. Designate content to be protected

The final step (and an ongoing one) is to specify content that requires an authenticated session to access. Apache supports various commands for this purpose, but the <RequestMap> element in the Shibboleth configuration file must be used with IIS servers. This does not directly perform any authorization for you, but it does ensure that a session via an InCommon identity provider has been established and any attributes the software can obtain about the user are available.

By default, a single <Path> element and its requireSession attribute is used to designate that any content in a folder named "secure" beneath the server document root is protected. Each element specifies a single component of the URL path to a resource. The resource/file name itself can also be specified as a <Path> element (the leaf of a tree). You can nest elements to specify session requirements embedded within specific subtrees. Other approaches (such as regular expression matching based on the URL) are also supported. Here is a complete reference. .

5. Start (or restart) Shibboleth service and web server

Once the initial changes described here have been made, you can try starting (or restarting) the various services and proceed to test and troubleshoot the installation. A few problems are not unexpected. The wiki and mailing list archive should help you diagnose problems or at least know where to look so you can provide accurate problem reports.

If you're getting metadata errors indicating the identity provider isn't supported, make sure you downloaded the incommon.pem file mentioned earlier, as you'll need it at runtime to verify the signature on the InCommon metadata file.

Next Steps

The preceding steps should get you close to a working Shibboleth-enabled service, but obviously there are a lot of complex options available and additional tasks necessary to maintain your deployment effectively. Additional information is available to assist with application development .