[role="xpack"]
[[saml-metadata]]
== saml-metadata

The `saml-metadata` command can be used to generate a SAML 2.0 Service Provider
Metadata file.

[float]
=== Synopsis

[source,shell]
--------------------------------------------------
bin/x-pack/saml-metadata
[--realm <name>]
[--out <file_path>] [--batch] 
[--attribute <name>] [--service-name <name>]
[--locale <name>] [--contacts]
([--organisation-name <name>] [--organisation-display-name <name>] [--organisation-url <url>])
[-E <KeyValuePair>]
[-h, --help] ([-s, --silent] | [-v, --verbose])
--------------------------------------------------

[float]
=== Description

The SAML 2.0 specification provides a mechanism for Service Providers to
describe their capabilities and configuration using a _metadata file_.

The `saml-metadata` command generates such a file, based on the configuration of
a SAML realm in {es}.

Some SAML Identity Providers will allow you to automatically import a metadata
file when you configure the Elastic Stack as a Service Provider.

[float]
=== Parameters

`--attribute <name>`:: Specifies a SAML attribute that should be
included as a `<RequestedAttribute>` element in the metadata. Any attribute
configured in the {es} realm is automatically included and does not need to be
specified as a commandline option.

`--batch`:: Do not prompt for user input.

`--contacts`:: Specifies that the metadata should include one or more
`<ContactPerson>` elements. The user will be prompted to enter the details for
each person.

`-E <KeyValuePair>`:: Configures an {es} setting.

`-h, --help`:: Returns all of the command parameters.

`--locale <name>`:: Specifies the locale to use for metadata elements such as
`<ServiceName>`. Defaults to the JVM's default system locale.

`--organisation-display-name <name`:: Specified the value of the
`<OrganizationDisplayName>` element.
Only valid if `--organisation-name` is also specified.

`--organisation-name <name>`:: Specifies that an `<Organization>` element should
be included in the metadata and provides the value for the `<OrganizationName>`.
If this is specified, then `--organisation-url` must also be specified.

`--organisation-url <url>`:: Specifies the value of the `<OrganizationURL>`
element. This is required if `--organisation-name` is specified.

`--out <file_path>`:: Specifies a path for the output files.
Defaults to `saml-elasticsearch-metadata.xml`

`--service-name <name>`:: Specifies the value for the `<ServiceName>` element in
the metadata. Defaults to `elasticsearch`.

`--realm <name>`:: Specifies the name of the realm for which the metadata
should be generated. This parameter is required if there is more than 1 `saml`
realm in your {es} configuration.

`-s, --silent`:: Shows minimal output.

`-v, --verbose`:: Shows verbose output.

[float]
=== Examples

The following command generates a default metadata file for the `saml1` realm:

[source, sh]
--------------------------------------------------
bin/x-pack/saml-metadata --realm saml1
--------------------------------------------------

The file will be written to `saml-elasticsearch-metadata.xml`.
You may be prompted to provide the "friendlyName" value for any attributes that
are used by the realm.

The following command generates a metadata file for the `saml2` realm, with a
`<ServiceName>` of `kibana-finance`, a locale of `en-GB` and includes 
`<ContactPerson>` elements and an `<Organization>` element:

[source, sh]
--------------------------------------------------
bin/x-pack/saml-metadata --realm saml2 \
    --service-name kibana-finance \
    --locale en-GB \
    --contacts \
    --organisation-name "Mega Corp. Finance Team" \
    --organisation-url "http://mega.example.com/finance/"
--------------------------------------------------