Metadatagen
The latest release (and future releases) of this plugin are incompatible with the command line options in the original 1.0 version, as the purpose of this tool has shifted dramatically from the original release. While the options are different, the new version is a strict superset of the capabilities of the original version.
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
You can the install the latest plugin version supported on your IdP version with .\plugin.sh -I net.shibboleth.idp.plugin.metadatagen
Plugin | Plugin ID | Module(s) | Bug Reporting |
---|---|---|---|
Metadatagen | net.shibboleth.idp.plugin.metadatagen | idp.plugin.MetadataGen.plugin idp.plugin.MetadataGen.Templates.plugin |
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.
Paremeter | Multiple? | Description |
---|---|---|
--file, --out |
| Output file to write to (stdout is used if not specified) |
--batch-file, --batch |
| Path to a batch file of individual commands to execute (see section below) |
--omit-namespaces |
| Prevents the generation of various XML namespace declarations in the root element, useful mainly for batches |
--entityID, --client_id, --id |
| Populates the entityID attribute, generally required to produce meaningful output |
--scope | Y | Populates |
--sp |
| Generates an |
--idp |
| Generates an |
--aa |
| Generates an |
--want-assertions-signed, -w |
| Toggles on the |
--nameid-format, -f | Y | Populates |
--certificate, --cert, -c | Y | Path to certificate file(s) intended for dual use (both signing and encryption) |
--signing, -x | Y | Path to certificate file(s) specific to signing only |
--encryption, -e | Y | Path to certificate file(s) specific to encryption only |
--sso | Y | Manually specifies |
--attribute-query, --query | Y | Manually specifies |
--artifact | Y | Manually specifies |
--logout | Y | Manually specifies |
--acs | Y | Manually specifies |
--layout-file, --layout |
| Path to a “layout template”, in effect a fragment of metadata containing an <md:EntityDescriptor> that specifies the endpoints to populate the output with (used in conjunction with the --hostname option) |
--hostname, -h | Y | Specifies the hostname(s) to plug into the layout template specified with the --layout-file option |
--lang |
| Language tag to use for any i18n-supporting elements |
--display-name, -y |
| Generates an |
--description, -d |
| Generates an |
--logo-url, --logo |
| Generates an |
--logo-width, --width |
| Sets |
--logo-height, --height |
| Sets |
--org-name, -o |
| Generates |
--org-url, -u |
| Generates |
--contact-admin, -a | Y | Splits a string containing first/last/email on the forward slash character and generates a <md:ContactPerson> of the “administrative” type |
--contact-support, -s | Y | Splits a string containing first/last/email on the forward slash character and generates a <md:ContactPerson> of the “support” type |
--contact-tech, -t | Y | Splits a string containing first/last/email on the forward slash character and generates a <md:ContactPerson> of the “technical” type |
--entity-attr, --tag | Y | An expression of the form “name=value”, which will generate a |
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:
Token | Protocol and Binding |
---|---|
Redirect | SAML 2.0, |
POST | SAML 2.0, |
SimpleSign | SAML 2.0, |
Artifact | SAML 2.0, |
SOAP | SAML 2.0, |
PAOS | SAML 2.0, |
POST1 | SAML 1.1, |
Artifact1 | SAML 1.1, |
SOAP1 | SAML 1.1, |
CAS | CAS, |
CAS (logout) | CAS, |
CASProxy | CAS, |
OIDC | OIDC/OAuth, |
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:
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
Location="https://webauth.example.org/idp/profile/SAML2/Redirect/SSO"
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
$ metadatagen.sh --lang US-en \
--logo https://idp.example.org/logo.png \
--logo-width 128 \
-o "Example & Org" \
-u "https://example.org?foo=bar&foo=baz" \
-a /Bono/ \
-t John/Doe/mailto\:doe@example.org \
--contact-support "Help & Desk//support@example.org" \
--sp -w \
--nameid-format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress \
--idp \
--aa \
--entityID https://sp.example.org \
--scope example.org \
--cert /Users/example/Desktop/webauth.crt \
--sso Redirect1/idp.example.org/idp/profile/SAML/SSO/Redirect \
--sso Redirect/idp.example.org/idp/profile/SAML2/SSO/Redirect \
--sso POST/idp.example.org/idp/profile/SAML2/SSO/POST \
--sso SOAP/idp.example.org/idp/profile/SAML2/SSO/SOAP \
--query SOAP/idp.example.org:8443/idp/profile/SAML2/AttributeQuery/SOAP \
--query SOAP1/idp.example.org:8443/idp/profile/SAML/AttributeQuery/SOAP \
--logout Redirect/sp.example.org/Shibboleth.sso/SLO/Redirect \
--logout Artifact/sp.example.org/Shibboleth.sso/SLO/Artifact \
--acs POST1/sp.example.org/Shibboleth.sso/SAML/POST \
--acs POST/sp.example.org/Shibboleth.sso/SAML2/POST \
--acs POST/sp2.example.org/Shibboleth.sso/SAML2/POST \
--acs PAOS/sp.example.org/Shibboleth.sso/SAML2/ECP \
--tag urn:oasis:names:tc:SAML:profiles:subject-id:req=subject-id
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.
--lang US-en
--logo https://idp.example.org/logo.png
--logo-width 128
-o Example\ &\ Org
-u https://example.org?foo=bar&foo=baz
-a /Bono/
-t John/Doe/mailto:doe@example.org
--contact-support Help\ &\ Desk//support@example.org
--sp -w
--idp
--aa
--entityID https://sp.example.org
--scope example.org
--nameid-format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
--cert /Users/scantor/Desktop/webauth2.crt
--sso Redirect1/idp.example.org/idp/profile/SAML/SSO/Redirect
--sso Redirect/idp.example.org/idp/profile/SAML2/SSO/Redirect
--sso POST/idp.example.org/idp/profile/SAML2/SSO/POST
--sso SOAP/idp.example.org/idp/profile/SAML2/SSO/SOAP
--query SOAP/idp.example.org:8443/idp/profile/SAML2/AttributeQuery/SOAP
--query SOAP1/idp.example.org:8443/idp/profile/SAML/AttributeQuery/SOAP
--logout Redirect/sp.example.org/Shibboleth.sso/SLO/Redirect
--logout Artifact/sp.example.org/Shibboleth.sso/SLO/Artifact
--acs POST1/sp.example.org/Shibboleth.sso/SAML/POST
--acs POST/sp.example.org/Shibboleth.sso/SAML2/POST
--acs POST/sp2.example.org/Shibboleth.sso/SAML2/POST
--acs PAOS/sp.example.org/Shibboleth.sso/SAML2/ECP
--tag urn:oasis:names:tc:SAML:profiles:subject-id:req=subject-id
.