/
PluginDevelopment

PluginDevelopment

Overview

Plugins are a mechanism to securely introduce function into an IdP in a manner which does not require lockstep versioning with the IdP. They do not include, by themselvesany configuration, but part of the functionality that they include can be (and usually is) one or more Modules.

The Plugin Installer and the IdP Installer work together to insert the plugin's content into the war file of a deployed IdP. A plugin adds functionality by arranging jar files to be included into the WEB-INF\lib folder of the war file.  Other resources are expected to be produced by enabling Modules and should usually be embedded within one of the plugin's jars.

Given that the war file is the only thing a plugin contributes to, configuration issues are out of scope for a plugin. Configuration management is delegated to the Module abstraction.

Contents

Formally, a plugin consists of four files which are usually made available via a fixed URL so as to allow for easy installation

  • A tar.gz file

  • A zip file

  • GPG signatures for the above

The layout of the tar or zip files is fixed.  A single top level folder may have any name and contains two or three sub folders:

  • webapp

    • Contains the contents which will be included into the war. There must be at least one jar file contained inside webapp\WEB-INF\lib  and the jar files in that folder must implement exactly one service of type net.shibboleth.idp.plugin.IdPPlugin

  • bootstrap

    • This folder:

      • MUST contain a file called plugin.properties.

        • This should be a property file with at least one property, "plugin.id".

        • The ID is used to locate the default truststore that verifies the GPG signature. The trust store will reside within a folder, named after the plugin ID, nested inside the IdP's credentials folder, e.g., idp.home/credentials/<pluginid>/truststore.asc

        • It must match the plugin ID that the plugin identifies itself with. By convention, plugin IDs are associated with the package name of the plugin to ensure uniqueness.

      • MAY contain a file called keys.txt  being the public key(s) used to sign the distribution. This enables the plugin installer to perform a one-time, "leap of faith" credentials check, and thereafter to prevent use of an unauthorized key.

  • Packages 5.2

    • This folder contains any tar.gz or .zip files which the plugin installer will unpack. See below

Building a Plugin

Given the constraints above you can use any mechanism you chose to build a plugin. However the format of the archive (and its signature) is conducive to being created automatically by maven and the IdP distribution contains support classes for constructing the service.

When doing this it is usual to have two subprojects.  One contains the code for the plugin and the other uses the output of the first to build the package.

Constructing the Service

The easiest way to construct a plugin service is to build a class derived from the PropertyDrivenIdPPlugin class. This uses a property file to implement the IdPPlugin interface.

Shibboleth Developers

Shibboleth developers ONLY use the subclass FirstPartyIdPPlugin which references the Shibboleth "standard property" file location that manages plugin compatibility metadata (https://shibboleth.net/downloads/identity-provider/plugins/plugins.properties), which is the only file in the java-idp-plugin-mgmt  project.

  • Build the implementing class by deriving it from the PropertyDrivenIdPPlugin class and supply the class as the parameter to the constructor.

The Service definition
package org.example; public class ExamplePlugin extends PropertyDrivenIdPPlugin { public ExamplePlugin () throws IOException, PluginException { super(ExamplePlugin .class); } }
  • Declare the class as a service by creating the /META-INF/services/net.shibboleth.idp.plugin.IdPPlugin file.

 /META-INF/services/net.shibboleth.idp.plugin.IdPPlugin
org.example.ExamplePlugin
  • Create the properties file used to implement the plugin service. This is a file in the same package as the implementing class and has the name plugin.properties 

plugin.id = org.example.ExamplePlugin # Only used when package manifest is not available, such as within Eclipse plugin.version = 1.0.0

The full list of properties is:

Property

Required?

What

Description

Property

Required?

What

Description

plugin.id

Y

Identifier

This is the unique identifier by which the plugin is described. It is used when manipulating the plugin (for instance doing an update).

NOTE
This file name and property name are purposely the same as required in the bootstrap location of the distribution. This enables one file to be used. See below.

plugin.version



two or three dot-separated numbers

This is current the version of the plugin. If configured correctly, the PropertyDrivenIdPPlugin class will use the version derived from the manifest of the containing jar to provide the version. This is a fallback if the manifest cannot be located.

plugin.license



location (in a jar file) of a text file

This is the (in jar) location of a file containing any licensing details. It is used only when the deployer requests it, and satisfies the spirit of providing the releva