Managing IdP Configuration Files

When running a production level service it is important to ensure the configuration is consistent (e.g. across cluster nodes), that changes are tracked, and that untested configurations are not accidentally deployed. This document addresses these issues.

Basics

The IdP's service.xml configuration file controls the loading of configuration information. Each Service defined in that file may load its configuration from local (e.g. filesystem, classpath) or remote (e.g. HTTP, Subversion) locations. This fetching of configuration information is controlled by the ConfigurationResource element.

By default the IdP loads all of its configuration files from the IDP_HOME/conf directory. However the following files can also be loaded from remote sources: attribute-filter.xml, attribute-resolver.xml, handler.xml, relying-party.xml.

The recommendation of this document is to manage an IdP's configuration as follows:

1. Load all allowable configuration files remotely
2. Keep sensitive information (such as LDAP passwords) in a separate property file

Loading Remote Configuration Files

The IdP can currently load its configuration from two different types of remote locations; an HTTP URL or a Subversion server. The recommended approach is to use Subversion because doing so also allows for good change tracking (via commit metadata).

Adjusting from where a configuration is loaded is done by changing the type of the <ConfigurationResource>. The following configuration snippet loads an IdP's attribute filter policy from the local filesystem and is what you would have from a basic installation.

<Service id="shibboleth.AttributeFilterEngine" 
         xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
    <ConfigurationResource xsi:type="resource:FilesystemResource" 
                           file="/opt/idp/shibboleth-idp-2.1.3/conf/attribute-filter.xml" />
</Service>

To fetch the attribute filter policy from an HTTP URL the configuration would become:

<Service id="shibboleth.AttributeFilterEngine"
         xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
    <ConfigurationResource xsi:type="resource:HttpResource" 
                           url="http://example.org/idpconf/attribute-filter.xml" />
</Service>

Note how the xsi:type of the <ConfigurationResource> changed and how the file attribute was replaced with the url property required by the HTTP resource.

Loading from Subversion

To load configuration files from a Subversion server use the SVN Resource configuration resource type. Here is an example:

<Service id="shibboleth.AttributeFilterEngine"
         xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
    <ConfigurationResource xsi:type="resource:SVNResource"
                           repositoryURL="http://svn.example.org/idp/prod/conf"
                           workingCopyDirectory="/opt/shibboleth-idp/svnconf"
                           resourceFile="attribute-filter.xml"
                           revision="513" />
</Service>

It is recommended that:

• the working copy directory be located in the $IDP_HOME directory and be called something like svnconf to make it clear that these configuration files come from SVN. You should not deploy directly, from SVN, to the IdP's working copy directory ($IDP_HOME/conf directory).
• a specific revision number be specified as the use of the HEAD revision may result in unintended versions of the configuration files being loaded

Loading from HTTP

To load configuration files from a Subversion server use the File-backed HTTP Resource configuration resource type. Here is an example:

<Service id="shibboleth.AttributeFilterEngine"
         xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
    <ConfigurationResource xsi:type="resource:FileBackedHttpResource"
                           url="http://example.org/idpconf"
                           file="/opt/shibboleth-idp/httpconf" />
</Service>

It is not recommended to use the plain HTTP resource shown in the first example as would prevent the IdP from starting if the remote site is down.

Dealing with Sensitive Configuration Information

Some configuration files may contain sensitive information such as passwords. For example, the attribute-resolver.xml probably contains the username/password used to access the institution's LDAP or relational database. Therefore this information should not be placed in a remotely accessible location.

This is remedied by using the property replacement filter within the <ConfigurationResource> that loads the file that contains the sensitive information. This allows such sensitive information to be pulled out in to a property file and merged in to the configuration resource before it is loaded by the IdP.

<Service id="shibboleth.AttributeResolver"
         xsi:type="attribute-resolver:ShibbolethAttributeResolver">
    <ConfigurationResource xsi:type="resource:SVNResource"
                           repositoryURL="http://svn.example.org/idp/prod/conf"
                           workingCopyDirectory="/opt/shibboleth-idp/svnconf"
                           resourceFile="attribute-resolver.xml"
                           revision="513">
        <ResourceFilter xsi:type="PropertyReplacement"
                        xmlns="urn:mace:shibboleth:2.0:resource"
                        propertyFile="/opt/idp/shibboleth-idp/conf/config.properties"/>
    </ConfigurationResource>
</Service>

<resolver:DataConnector id="myLDAP" 
                        xsi:type="LDAPDirectory"
                        xmlns="urn:mace:shibboleth:2.0:resolver:dc"
                        ldapURL="ldap://example.org" 
                        baseDN="ou=people,dc=example,dc=org"
                        principal="${ldap.principal}"
                        principalCredential="${ldap.credential}" >
    <FilterTemplate>(uid=$requestContext.principalName)</FilterTemplate>
</resolver:DataConnector>

ldap.principal = cn=idpserver,ou=services,dc=example,dc=org
ldap.credential = $uper$ecr3+

Multiple Property Files

In some cases it may be desirable to factor out configuration properties into several files; for example host-specific and tier-specific. The following configuration demonstrates how to configure resource filter components for that case.

 <Service id="shibboleth.AttributeResolver"
        xsi:type="attribute-resolver:ShibbolethAttributeResolver">
    <ConfigurationResource
            file="/opt/shibboleth-idp/conf/attribute-resolver.xml"
            xsi:type="resource:FilesystemResource">
        <ResourceFilter xsi:type="Chaining"
                  xmlns="urn:mace:shibboleth:2.0:resource">
            <ResourceFilter xsi:type="PropertyReplacement"
                            xmlns="urn:mace:shibboleth:2.0:resource"
                            propertyFile="/opt/shibboleth-idp/conf/idp.properties"/>
            <ResourceFilter xsi:type="PropertyReplacement"
                        xmlns="urn:mace:shibboleth:2.0:resource"
                        propertyFile="/home/idp/private/idp-env.properties"/>
        </ResourceFilter>
    </ConfigurationResource>
</Service>