Metadatagen

Overview

The MetadataGen plugin provides a command line utility to generate SAML metadata based on a variety of potential inputs. It can handle several different metadata “roles” but is primarily expected to be useful in generating SP metadata. It is a Java-based port of some of the features of the metagen.sh shell script that was included with the SP software. Porting it to Java allows the utility to be portable to Windows and makes it a bit easier to maintain, albeit with the overhead of a plugin release.

The previous release of this plugin was centered around replicating the functionality of the IdP installer to allow the IdP configuration to be introspected to a limited degree to produce example metadata for the IdP itself. This version is more generic, and does not have any particular knowledge of the IdP itself. It is still delivered as an IdP plugin simply to facilitate delivery and installation of the code, and because a tool like this can be very helpful in managing a Shibboleth IdP deployment.

This utility is actually a wrapper around a generic metadata generation API added to OpenSAML. It relies on the Velocity template language to plug its inputs into a set of templates inside the library that contain the general structure of various metadata elements. For enhanced customization, it is an option to install these templates to disk and edit them (or point to an entirely different set).

There are a number of command line options to control metadata generation, spanning the roles to generate, protocols to support, various means of specifying enpdoints, and an advanced “batch” option allowing multiple invocations of the tool via a single process without the overhead of running Java every time.

There is some limited support at present for generating CAS metadata, and even less so for generating OIDC/OAuth metadata, but we hope to improve the latter over time. Both are limited to SP/RP roles only.

Plugin Installation

Command Line Options

Notably, none of the options are actually required, as the tool is quite laissez-faire about what it’s generating. While it is designed to the extent possible to produce well-formed XML, it is not inherently attempting to produce valid metadata in either a schema sense or in a “this is sensible to use” sense. It simply does what it’s told to do, and leaves out anything that isn’t specified.

The options are also case-insensitive (most of our CLI tools are not).

Take care to wrap options containing whitespace in double quotes. The generator will automatically encode any XML-unsafe characters, so you should not pre-encode any of them.

The full set of options can be viewed with the --help option.

Endpoint Expressions

Various manual options for specifying the endpoints to generate (e.g., --sso, --logout, --acs, etc.) rely on built-in “tokens” that represent the various protocols and bindings supported by the tool, to simplfy expressing these parameters. While bindings are in principle extensible, the set is generally known at this point and isn’t changing substantially. Notably, the layout template feature (see below) can also handle any possible endpoints not already supported by this tool.

Endpoint expressions are in the form <binding>/<location>. The location portion may contain a scheme, or if none, the “https://” scheme will be applied automatically. The binding portion must be one of the following values:

Note that when endpoints require an index attribute, the generator will auto-generate those values by tracking them and incrementing the index. The indexes should not in general be used at runtime at thie point.

Endpoint Example

The parameter --sso Redirect/webauth.example.org/idp/profile/SAML2/Redirect/SSO will produce this endpoint:

Using a Layout Template

A layout template is an alternative means of specifying the endpoints to generate by supplying an <md:EntityDescriptor> in a file in which the endpoint elements' Location values contain the replacement string "${hostname}", into which the generator will plug in the value(s) of the --hostname parameter in a loop to produce the desired endpoints.

There are some exceptions to the iteration process; some endpoints (particularly non-SP endpoints) that are by design assumed to appear only once per Binding are only output using the first --hostname option supplied.

After installation, an editable example is provided under conf/examples/shibmd-layout.xml that illustrate how this works, and provide a starting point to copy from that includes the “default” endpoints used by the Shibboleth IdP and SP software. One should not ordinarily use it directly, but should copy/edit it to exclude anything unneeded for one’s use.

Batch Use

In order to allow for batching, without the overhead of a separate Java process for each command (as would occur if a real shell script was used), the tool supports the processing of simple batches of commands loaded from a single file. At present, this is a fairly primitive mechanism as it does not allow for shell variables and other sorts of tricks that would make authoring batches more convenient.

Batches are essentially sets of command line options, either one per line, or separated by whitespace, that are terminated by a single period plus line feed, or by the end of the file. Each batch is parsed into a new command line fed into the tool and the output is captured in a single stream that is wrapped by a surrounding (unnamed) <md:EntitiesDescriptor> tag. The “--omit-namespaces” option is also passed into each subcommand so that the namespaces can be declared only once, on the root element.

A limited form of escaping is permitted, with the backslash character (\) delineating a literal character to add into the command line.

Examples

Example Command Line

Example Batch File

Below is a single “command” to run. Any number can be added to a file, with the period terminator separating the commands. In principal, a shell script could be used to generate these commands, of course, which would recover some of the fancier substitution ability of the shell.