Federation Guides › Legacy Federation Guide › Use SAML 2.0 Provider Metadata To Simplify Configuration

Use SAML 2.0 Provider Metadata To Simplify Configuration

This section contains the following topics:

SiteMinder SAML 2.0 Metadata Tools Overview

CA SiteMinder® provides a metadata tool to import and export SAML 2.0 metadata programmatically. Metadata lets you efficiently exchange federation configurations between a site that uses CA SiteMinder® and a partner that uses a third party or CA SiteMinder®. Programmatic use of SAML 2.0 metadata can limit how much configuration that you perform.

The two command line utilities that make up the CA SiteMinder® metadata tools are smfedexport and smfedimport.

Exporting metadata involves the following types of input:

User input
Access to the CA SiteMinder® certificate data store for including KeyInfo into the metadata
Access to the certificate data store for signing
Access to the policy store to reference similar metadata that can be used as a template.

Importing metadata involves:

User input.
Access to the policy store.
Access to the certificate data store for verifying signatures, if certificates are configured.
Parsing the XML metadata in the metadata document.
Storing the relevant metadata in the policy store.
Storing the PKI information from the metadata in the certificate data store.

Export Metadata Tool

You can use the export tool in the following situations:

Create an Identity Provider metadata file for use by Service Providers.
Use the tool to produce a metadata file containing information about profiles that the Identity Provider supports. This XML output that the export tool generates describes the Identity Provider. Sites acting as Service Providers can import this metadata file to establish a relationship with the Identity Provider.
Create an Identity Provider metadata file from an existing Service Provider.
A CA SiteMinder® Identity Provider generates a metadata file from an existing Service Provider object. The use of the Service Provider object reduces the amount of required data that a user must configure. Many of the settings for the Identity Provider metadata file can be derived from the existing Service Provider. Also,CA SiteMinder® provides the default names of the servlets.

To use the metadata file, the existing relationship between the Identity Provider and the Service Provider is similar to the relationship you are establishing.

The SSO and SLO servlet URLs are the default servlet names that are prepended with the IP address and port of the Federation Web Services application.

The servlet names are:
- http://idp_server:port/affwebservices/public/saml2sso
- http://idp_server:port/affwebservices/public/saml2slo
idp_server:port

Identifies the web server and port hosting the Web Agent Option Pack or SPS federation gateway.
Create a Service Provider metadata file for Use by Identity Providers.
A CA SiteMinder® Service Provider can facilitate federation with sites acting as Identity Providers by producing a metadata file containing information about the profiles it supports. An Identity Provider can import the metadata file to establish a relationship with the Service Provider.
Create a Service Provider metadata file from an existing SAML 2.0 Authentication Scheme.
A CA SiteMinder® Service Provider generates a metadata file from an existing SAML 2.0 Authentication Scheme object. The use of the Service Provider object reduces the amount of required data that a user must configure. Many of the settings for the SP metadata file can be derived from the existing SAML 2.0 authentication scheme. CA SiteMinder® provides the default names of the servlets.

To use the metadata file, the existing relationship between the Service Provider and the Identity Provider must be similar to the relationship you are establishing. The SSO and SLO servlet URLs are the default servlet names that are prepended with the IP address and port of the Federation Web Services application.

The servlets are:
- http://idp_server:port/affwebservices/public/saml2sso
- http://idp_server:port/affwebservices/public/saml2slo
idp_server:port

Identifies the web server and port hosting the Web Agent Option Pack or SPS federation gateway.

The following illustration shows a metadata file that is generated only from user input.

Graphic showing an example metadata file that is generated from user input

The following illustration shows a metadata file that is generated from a combination of user input and data from an existing Service Provider object.

Graphic showing an example metadata file that is generated from a combination of user input and data from an existing Service Provider objec

Run the smfedexport Tool

The smfedexport tool lets you export SAML 2.0 metadata to an XML file.

If you enter smfedexport without any command arguments, all the command arguments and their usage are displayed.

To run the smfedexport tool

At the system where you installed the Policy Server, open a command window.

Enter the smfedexport command using the syntax for the task you want to complete:

Note: Command arguments enclosed in square brackets [] are optional.

To export a SAML 2.0 Identity Provider metadata file:

smfedexport -type saml2idp [-entityid <entityid>] [-expiredays <num>] 
[-fwsurl <FWS Location> [-spbase <spname>] -username <SiteMinder Admin Name>
-password <SiteMinder Admin Password>]][-sign][-pubkey]
[-slo <SLO Service Location> -slobinding <REDIR>] [-reqsignauthr] 
[-sso <SSO Service Location> -ssobinding <REDIR|SOAP>]
[-ars <Artifact Resolution Service Location>][-output <file>]

To export a SAML 2.0 Service Provider metadata file:

smfedexport -type saml2sp [-entityid <entityid>] [-expiredays <num>] 
[-fwsurl <FWS Location> [-schemebase <Auth Scheme name>
-username <SiteMinder Admin Name> -password <SiteMinder Admin Password>]]
[-sign][-pubkey][-slo <SLO Service Location> -slobinding <REDIR>]
[-signauthr][-acs <Assertion Consumer Service> -acsbinding <ART|POST|PAOS>
-acsindex <num>][-acsisdef]][-output <file>]

To sign an existing Metadata document:

smfedexport -type (saml2sp|saml2idp) -sign -input <file> -output <file>

After you run the tool, an XML file will be produced. If the -type option is set to saml2idp, the default output file name is IDPSSODescriptor.xml. If the -type option is set to saml2sp, the default output file name is SPSSODescriptor.xml.

After smfedexport processes the initial command options, the tool prompts you for additional data that is related to the type of export file the tool is generating. Any optional arguments that you do not enter use default values.

Note: If you are creating an IdP metadata file, you must have at least one single sign-on service defined in the smfedexport command. If you are creating an SP metadata file, you must have at least one assertion consumer service defined in the smfedexport command.

Command Options for smfedexport

The smfedexport command line options are listed in the table that follows:

Option	Description	Values
-acs	Assertion Consumer Service URL	URL
-acsindex	Assertion Consumer Service index value	integer
-acsisdef	Makes the immediately preceding Assertion Consumer Service the default.	none
-acsbinding	SAML protocol binding for the Assertion Consumer Service.	ART (artifact) POST (POST) PAOS (Reverse SOAP - ECP)
-ars	Artifact Resolution Service	URL
-decryptionkeyalias	Tells the Policy Server to include the certificate (public key) in the metadata. This certificate encrypts the metadata. The SP decrypts the metadata using the corresponding private key.	alias name
-entityid	Represents the ID of the SP or IDP whose metadata you are exporting.	URI
-expiredays	Days until the metadata document is no longer valid.	integer; 0 is the default A value of 0 indicates that the metadata document has no expiration. No "validUntil" elements being generated in the exported XML.
-fwsurl	URL pointing to the FWS application.	URL in the form http://host:port
-input	Full path to an existing XML file	string, no default
-output	Full path to an output XML file	Default values: IDPSSODescriptor.xml SPSSODescriptor.xml
-password	SiteMinder Administrator name Requires the -username option	string, no default
-pubkey	Tells the Policy Server to include the certificate (public key) in the metadata. The partner site uses the certificate for signature encryption and verification. This setting is optional because the metadata does not have to be signed.	true, if present false otherwise
-reqsignauthr	Require signed AuthnRequests	true, if present false otherwise
-schemebase	Points to an existing Service Provider. The settings for the profiles/bindings are taken from this provider. Requires the following options: -fwsurl -username -password	authentication scheme name
-spbase	Points to an existing Service Provider. The settings for the profiles/bindings are taken from this provider. Requires the following options: -fwsurl -username -password	Service Provider Name
-sign	Indicates whether the Policy Server signs the metadata. This setting is optional.	true, if present false, otherwise
-sigalg	Designates the signature hashing algorithm CA SiteMinder® uses to for signing assertions and assertion responses, single logout requests and responses.	rsawithsha1 rsawithsha256
-signauthr	Indicates whether the SP signs AuthnRequests	true, if present false, otherwise
-signingcertalias	Specifies the alias for the key/certificate pair that signs the metadata. Store the pair in the certificate data store. This setting is an alternative to the default alias, defaultenterpriseprivatekey. If you do not enter a value for this option, the Policy Server uses the defaultenterpriseprivatekey alias to sign the metadata.	alias name
-slo	Single Logout Service URL	URL
-slobinding	HTTP binding that is used for single logout. HTTP Redirect binding is the only option.
-sso	Single sign-on service URL	URL
-ssobinding	SSO Service URL protocol binding	REDIR (web SSO) SOAP (ECP)
-type (Required)	Entity type of the export file	saml2idp sam2sp
-username	The CA SiteMinder® Administrator name, which requires the -password option.	string, no default

smfedexport Tool Examples

Example: Exporting an Identity Provider

smfedexport -type saml2idp -entityid http://www.myidp.com/idp1 
-expiredays 30 -sign -pubkey -slohttpredir http://www.mysite.com
/affwebservices/public/saml2slo -reqsignauthr 
-ssoart http://www.mysite.com/affwebservices/public/saml2sso 
-artressvc http://www.mysite.com/affwebservices/
saml2artifactresolution -output myidpdescription.xml

Example: Exporting a Service Provider

smfedexport -type saml2sp -entityid http://www.myidp.com/sp1
-expiredays 30 -sign -pubkey -slohttpredir http://www.mysite.com/
affwebservices/public/saml2slo -signauthr -aconsvcpost 
http://www.mysite.com/affwebservices/public/saml2assertionconsumer
-aconsvcpostindex 12345 -output myidpdescription.xml

Example: Modifying and Signing an Exported Data File

In this example, you are modifying and digitally signing an XML file using the smfedexport.

To modify and sign a metadata file

Edit the existing XML file using an XML editor.

Enter the following command:

smfedexport -sign -input file -output file

For example:

smfedexport -sign -input myspdescription.xml -output newspdescription.xml

To modify an exported file that is already digitally signed

Edit the existing XML file using an XML editor as need.
Delete the <Signature> element from the file.

Enter the following command:

smfedexport -sign -input file -output file

For example:

smfedexport -sign -input myspdescription.xml -output newspdescription.xml

Import Metadata Tool

You can use the import tool for the following tasks:

Create a SAML 2.0 authentication scheme for a Service Provider, as shown in the following illustration.
Create a SAML 2.0 Service Provider object for an Identity Provider.

Run the smfedimport Tool

The smfedimport utility can import Identity Providers and Service Providers into a CA SiteMinder® policy store and the certificate data store. If you import a Service Provider input file, the result is a new CA SiteMinder® Service Provider object within an existing affiliate domain. If you import an Identity Provider input file, the result is an authentication scheme that is based on the CA SiteMinder® SAML 2.0 Template.

When the smfedimport command line utility is run, the first and second parameters are the username and password of the CA SiteMinder® administrator. The third and final argument is the path to the input XML file.

To run the smfedimport tool

At the system where you installed the Policy Server, open up a command window.

Enter the command using the following syntax:

To import a SAML2 Identity Provider metadata file into the policy store:

smfedimport -type saml2idp -username <username>
-password <password> -entityid <entityid> -name <name>
[-importkeys <name>] [-silent] -input <file>

To import a Service Provider metadata file into the policy store:

smfedimport -type saml2sp -username <username>
-password <password> -entityid <entityid> -domainname <name>
-authurl <URL> -nameidformat (U|E|X|W|K|N|P|T|U)
-nameidtype  (S | U | D) -attrname <name> -dnspec <spec>
-name <name>[-importkeys <name>] [-silent] -input <file>

Note: Switches in square brackets [] are optional.

After smfedimport processes the initial command options, the tool prompts you for additional data based on the type of file you are importing. Any optional arguments that you do not enter on the command line have default values.

smfedimport Tool Examples

Example: Importing Identity Provider metadata

smfedimport -type saml2idp -username Siteminder

-password siteminderpassword -entityid http://www.myidp.com
-name mynewauthscheme -importkeys keyaliasname -input mypartnersidpinfo.xml

Example: Importing Service Provider metadata

smfedimport -type saml2sp -username Siteminder  -password siteminderpassword
-entityid http://www.mysp.com -name mynewsaml2sp -importkeys
keyalisname -domainname myaffiliatedomain
-authurl http://www.mysite.com/login.html -nameidformat U
-nameidtype S -attrname attrname  -input mypartnersspinfo.xml

Command Options for smfedimport

The command line options are listed in the following table.

Option	Description	Value
-attrname	Attribute name for the nameID	string
-authurl	Authentication URL	URL
-dnspec	DN specification for the name ID type only	string
-domainname	Affiliate domain name	string
-entityid	Entity ID	The Service Provider ID for the import or the Identity Provider ID for the import
-importkeys	Indicates whether the certificates in the metadata are imported into the certificate data store.	string. Enter a name that becomes an alias for the certificate in the certificate data store. If there are multiple certificates, the aliases are added as name, name1, name2.
-input	Input file	string
-name	Indicates the name of the CA SiteMinder® object, such as the Service Provider name or the SAML authentication scheme name.	string
-nameidformat	Name ID format	(U)nspecificed--default (E)mail address (X)509 Subject name (W)indows domain name (K)erberos Principal Name E(n)tity Identifier (P)ersistent Identifier (T)ransient Identifier
-nameidtype	Name ID type	(S)tatic (U)ser attribute (D)N attribute
-password	CA SiteMinder® Administrator password	string, no default
-type (Required)	Entity type of the import file	saml2idp sam2sp
-silent	Determines whether the tool interactively prompts the user. With this option, the tool operates in silent mode. The tool does not interactively prompt the user for missing input. The tool also does not prompt the user to accept the import of each separate entity in the input file. The tool assumes that all entities in the input file must be imported.	true, if present false otherwise
-username	CA SiteMinder® Administrator name	string, no default

Processing Import Files with Multiple SAML 2.0 Providers

If multiple providers are specified in one import file, the tool imports them into the same affiliate domain. The names for each provider are based on the value you specify for the smfedimport command option -name.

For example, if there are three Service Providers in the import file and you specify:

-name mySP

The tool registers the imported providers as mysp, mysp_1, and mysp_2. The integer increases by one for each subsequent provider. If there is a mixture of Identity Providers and Service Providers in an import file, the naming convention still applies.

Processing Import Files with Multiple Certificate Aliases

If there are multiple certificates in the import file, the tool imports them into the certificate data store. The tool then assigns alias names from the value you specify with that smfedimport command option –importkeys.

For example, if there are three certificates in the import file and you specify:

 -importkeys myalias

The tool registers the imported certificates as myalias, myalias_1, and myalias_2. The integer increases by one for each subsequent certificate.