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

Plugin

Plugin ID

Module(s)

Bug Reporting

Metadatagen

net.shibboleth.idp.plugin.metadatagen

idp.plugin.MetadataGen.plugin

idp.plugin.MetadataGen.Templates.plugin

https://shibboleth.atlassian.net/browse/JMETAGEN

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

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 <shibmd:Scope> element(s)

--sp

 

Generates an <md:SPSSODescriptor> role (this is the default)

--idp

 

Generates an <md:IDPSSODescriptor> role

--aa

 

Generates an <md:AttributeAuthorityDescriptor> role

--want-assertions-signed, -w

 

Toggles on the WantAssertionsSigned flag in SP metadata

--nameid-format, -f

Y

Populates <md:NameIDFormat> elements

--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 <md:SingleSignOnService> endpoint(s) (see below)

--attribute-query, --query

Y

Manually specifies <md:AttributeService> endpoint(s) (see below)

--artifact

Y

Manually specifies <md:ArtifactResolutionService> endpoint(s) (see below)

--logout

Y

Manually specifies <md:SingleLogoutService> endpoint(s) (see below)

--acs

Y

Manually specifies <md:AssertionConsumerService> endpoint(s) (see below)

--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 <mdui:DisplayName> extension element

--description, -d

 

Generates an <mdui:Description> extension element

--logo-url, --logo

 

Generates an <mdui:Logo> extension element (only external URI references supported)

--logo-width, --width

 

Sets Width attribute of <mdui:Logo> extension element

--logo-height, --height

 

Sets Height attribute of <mdui:Logo> extension element

--org-name, -o

 

Generates <md:OrganizationName> and <md:OrganizationDisplayName> elements

--org-url, -u

 

Generates <md:OrganizationURL> element

--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 <saml:Attribute> in an <mdattr:EntityAttributes> extension (note that this tool assumes all tags will have URI names)

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

Token

Protocol and Binding

Redirect

SAML 2.0, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

POST

SAML 2.0, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

SimpleSign

SAML 2.0, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign

Artifact

SAML 2.0, urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

SOAP

SAML 2.0, urn:oasis:names:tc:SAML:2.0:bindings:SOAP

PAOS

SAML 2.0, urn:oasis:names:tc:SAML:2.0:bindings:PAOS

POST1

SAML 1.1, urn:oasis:names:tc:SAML:1.0:profiles:browser-post

Artifact1

SAML 1.1, urn:oasis:names:tc:SAML:1.0:profiles:artifact-01

SOAP1

SAML 1.1, urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding

CAS

CAS, https://www.apereo.org/cas/protocol/login

CAS (logout)

CAS, https://www.apereo.org/cas/protocol/logout (location portion ignored)

CASProxy

CAS, https://www.apereo.org/cas/protocol/proxy

OIDC

OIDC/OAuth, https://tools.ietf.org/html/rfc6749#section-3.1.2

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 .