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

IdPProductionConfiguration

Securing the Shibboleth IdP

Add Content

Tuning the Shibboleth IdP

Most of the performance characteristics for the Shibboleth !IdP are determined by the Servlet Container and Java VM running it. For Tomcat and Sun's JVM, a few suggested optimizations are described below:

  • Memory: Tomcat will require large amounts of memory to handle a high throughput of session creation. The default setting varies by Tomcat distributions, but it's appropriate to allocate at least 500 megabytes of RAM. Add a line like the following to catalina.sh or the script used to start Tomcat:
    JAVA_OPTS="-server -Xms512M -Xmx1024M"
    
  • Garbage Collection: When the RAM sized is increased dramatically to handle the large number of users some !IdP's must support, garbage collection can cause a severe service interruption while it's performed. Incremental garbage collection is recommended, which is specified by the -Xincgc flag.

Other performance enhancements can be gained through improving the !Shibboleth's interactions with attribute sources. The !IdP caches some attributes, but techniques such as JDBC or JNDI connection pooling can reduce the strain and latency associated with queries.

Customizing the Web UI

Out of the box the Shibboleth IdP comes with some default, and generally aesthetically sparse, pages that users see when interacting with it. An institution should customize these pages to, at the very least, include some more use friendly text and university branding. Each page contains some number of attributes that can be printed on the page by way of the following JSP taglib tags:

<bean:write name="attributeName" />

where attributeName is replaced by the name of the attribute to be printed.

Changing the "Request Processed" page

The first page is displayed after a user has authenticated but before they reach the service provider. This page, webApplication/IdP.jsp in the source tree, is what redirects the user from the IdP to the SP (either with the SAML response or an artifact for the response. This page has the following attributes available for use with in:

  • shire - This is the URL to the service provider endpoint that the SAML response or artifact needs to be submitted to for processing
  • target - This is the target URI for the service provider and MUST be submitted to the SP as the request attribute TARGET
  • assertion - This is the base64 encoded SAML response to the authentication request and must be submitted to the SP as the request attribute SAMLResponse
    By default, Javascript is used to submit a form with the TARGET and SAMLResponse attributes populated to the URL specified by the shire attribute.

When customizing this page you should not touch the code in lines 1 - 39, except lines 20 and 21 (to set the CSS and title used for the page) unless you understand exactly what it's doing. Beyond that you can customize the page however you see fit, just ensure that the above mentioned form fields, with the appropriate values get submitted to the URL, via POST, to the URL in the shire attribute. Some obvious customizations are to brand the page to your university. Other universities have replaced the automatic submitting java script (on the body's onLoad attribute on line 24) so that the first time a user employs Shibboleth to get an SP they must agree to some terms and subsequent requests to other service provider just forward on automatically.

Changing the error page

The other web page contained in the IdP is a page that is used to display errors when something goes wrong. The error page, webApplication/IdPError.jsp in the Shibboleth source tree, has access to two attributes that can be displayed on the page:

  • requestUrl contains the URL of the resource the user was trying access
  • errorText contains a textual description, and often technical, description of what error occurred

Institutions usually customize this page to look like the rest of thier sites (i.e. to provide a consitant branding) and to include help desk contact information. It should be noted that the information in the requestUrl and errorText attributes are not meant to help the user, but instead are meant to be given to help staff to help them put the problem in context and diagnose it.

When to Restart the IdP

Configuration Change

Restart Required

 

ARP xml files

No

idp.xml

Yes

resolver.xml

Yes

metadata files

No

Note

The IdP can be stopped and started independently of Tomcat, but you need to use the Tomcat manager interface to do this.

Monitoring the IdP

Shibboleth 1.3 and later include a special Status handler which allows standard web-based monitoring tools to verify that the IdP is up and running. It's located at a URL similar to https://idm.supervillain.edu/shibboleth-idp/Status and will display a simple AVAILABLE if the IdP is accessible.