IdP Extension Development

Since Shibboleth 1.2 it has been possible to create custom code, such as custom data connectors for attribute resolution, to extend the out-of-the-box functionality of the Shibboleth IdP. With the release of version 1.3 of the IdP the number of extensions points has grown significantly (see list below) and with it the need for a mechanism that would make it easy to build and include custom code with an IdP installation. Shibboleth 1.3 now offers this functionality.

Extending the IdP

Extensions to the Shibboleth !IdP should be placed in individual directories within the custom directory found in the Shibboleth IdP source tree. Each such extension directory is required to have a particular layout, so that the build file knows where to look for things like source code, configuration files, libraries, etc. Once this directory is created, all that is required is to execute a normal IdP install by running ./ant install (or simply ./ant) and responding to the prompts. For a complete description of the extension directory layout and what's created or destroyed by the build process, refer to the README.txt file within the custom directory.

Shibboleth extension developers are encouraged to submit their favorite ExtensionTipsAndTricks to the community.

IdP Extension Points

Data Connectors - Data connectors are likely to be the most common extensions for the average IdP install. Shibboleth supports the most common data stores (i.e., LDAP directories and relational databases) but organizations will likely find that some of their data is located elsewhere, such as flat files, proprietary administrative systems, etc. A custom data connector allows organizations to access these data sources. Such a connector would be configured by way of the CustomDataConnector element in the attribute resolver configuration file resolver.xml.

Release Policy Engine - It's highly unlikely that the majority of organizations would ant to modify the engine that interprets Attribute Release Policies, but it is possible to do so. A custom policy engine would be configured by way of the ReleasePolicyEngine element in the IdP's configuration file.

Name Mapper - The IdP Name Mapper is responsible for creating handles from the authenticated user's principal name and translating the handle back to the principal name. In the standard browser based usage of Shibboleth the SSO service associates the local principal with a SAML NameIdentifier. The attribute authority service uses the Name Mapper to map the NameIdentifier back to the corresponding principal name during an attribute request. A custom Name Mapper is an implementation of the NameIdentifierMapping interface and is configured by way of the NameMapping element in the IdP's configuration file. It is likely that organizations that use something other than ordinary userid/password pairs to authenticate users would need to implement a special Name Mapper.

Artifact Mapper - The Artifact Mapper is responsible for creating, and later resolving, artifacts from/to SAML assertions. A custom Artifact Mapper would be configured by way of the ArtifactMapper element in the IdP's configuration file.

Credential Resolver - This is another item that the majority of organizations will likely not customize. Currently, Shibboleth components (IdPs and SPs) authenticate and secure communications with each other by way of digital certificates. The Credential Resolver is responsible for loading these certificates. A custom Credential Resolver would be configured by way of the CustomResolver element in the IdP's configuration file.

Protocol Handler - Protocol Handlers are responsible for taking incoming SAML requests and operating on them. The standard Protocol Handlers are responsible for handling SAML authentication requests (the SSO handler), attribute queries (the AA handler), and artifact resolution (the Artifact handler). A custom Protocol Handler would be configured by way of the ProtocolHandler element in the IdP's configuration file.

Web UI Pages - The web UI pages consist of things like the error pages and the handle processing page. To override these pages simply create a page, with the same name as the page you want to replace, in the "web" directory of the extension. Then add your content and regenerate the Shibboleth WAR file. NOTE: If more than one extension overrides the same page then there is no way to determine which page will be used.