Sun Java System SAML v2 Plug-in for Federation Services User's Guide

The saml2meta Command-line Reference

The SAML v2 Plug-in for Federation Services contains the saml2meta command-line interface to manage metadata and circles of trust. It is located in /AccessManager-base/product-directory/saml2/meta or /FederationManager-base/SUNWam/saml2/meta.

The saml2meta syntax is:

saml2meta [-i staging-directory] import -u user-DN [-w password | -j password-file] [-r realm]
 [-m XML-file-name] [-x XML-file-name] [-t COT_name]
saml2meta [-i staging-directory] export -u user-DN [-w password | -j password-file] [-r realm]
 -e entityID [-n] [ -m  XML-file-name] [-x XML-file-name]
saml2meta [-i staging-directory] template -u user-DN [-w password | -j password-file]
 [-e entityID] [-s metaAlias [-a certAlias] [-f certAlias]] [-d metaAlias
 [-b certAlias] [-g certAlias]] -m XML-file-name -x XML-file-name
saml2meta [-i staging-directory] delete -u user-DN [-w password | -j password-file]
 [-r realm] [-e entityID] [-c]
saml2meta [-i staging-directory] list -u user-DN [-w password | -j password-file]
saml2meta [-i staging-directory] cotcreate -u user-DN [-w password | -j password-file]
 [-t COT-name] [-p prefix-URL] [-l entity-ID, entity-ID, ...]
saml2meta [-i staging-directory] cotdelete -u user-DN [-w password | -j password-file]
 [-t COT-name]
saml2meta [-i staging-directory] cotadd -u user-DN [-w password | -j password-file]
 [-t COT-name] [-e entityID]
saml2meta [-i staging-directory] cotremove -u user-DN [-w password | -j password-file]
 [-t COT-name] [-e entityID]
saml2meta [-i staging-directory] cotmember -u user-DN [-w password | -j password-file]
 -t COT-name
saml2meta [-i staging-directory] cotlist -u user-DN [-w password | -j password_file]
saml2meta -V
saml2meta -?

where:

-i

Specifies the directory for the web application staging area. For example, /var/opt/SUNWam/fm/war-staging on Federation Manager.


Note –

This option is specific only to instances of the SAML v2 Plug-in for Federation Services installed on Federation Manager.


-u or --runasdn

Specifies the full distinguished name of the user running the command. 

-w or --password

Specifies the password of the user running the command. 

-j or --passwordfile

Specifies the name of the file that contains the password of the user running the command. 

-r or --realm

Specifies the realm or organization under which the metadata is stored. If not defined, the default value is the root realm or organization. 

-m or --metadata

Specifies a file name for the standard configuration. 


Note –

In most subcommands, either -m or -x must be used. Both can also be used.


-x or --extended

Specifies a file name for the extended configuration. 


Note –

In most subcommands, either -m or -x must be used. Both can also be used.


-e or --entityid

Specifies an entity identifier, if applicable. 

-s or --serviceprovider

Specifies a metaAlias for the hosted service provider being created. The metaAlias is used to locate the provider's entity identifier and the organization in which it is located. The value is a string equal to the realm or organization name (dependent on whether the SAML v2 Plug-in for Federation Services is installed in Access Manager or Federation Manager) coupled with a forward slash and the provider name. For example, /suncorp/travelprovider.


Caution – Caution –

The strings used in the metaAlias values must not contain a /.


-a or --spcertalias

Specifies a certificate alias for the hosted service provider to be created. 

-f or --specertalias

Specifies an encrypted certificate alias for the hosted service provider to be created.  

-d or --identityprovider

Specifies a metaAlias for the hosted identity provider being created. The metaAlias is used to locate the provider's entity identifier and the organization in which it is located. The value is a string equal to the realm or organization name (dependent on whether the SAML v2 Plug-in for Federation Services is installed in Access Manager or Federation Manager) coupled with a forward slash and the provider name. For example, /suncorp/hr.


Caution – Caution –

The strings used in the metaAlias values must not contain a /.


-b or --idpcertalias

Specifies a certificate alias for the hosted identity provider to be created. 

-g or --idpecertalias

Specifies an encrypted certificate alias for the hosted identity provider to be created. 

-n or --sign

Signs the exported XML file. 

-c or --extendedonly

Deletes extended configurations only. 

-t or --cot

Specifies the name of a circle of trust. 

-p or --prefix

Specifies the full path to where the SAML v2 IDP Discovery Service is deployed. 

-l or --trustedproviders

Specifies a list of trusted providers in a circle of trust. Input is a comma-separated list of entity identifiers. 

-V

Displays version information. 

-?

Displays help information. 


Note –

To access usage information on the command-line, change to /AccessManager-base/product-directory/saml2/bin or /FederationManager-base/SUNWam/saml2/bin and run saml2meta with no input.


For explanations of the saml2meta subcommands, see the:

Managing Metadata using saml2meta

saml2meta is used to manage the SAML v2 metadata. The following table describes the saml2meta subcommands specific to metadata management.

Table 3–1 saml2meta Subcommands for Managing Metadata

Subcommand 

Description 

import

Loads standard and extended metadata in XML format into a local configuration data store. 


Note –

Either -m or -x must be used. Both can also be used.


export

Exports standard and extended metadata in XML format from a local configuration data store. 


Note –

Either -m or -x must be used. Both can also be used.


template

Generates a metadata configuration file for either type of hosted provider (service or identity) with defined values for default metadata properties. The generated file can be modified for use with import.

delete

Removes standard or extended metadata from a local configuration data store. 

list

Generates a list of all the entity identifiers on the system. 

Following are some examples on how you might use saml2meta. See The saml2meta Command-line Reference for explanations of the options used.

Managing Circles of Trust using saml2meta

The saml2meta command line interface creates and manages the circles of trust used by the SAML v2 Plug-in for Federation Services. The following table describes the saml2meta subcommands specific to circle of trust management.

Table 3–2 saml2meta Subcommands for Managing Circles of Trust

Subcommand 

Description 

cotcreate

Creates a circle of trust. 

cotdelete

Removes a circle of trust. 


Note –

To delete a circle of trust that contains providers, use cotremove to remove each provider first, then use cotdelete to delete the circle itself.


cotadd

Adds a trusted provider to an existing circle of trust. 


Note –

cotadd can only add a single entity at a time. Add multiple entities when you first create the circle by using cotcreate and the -l option.


cotremove

Removes a trusted provider from an existing circle of trust. 

cotmember

Lists the member providers in a particular circle of trust. 

cotlist

Lists all the circles of trust configured on the system. 

The following command example will create a circle of trust:


saml2meta [-i staging-directory] cotcreate -u admin-user -w password -t COT-name
 -p idp-discovery-URL-path

This second command example will add a trusted provider to an existing circle of trust:


saml2meta [-i staging-directory] cotadd -u admin-user -w password -t COT-name -e entity-ID

This next command example will remove a trusted provider from an existing circle of trust:


saml2meta [-i staging-directory] cotremove -u admin-user -w password -t COT-name -e entity-ID

This command example will list all the providers belonging to an existing circle of trust:


saml2meta [-i staging-directory] cotmember -u admin-user -w password -t COT-name

This last command example will list all the available circles of trust under the instance of the SAML v2 Plug-in for Federation Services:


saml2meta [-i staging-directory] cotlist -u admin-user -w password