Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Overview

Plugins are a mechanism to install non-default functionality into the IdP from signed release distribution packages.

Plugins:

  • Are distinguished from each other by a unique identifier in the style of a Java package name.

  • Are revised on a different schedule to the IdP itself, so upgrading the IdP does not upgrade a plugin and equally upgrading a plugin does not affect the IdP. Often, significant IdP upgrades may require plugin upgrades, but the operations are distinct.

  • Must be GPG signed.

  • May be installed and updated directly from a web-hosted file or from a local file (with associated signature).

  • Generally have no configuration that it directly installs, leaving this to the Module layer to manage.

  • May require one or more Modules to be enabled before they can be installed, this being indicated by the plugin developer.

  • May automatically enable a Module on install and/or disable a Module on uninstall, this being indicated by the plugin developer.

It is usual that a plugin contains one or more Modules, so the usual way to add functionality via a plugin is to install the plugin, then enable the module (if not already done for you) and then complete any per-module configuration.

We maintain a directory of known plugins.

Plugin Versioning and IdP Versioning

The developer of the plugin defines the minimum (inclusive) and maximum (exclusive) IdP versions that the plugin can operate with. This information is not distributed with the plugin; instead, the plugin package points to a URL (or redundant URLs) where the information is contained. This allows the plugin developer to change the supported status or the compatibility bounds of a particular plugin version after it has been released and installed based on testing and unexpected changes to the IdP.

The goal is not a bulletproof, perfectly-working-at-all times system because that's impossible, but it will allow for clear command-line driven determinations of the likely compatibility situation at any given time and a means to update a non-working system to a more-working system despite independent code streams.

Example of Versioning

Version 1.0 of a plugin is released and the minimum IdP version is specified as 4.1.0 and the maximum as 5.0.0  This means that the plugin will only work when the IdP is at version V4.1.0 or later and will fail to work if the IdP is updated to V5.0.0.  During the development of IdP V5 the plugin developer establishes that the plugin will continue work with version 5.x and so they dynamically change the maximum to 6.0.0.  No changes are required by the deployer and the plugin continues to work even after an upgrade to IdP V5.0.0

The IdP plugin developer then develops version 1.2 of the Plugin which requires at least version 4.2.0 This is released and the versions specified for this version are 4.2.0 and 6.0.0.

At any time the Plugin developer can change the status of any released plugin from Supported (current) to 

  • OutOfDate: Still working but a new version is available

  • Unsupported: Out of Support

  • Secadv: Security alerts exist against this plugin

  • Withdrawn

There are no semantics associated with these beyond that only Supported versions are candidates for automatically selected update. The other states are there as (dynamic) guidance from the developer to the deployer of the state of the plugin.

GPG Trust

In order for a plugin to be installed, the distribution must be accompanied by a GPG signature. The installation process checks the correctness of this signature before it does any installation or other potentially dangerous operations. Before it can do this check, the public key needs to be available to the plugin command in a trust store.   By default each plugin has its own trust store. This means that the trust surrounding one plugin cannot be subverted to allow another plugin to be installed. Alternatively the --truststore qualifier to the plugin command can be used to point to a central store (which you are expected to maintain).

The default location for a plugin is derived from the "pluginId" as:

%{idp.home}/credentials/<pluginId>/truststore.asc

This is a user-editable file you may delete or add to as you wish.

A plugin author may chose to ship signing key(s) with the plugin. If the key is not found in the trust store during the signature check, then you will be prompted to optionally install it:

INFO  - TrustStore does not contain signature 0X1483F262A4B3FF0
Accept this Key:
Signature:      0X1483F262A4B3FF0
FingerPrint:    4AF4D83EEDDF43DA3C06CB3101483F262A4B3FF0
Username:       Rod Widdowson <rdw@steadingsoftware.com>
 [yN]

Note that the default operation it to refuse to install the key.

The 'plugin' Command

All plugin manipulation (except trust store maintenance) is done via the plugin command. Operations fall into 2 broad categories.

Plugin Discovery and Automated Installation

Information about plugins is always kept separate from the plugin itself. This same information can be used to discover which plugins are available at a given URL. The -L will list them. This defaults to using the URL which is shared by all plugins developed by the Shibboleth Team (and documented here). The --updateURL allows other locations to be used.

Given the ID of a plugin (from the -L qualifier) it can be installed with the -I qualifier.

Manual Install, Update, and Uninstall

Installation (specified by the -i  or --input qualifier, immediately followed by the file name or URL) either installs a plugin or updates/downgrades it to a provided version.  

Update (specified by the  -u  or --update qualifier, followed by the plugin id) consults the remote location to find the best version to update the plugin to. If it finds one, it automatically downloads it, checks the signature and installs it (think apt/yum update).

Uninstall (specified by the  -r  or --remove qualifier, followed by the plugin id) removes the plugin from the IdP, generally including disabling Module(s) at the same time. It does not touch the truststore.

Queries

Qualifiers exist to:

  • List which plugins are installed

  • Provide details about available versions of existing plugins

  • Output the license information for the plugin

  • Detail the content that the plugin installed

Operation Qualifiers

These define which operation to perform.

Short

Long

Parameter

Description

-i

--install

File Or URL

Install the provided qualifier

-u

--update

PluginId

Update installed plugin

-r

--remove

PluginId

Remove the installed plugin

-l

--list

Enumerate all installed plugins

-fl

--full-list

Give full version details for all installed plugins

-cl

--contents-list

PluginId

List all files installed by the specified plugin

-L

--list-available

List available plugins (i.e discover plugins which can be downloaded and installed)
Use --updateURL to specify the source for plugins not provided by the Shibboleth Project

-I

--install-ID

PluginId

Install plugin from its ID. The plugin should be available at the default endpoint (or that specified by --updateURL)

--noCheck

Do not check for compatibility with the current IdP Version

--updateURL

Specify the update URL (for -L, -I or to override the plugin provided value)

--license

PluginId

Output the license information for the specified plugin

Other Qualifiers

These provide extra/advanced options for the command:

Short

Long

Parameter

Description

--verbose

Verbose logging

--quiet

Quiet logging

--logConfig

a logback file

Specify a file to use to control the logging of the plugin command

--version

Output the version of the plugin command

--propertyFiles

file list

Any property files that are to be included when parsing a Spring file input (see below)

--noPrompt

Use for unattended installs. If specified the install will fail rather than require input.

--truststore

Path to the (non default) trust store file used during installs and updates. See above.

--noRebuild

If set then the war file is not rebuilt after the installation.

-fu

--force-update

Version

Used with the -u qualifier to force the update (or downgrade) to a specific version

-hc

--http-client

Bean ID

Allows specification of an HTTP client bean used to download updates (or perform any related Module operation).

For details on wiring up a client bean, refer to the HttpClientConfiguration topic.

-hs

--http-security

Bean ID

Only used if the plugin installer needs to invoke a module operation, and allows security customization of the HTTP operation(s).

Optional Parameter

Finally the plugin command can take one additional bare parameter - the path to a file which contains any native Spring bean definitions that may be needed. This is typically only required for the -hc  and -hs qualifiers to perform advanced customization of HTTP operations, and should be rare.

Using an HTTP proxy is the only typical case where this should be needed, e.g.:

Example HTTP Client with proxy settings
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:context="http://www.springframework.org/schema/context"
	xmlns:util="http://www.springframework.org/schema/util"
    xmlns:p="http://www.springframework.org/schema/p"
	xmlns:c="http://www.springframework.org/schema/c"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"

	default-init-method="initialize" default-destroy-method="destroy">

    <bean id="customHttpClient" parent="shibboleth.HttpClientFactory"
        p:connectionProxyHost="proxy.example.org"
        p:connectionProxyPort="80" />

</beans>

Examples

Install from a file
/idp/bin$ ./plugin.sh -i  /mnt/h/Perforce/Juno/New/plugins/java-idp-plugin-scripting/rhino-dist/target/shibboleth-idp-plugin-rhino-0.1.4-SNAPSHOT.tar.gz
INFO  - TrustStore does not contain signature 0X1483F262A4B3FF0
Accept this Key:
Signature:      0X1483F262A4B3FF0
FingerPrint:    4AF4D83EEDDF43DA3C06CB3101483F262A4B3FF0
Username:       Rod Widdowson <rdw@steadingsoftware.com>
 [yN]yINFO  - Installing Plugin net.shibboleth.idp.plugin.rhino version 0.1.4
INFO  - Rebuilding /home/rdw/idp/war/idp.war, Version 4.1.0-SNAPSHOT
INFO  - Initial populate from /home/rdw/idp/dist/webapp to /home/rdw/idp/webpapp.tmp
INFO  - Overlay from /home/rdw/idp/dist/plugin-webapp to /home/rdw/idp/webpapp.tmp
INFO  - Overlay from /home/rdw/idp/edit-webapp to /home/rdw/idp/webpapp.tmp
INFO  - Creating war file /home/rdw/idp/war/idp.war

rdw@DELL10:~/idp/bin$ ./plugin.sh -l
Plugin: net.shibboleth.idp.plugin.rhino Current Version: 0.1.4
rdw@DELL10:~/idp/bin$ ./plugin.sh -cl net.shibboleth.idp.plugin.rhino
/home/rdw/idp/dist/plugin-webapp/WEB-INF/lib/idp-plugin-rhino-impl-0.1.4-SNAPSHOT.jar
/home/rdw/idp/dist/plugin-webapp/WEB-INF/lib/idp-plugin-scripting-api-0.1.4-SNAPSHOT.jar
/home/rdw/idp/dist/plugin-webapp/WEB-INF/lib/rhino-1.7.13.jar
rdw@DELL10:~/idp/bin$
Full list of installed plugins
/idp/bin$ ./plugin.sh -fl
Plugin: net.shibboleth.idp.plugin.rhino Current Version: 0.1.4
        Versions
        0.1.3:  Min=4.1.0       Max=5.0.0       Support level: Withdrawn
Discover and automated install 4.2
rdw@DELL10:~/idp/bin$ ./plugin.sh  -L
Plugin net.shibboleth.idp.plugin.rhino: version 1.1.0 available for install
Plugin net.shibboleth.idp.plugin.authn.duo.sdk: version 1.1.1 available for install
Plugin net.shibboleth.idp.plugin.authn.totp: version 1.0.0 available for install
Plugin net.shibboleth.idp.plugin.oidc.op: version 3.0.1 available for install
Plugin net.shibboleth.idp.plugin.metadatagen: version 0.1.1 available for install
Plugin net.shibboleth.idp.plugin.authn.duo.nimbus: version 1.1.1 available for install
Plugin net.shibboleth.idp.plugin.nashorn: Installed version 1.1.0: No update available
Plugin net.shibboleth.oidc.common: version 1.1.0 available for install
rdw@DELL10:~/idp/bin$ ./plugin.sh  -I net.shibboleth.idp.plugin.authn.totp
.....
rdw@DELL10:~/idp/bin$ ./plugin.sh  -l
Plugin: net.shibboleth.idp.plugin.nashorn       Current Version: 1.1.0
Plugin: net.shibboleth.idp.plugin.authn.totp    Current Version: 1.0.0

  • No labels