{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"_parentId":{"value":"1296760857"}},"macroMetadata":{"macroId":{"value":"eb43a41a-af2d-4422-a800-e0a729a00e9e"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"3e7f1e7d-7c15-4075-a0e1-c54f23120d14"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"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 themselves","type":"text"},{"text":", ","type":"text","marks":[{"type":"em"}]},{"text":"any configuration, but part of the functionality that they include can be (and usually is) one or more ","type":"text"},{"text":"Modules","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1294073986"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Plugin Installer","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/IDP4/pages/1294074003"}}]},{"text":" and the ","type":"text"},{"text":"IdP Installer","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/SHIB2/pages/2577596497"}}]},{"text":" 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 ","type":"text"},{"text":"WEB-INF\\lib","type":"text","marks":[{"type":"code"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Given that the war file is the ","type":"text"},{"text":"only","type":"text","marks":[{"type":"strong"}]},{"text":" thing a plugin contributes to, configuration issues are out of scope for a plugin. Configuration management is delegated to the Module abstraction.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Contents","type":"text"}]},{"type":"paragraph","content":[{"text":"Formally, a plugin consists of four files which are usually made available via a fixed URL so as to allow for easy installation","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A tar.gz file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A zip file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GPG signatures for the above","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The layout of the tar or zip files is fixed. A single top level folder may have any name and contains two sub folders:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"webapp","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Contains the contents which will be included into the war. There must be at least one jar file contained inside ","type":"text"},{"text":"webapp\\WEB-INF\\lib","type":"text","marks":[{"type":"strong"}]},{"text":" and the jar files in that folder ","type":"text"},{"text":"must","type":"text","marks":[{"type":"strong"}]},{"text":" implement exactly one service of type ","type":"text"},{"text":"net.shibboleth.idp.plugin.IdPPlugin","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.plugin.IdPPlugin"}}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"bootstrap","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This folder:","type":"text"},{"type":"hardBreak"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MUST contain a file called ","type":"text"},{"text":"plugin.properties","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This should be a property file with at least one property, \"plugin.id\".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"credentials","type":"text","marks":[{"type":"strong"}]},{"text":" folder, e.g., ","type":"text"},{"text":"idp.home/credentials//truststore.asc","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It ","type":"text"},{"text":"must","type":"text","marks":[{"type":"strong"}]},{"text":" 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.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MAY contain a file called ","type":"text"},{"text":"keys.txt","type":"text","marks":[{"type":"em"}]},{"text":" 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.","type":"text"}]}]}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Building a Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Constructing the Service","type":"text"}]},{"type":"paragraph","content":[{"text":"The easiest way to construct a plugin service is to build a class derived from the ","type":"text"},{"text":"PropertyDrivenIdPPlugin","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.plugin.PropertyDrivenIdPPlugin"}}]},{"text":" class. This uses a property file to implement the ","type":"text"},{"text":"IdPPlugin","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.plugin.IdPPlugin"}}]},{"text":" interface.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Shibboleth Developers","type":"text"}]},{"type":"paragraph","content":[{"text":"Shibboleth developers ","type":"text"},{"text":"ONLY","type":"text","marks":[{"type":"strong"}]},{"text":" use the subclass ","type":"text"},{"text":"FirstPartyIdPPlugin ","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.plugin.impl.FirstPartyIdPPlugin"}}]},{"text":"which references the Shibboleth \"standard property\" file location that manages plugin compatibility metadata (","type":"text"},{"text":"https://shibboleth.net/downloads/identity-provider/plugins/plugins.properties","type":"text","marks":[{"type":"link","attrs":{"href":"https://shibboleth.net/downloads/identity-provider/plugins/plugins.properties"}}]},{"text":"), which is the only file in the ","type":"text"},{"text":"java-idp-plugin-mgmt","type":"text","marks":[{"type":"code"}]},{"text":" project.","type":"text"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Build the implementing class by deriving it from the ","type":"text"},{"text":"PropertyDrivenIdPPlugin","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.plugin.PropertyDrivenIdPPlugin"}}]},{"text":" class and supply the class as the parameter to the constructor.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"The Service definition","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"package org.example;\npublic class ExamplePlugin extends PropertyDrivenIdPPlugin {\n public ExamplePlugin () throws IOException, PluginException {\n super(ExamplePlugin .class);\n }\n}","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Declare the class as a service by creating the /","type":"text"},{"text":"META-INF/services/net.shibboleth.idp.plugin.IdPPlugin","type":"text","marks":[{"type":"em"}]},{"text":" file.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":" /META-INF/services/net.shibboleth.idp.plugin.IdPPlugin","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"org.example.ExamplePlugin ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"plugin.properties","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"plugin.id = org.example.ExamplePlugin\n# Only used when package manifest is not available, such as within Eclipse\nplugin.version = 1.0.0","type":"text"}]},{"type":"paragraph","content":[{"text":"The full list of properties is:","type":"text"}]},{"type":"table","attrs":{"layout":"full-width","localId":"cb5d9cd3-2cc6-4776-91d0-f053657c0bcb"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[208.62]},"content":[{"type":"paragraph","content":[{"text":"Property","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.96]},"content":[{"type":"paragraph","content":[{"text":"Required?","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[154.98]},"content":[{"type":"paragraph","content":[{"text":"What","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[703.44]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[208.62]},"content":[{"type":"paragraph","content":[{"text":"plugin.id","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.96]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Y","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[154.98]},"content":[{"type":"paragraph","content":[{"text":"Identifier","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[703.44]},"content":[{"type":"paragraph","content":[{"text":"This is the unique identifier by which the plugin is described. It is used when manipulating the plugin (for instance doing an update).","type":"text"}]},{"type":"paragraph","content":[{"text":"NOTE","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"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 ","type":"text"},{"text":"below","type":"text","marks":[{"type":"link","attrs":{"href":"#PluginDevelopment-distribution"}}]},{"text":".","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[208.62]},"content":[{"type":"paragraph","content":[{"text":"plugin.version","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.96]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[154.98]},"content":[{"type":"paragraph","content":[{"text":"two or three dot-separated numbers","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[703.44]},"content":[{"type":"paragraph","content":[{"text":"This is current the version of the plugin. If configured correctly, the ","type":"text"},{"text":"PropertyDrivenIdPPlugin","type":"text","marks":[{"type":"link","attrs":{"href":"http://shibboleth.net/cgi-bin/java-idp.cgi/net.shibboleth.idp.plugin.PropertyDrivenIdPPlugin"}}]},{"text":" class will use the ","type":"text"},{"text":"version derived from the manifest ","type":"text","marks":[{"type":"link","attrs":{"href":"#PluginDevelopment-version"}}]},{"text":"of the containing jar to provide the version. This is a fallback if the manifest cannot be located.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[208.62]},"content":[{"type":"paragraph","content":[{"text":"plugin.license","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.96]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[154.98]},"content":[{"type":"paragraph","content":[{"text":"location (in a jar file) of a text file","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[703.44]},"content":[{"type":"paragraph","content":[{"text":"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 relevant licenses for a plugin.","type":"text"}]},{"type":"paragraph","content":[{"text":" plugin.sh --license org.example.shibbolethplugin.ExamplePlugin","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[208.62]},"content":[{"type":"paragraph","content":[{"text":"plugin.url.0","type":"text"},{"type":"hardBreak"},{"text":"plugin.url.1","type":"text"},{"type":"hardBreak"},{"text":"...","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.96]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Y","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[154.98]},"content":[{"type":"paragraph","content":[{"text":"URL","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[703.44]},"content":[{"type":"paragraph","content":[{"text":"These are the URLs where the plugin compatibility property files (below) are located. Multiple locations may be specified to allow for redundancy.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[208.62]},"content":[{"type":"paragraph","content":[{"text":"plugin.modules.required","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[90.96]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"type":"hardBreak"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[154.98]},"content":[{"type":"paragraph","content":[{"text":"Space-delimited list","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[703.44]},"content":[{"type":"paragraph","content":[{"text":"The names of any modules which need to be enabled before the plugin installer will install this plugin. This is the only sense in which plugins may \"depend\" on other plugins; it's the module(s) exposed by those plugins that are identified as required.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Constructing the Implementation Project","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}},{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"In constructing the POM for the implementation project, you need to pay attention to three aspects: dependency management, dependency collection (for use in building the package) and managing the version. The ","type":"text"},{"text":"Plugin Archetype","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/DEV/pages/1196393483"}}]},{"text":" may help.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Dependency Management","type":"text"}]},{"type":"paragraph","content":[{"text":"Any code you rely on from the IdP should be scoped \"provided\". You should avoid dependencies on impl modules.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Be careful in your use of IdP versions. In general you should build against the lowest version of the IdP that you support (i.e. the version you specify as ","type":"text"},{"text":"idpVersionMin","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Any code that you require to be shipped along with the plugin should be declared as \"compile\" or \"runtime\". Transitive dependencies of your plugin should ","type":"text"},{"text":"only","type":"text","marks":[{"type":"strong"}]},{"text":" be mentioned if they are not IdP-provided (philosophically, a provided jar cannot have a dependency since you are not providing it, you are relying on it). ","type":"text"},{"text":"However ","type":"text","marks":[{"type":"strong"}]},{"text":"you ","type":"text"},{"text":"must ","type":"text","marks":[{"type":"strong"}]},{"text":" mention those transitive dependencies of your plugin which are not supplied by the IdP installation and these should be scoped as \"runtime\".","type":"text"}]},{"type":"paragraph","content":[{"text":"This last is not only good hygiene (so you know what you are using) but also a requirement for dependency collection (see below).","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Dependency Collection","type":"text"}]},{"type":"paragraph","content":[{"text":"The following plugin stanza will copy the \"compile\" and \"runtime\" dependencies into a directory from which they can be collected by the distribution project.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n org.apache.maven.plugins\n maven-dependency-plugin\n \n \n copy-dependencies\n package\n \n copy-dependencies\n \n \n ${project.target.directory}\n runtime\n true \n \n \n \n ","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":4},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"version"},"_parentId":{"value":"1296760857"}},"macroMetadata":{"macroId":{"value":"032a30d7-fb85-435b-bc17-3ffa301bf1b9"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"0fc09b25-608e-457b-a5b8-24191d3b739e"}},{"text":"Managing the Version","type":"text"}]},{"type":"paragraph","content":[{"text":"The following plugin stanza will place the current version into the manifest,. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"it is ","type":"text"},{"text":"critical","type":"text","marks":[{"type":"strong"}]},{"text":" that the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" be the path to your plugin's package ","type":"text"},{"text":"and that it be terminated with a /","type":"text","marks":[{"type":"em"}]}]}]},{"type":"paragraph"},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":" \n org.apache.maven.plugins\n maven-jar-plugin\n \n \n \n ${automatic.module.name}\n \n \n \n org/example/\n \n ${project.artifactId}\n ${project.version}\n example.org\n \n \n \n \n \n ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"anchor","parameters":{"macroParams":{"":{"value":"distribution"},"_parentId":{"value":"1296760857"}},"macroMetadata":{"macroId":{"value":"2eaf8ba1-ecba-49d1-9fbd-f1ff0d5070d8"},"schemaVersion":{"value":"1"},"title":"Anchor"}},"localId":"77af524b-56e8-4ea4-b7b6-e55f22019238"}},{"text":"Constructing the Distribution Project","type":"text"}]},{"type":"paragraph","content":[{"text":"The distribution project is a simple \"pom\" package with one plugin - the assembly plugin to create the zip and tar.gz files.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Distribution Pom example","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n 4.0.0\n\n .....\n .....\n pom\n\n \n A project to \n \n\n \n .....-${project.version}\n \n\n \n \n \n \n maven-assembly-plugin\n \n \n make-assembly\n package\n \n single\n \n \n \n \n false\n \n src/main/assembly/plugin-assembly-tgz.xml\n src/main/assembly/plugin-assembly-zip.xml\n \n ${plugin.finalName}\n gnu\n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"The work is all done in the assembly files. This collects together at several groups of files into the package","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The webapp directory gets:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The jar file created by the implementation project","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The dependencies assembled by the implementation project","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Optionally, any other files which may need to do into the idp.war file","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The bootstrap directory gets:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The shared property file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Optionally, the file of keys associated with signing this distribution","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"The following example build the tar.gz. The zip version is similar, but may decide to preserve line endings for any rare text files.","type":"text"}]},{"type":"expand","attrs":{"title":"tar.gz assembly file"},"content":[{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n assembly-tgz\n \n tar.gz\n \n \n \n \n ../impl/target\n webapp/WEB-INF/lib\n \n XYZ-plugin-*.jar\n \n \n *test*.jar\n *javadoc.jar\n *sources.jar\n \n \n \n \n ../impl/target/dependency\n webapp/WEB-INF/lib\n \n *.jar\n \n \n *test*.jar\n *javadoc.jar\n *sources.jar\n \n \n \n \n ../impl/target/classes/org/example\n bootstrap\n \n plugin.properties\n \n \n \n \n src/main/resources/bootstrap\n bootstrap\n \n keys.txt\n \n \n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Maintaining the Update Property File","type":"text"}]},{"type":"paragraph","content":[{"text":"An important motivation for plugin development is avoiding lockstep deployment with IdP versions. Further it is important that a plugin's IdP depenedencies can change over time. The information which describes a plugin's state and dependency is therefore not included in the plugin; rather it contains a URL. The URL points to a property file which contains information about the plugin and its versions and their IdP compatibility.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"The plugin installer consults this URL to list all possible versions and their requirements (","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"plugin -fl plugin-id","type":"text","marks":[{"type":"code"}]},{"text":") but also (and more importantly) to select and automatically download the latest version of the plugin for the current IdP version (","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"plugin -u plugin-id","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph","content":[{"text":"Obviously this information can be changed at any time, allowing plugins to be retired or have their life extended.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph","content":[{"text":"One file may document multiple plugins and (of course) multiple versions of the plugin, so ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]},{"text":"all","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}},{"type":"strong"}]},{"text":" property names are prefixed by the plugin ID and per-version properties are postfixed by the version.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Properties","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"paragraph","content":[{"text":"The following properties should be provided:","type":"text","marks":[{"type":"textColor","attrs":{"color":"#000000"}}]}]},{"type":"table","attrs":{"layout":"full-width","localId":"8621c7c5-ca10-4cc0-a14c-bf4ff0a0fce4"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"What","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"PluginId.versions ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"Space separated list of versions (three dot-separated numbers)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"The versions of the plugin which are available. ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"PluginId.downloadURL.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"A URL","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"The \"directory\" part of the the location of this version of this plugin.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"PluginId.baseName.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"A file name","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"The \"root\" name of the four files which make up the plugin. The ","type":"text"},{"text":"downloadURL","type":"text","marks":[{"type":"code"}]},{"text":" is prepended and the four followig extension appended:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".tar.gz","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".tar.gz.asc","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".zip","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".zip.asc","type":"text"}]}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"PluginId.idpVersionMax.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"An IdP version (three dot-separated numbers)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"The first IdP version that this version of this plugin ","type":"text"},{"text":"will not ","type":"text","marks":[{"type":"strong"}]},{"text":"work with.","type":"text"},{"type":"hardBreak"},{"text":"(exclusive)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"PluginId.idpVersionMin.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"An IdP version (three dot-separated numbers)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"The first IdP version that this version of this plugin ","type":"text"},{"text":"will ","type":"text","marks":[{"type":"strong"}]},{"text":"work with.","type":"text"},{"type":"hardBreak"},{"text":"(inclusive)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[292.44]},"content":[{"type":"paragraph","content":[{"text":"PluginId.supportLevel.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[260.99]},"content":[{"type":"paragraph","content":[{"text":"One of","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Current","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"OutOfDate","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unsupported","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Secadv","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Withdrawn","type":"text"}]}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[604.57]},"content":[{"type":"paragraph","content":[{"text":"A description of the current status of this version of this plugin.","type":"text"}]},{"type":"paragraph","content":[{"text":"The only semantic associated is that the plugin verb will only consider plugins with support level of Current for automatic update.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Wildcarding the Version","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"dowloadURL","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"baseName","type":"text","marks":[{"type":"code"}]},{"text":" for versions managed by a Nexus repository are usually predictable given the version number. Hence a simplified wildcarding is allowed for these two property classes.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the property name contains the string ","type":"text"},{"text":"%{version","type":"text","marks":[{"type":"code"}]},{"text":"}, then properties for all declared version numbers will be defined with the ","type":"text"},{"text":"%{version","type":"text","marks":[{"type":"code"}]},{"text":"} string in both the property name and property value being replaced.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the property name for a specific version is defined elsewhere, then for that property and that version only the replacement does ","type":"text"},{"text":"not ","type":"text","marks":[{"type":"strong"}]},{"text":"take place.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Example","type":"text"}]},{"type":"codeBlock","content":[{"text":"org.example.ExamplePlugin.versions=1.1.0 1.0.0\norg.example.ExamplePlugin.downloadURL.%{version} = https://example.org/nexus/service/local/repositories/releases/content/org/example/exampleplugin/plugin-dist/%{version}\norg.example.ExamplePlugin.baseName.%{version} = plugin-dist-%{version}\n\norg.example.ExamplePlugin.idpVersionMax.1.1.0=5.0.0\norg.example.ExamplePlugin.idpVersionMin.1.1.9=4.1.0\norg.example.ExamplePlugin.supportLevel.1.1.0 = Current\n\norg.example.ExamplePlugin.idpVersionMax.1.0.0=4.2.0\norg.example.ExamplePlugin.idpVersionMin.1.10.9=4.1.0\norg.example.ExamplePlugin.supportLevel.1.0.0 = Withdrawn\n# Override basename for this version\norg.example.ExamplePlugin.baseName.1.0.0 = plugin-dist-old","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}