3.0 beta 1

This is sparse documentation to aid in testing the beta releases of the Identity Provider 3.0 software. We will eventually have more complete documentation on par with, or hopefully better than, that available for 2.x, but that will take a good portion of next year to complete, so for now this is an outline of the changes in 3.0 and how to find the right places to configure specific features. The general thrust of this material is for the tester who is familiar with 2.x, so many comparisons and notes about the differences and changes are made.

Those with experience running 2.x will find many similarities and significant compatibility, with the major difference being much more use of native Spring XML configuration for newer or enhanced features. For some helpful reference material on how native syntax works, see:

Another key technology that can greatly simplify more complex Spring requirements is the Spring Expression Language:

To show just one simple example, populating list-based properties can require multiple lines of XML, or can be shorthanded with SpEL:

#{ {'item1', 'item2'} }

While the use of Spring Web Flow (SWF) for user interaction is a major change, we have tried to minimize the degree to which a typical deployer will need to interact with, let alone customize, flows. But we provide some notes on how and where this can be done for those with more ambitious needs.

Reporting Bugs

Feel free to discuss issues on the dev@shibboleth.net list or file any issues in JIRA at https://issues.shibboleth.net. Please associate issues to the 3.0-alpha2 version if possible, as it's less likely to be overlooked that way.

Features Done or TBD

In general, 3.0 is a small superset of 2.x features at this stage, with a couple of exceptions.

Audit logging is not yet present, and general logging is a first draft at this stage, so lots on DEBUG, not much analysis of what's needed on INFO or WARN.

We have not yet added functionality from uApprove, so that matches 2.x at this point.

Most of the functionality for all supported 2.x profiles is present, with the exception of the partial logout support added in 2.4, which is not yet added to 3.0.

Notable Changes Since alpha1

A lot of major bugs have been fixed that were small in size but prevented testing a lot of basic features.

There are no longer dummy "default" credentials included with the distribution, so it's necessary to run a temporary script included in bin/ or some native commands manually to generate keys and certificates.

There are no longer seperate authentication flows for different password-based back-ends like JAAS or LDAP, but a single flow for password authentication that can be easily configured to use different back-ends. This is a breaking configuration change.

A new subsystem was added to support reloadable access control rules for administrative features like the status page.

The ECP profile implementation was completed.

The war tree is now expanded in the distribution to allow us to run command line tools without duplicating libraries.

Preliminary Installation Guide

Work on an installer is not complete, so the alpha does not have a formal installation process. See the alpha installation topic for instructions for this release.

General Installation Structure

The installation layout of the alpha release (and the planned layout of future releases) is as follows:

shibboleth-idp/					(root, referred to as idp.home)
	bin/						(scripts and utilities)
 	conf/						(user-modifiable configuration, untouched across upgrades)
		idp.properties			(properties that plug into XML config in various ways)
 		authn/					(authentication-related configuration)
 		c14n/					(subject normalizing configuration)
	creds/						(credentials, keys, certificates)
	doc/
	flows/						(user-modifiable SWF definitions, untouched across upgrades)
	jetty-base/					(example Jetty configuration suitable for use with current Jetty versions)
	logs/
	messages/					(internationalized messages for UI templates, untouched across upgrades)
	metadata/					(locally deployed metadata, backup for remotely hosted metadata)
	misc/						(additional useful files included with the install)
	system/						(internal system configuration, meant to be left alone)
	views/						(external-to-war Velocity UI templates, untouched across upgrades)
	war/						(unpacked war tree containing the Java webapp)

The most important difference from older versions is the separation of configuration files into user- and system-level files. The contents of the "system" directory and its subdirectories are meant to be left unmodified to as great an extent as possible. This is to ensure that backward-compatible upgrades can be accomplished safely without reapplying local changes, and so that core configuration changes required by newer versions can be applied automatically.

There are a number of interdependencies between the Spring configuration files in "conf" and "system" that are like a contract between the user configuration and the system configuration. In most cases, these dependencies can be identified via the use of bean identifiers that contain the prefix "shibboleth." When in doubt, don't change a bean id that contains such a prefix. Eventually the various required beans will be thoroughly documented.

Properties

The old 2.x support for "resource filters" that allowed for property replacement in configuration files has been replaced with a less generic but more supportable approach using Spring's property replacement layer. This allows for both arbitrary files containing properties, but also chaining back to the system environment or system properties set in Java. By default, we supply a file called idp.properties that is processed at load time and is accessible as a property source for most of the configuration files.

Unfortunately, the syntax for Spring properties by default clashes with Velocity macro syntax, which causes problems in the attribute resolver configuration. To avoid this problem, the Spring syntax is customized to use a '%' character as a prefix. So properties in the files will appear as "%{propertyname}" or in some cases "%{propertyname:defaultvalue}". If you want to use your own properties, just keep in mind you need to use a different character than documented by Spring.

Configuration Areas

 Topics exist for each general configuration area to go into more detail on how to do various things or try out features:

Configuration Changes (and Non-Changes) from 2.x

You'll see a lot of new files in "conf" as well as a few familiar ones. There are three older files that are designed to work fully, or almost-fully, from 2.x:

These are, not surprisingly, the files containing most of the frequently modified configuration in older versions. There are a few caveats to this compatibility, which are discussed in the subtopics discussing these particular files, but apart from the noted issues there, any failures to load or operate as expected with any older 2.x configuration files should be considered a high-priority bug and reported. We can't possibly test all the possible options out there, so it's critical that we get feedback on these issues prior to the release later this year to smooth the upgrade process. All regressions should be reported via JIRA.

The other files are essentially new configuration, or in a few cases are refactored subsets of the original relying-party.xml configuration, which is discussed in that subtopic.

The most noteworthy change is that authentication is configured very differently in 3.0. There is no handler.xml file any longer, but there are substantial overlaps in the common cases of the UsernamePassword or RemoteUser login handlers, and there's a similar feature to the External login handler. In particular, the hardest aspects of configuring those handlers should translate more or less directly to this version.