After installing the SAML v2 Plug-in for Federation Services, follow the procedures in this chapter to configure the product for SAML v2 interactions. It covers the following topics:
In order to communicate using the SAML v2 profiles you need, at the least, two instances of the installed SAML v2 Plug-in for Federation Services configured in one circle of trust. Circles of trust configured for real time interactions must have, at the least, one instance acting as the circle's identity provider and one instance acting as a service provider.
To prepare your instances of the SAML v2 Plug-in for Federation Services for interactions, you need to exchange and import the metadata for all participating identity and service providers, and assemble the providers into a circle of trust. The following steps are an overview of the process. Many of these steps are accomplished using the saml2meta interface as described in The saml2meta Command-line Reference.
Before beginning this configuration process, be sure that you have completed the instructions in Postinstallation.
Decide whether the instance of the SAML v2 Plug-in for Federation Services you are configuring will act as either an identity provider, a service provider, or both.
Create standard and extended metadata configuration files containing the appropriate metadata for your organization as described in Metadata.
Alternately, you can use the default identity provider metadata configuration files (idpMeta.xml and idpExtended.xml) or the default service provider metadata configuration files (spMeta.xml and spExtended.xml) created during installation. See Standard Metadata Properties and Extended Metadata Properties for more information.
Create a circle of trust as described in Managing Circles of Trust using saml2meta.
Information about circles of trust can be found in Circles of Trust.
Import your organization's provider metadata into the circle of trust as described in Managing Metadata using saml2meta.
Determine which organizations will be added to the circle of trust as identity providers and service providers and create a standard and an extended metadata configuration file for each. See Metadata.
The values in these files will come from the providers themselves.
Import the trusted provider metadata into the circle of trust as described in Managing Metadata using saml2meta.
Restart the web container.
SAML profiles require that pre-interaction agreements regarding user identifiers, provider (entity) identifiers, binding support, SOAP endpoints, public key information and other similar types of data be made between providers in a circle of trust. This configuration information, or metadata, is defined in an XML file and shared amongst all providers who will participate in the interactions. Application programming interfaces (API) are then used to communicate with the data store; reading, writing, and managing the relevant properties and property values. There are two classifications of metadata:
Standard metadata is defined in the Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 specification. The specification includes information such as the single sign-on service URL and the assertion consumer service URL and is written so as to be extensible. For more information, see Standard Metadata Properties.
Extended metadata are properties used by the SAML v2 Plug-in for Federation Services proprietary features and include information such as the account mapper implementation class, and the local authentication URL. For more information, see Extended Metadata Properties.
Instructions on how to use to the saml2meta command-line interface to manage metadata is in Managing Metadata using saml2meta. Instructions on how to generate a dual provider metadata configuration file is in Dual Purpose Provider Metadata Files.
Metadata is sometimes referred to as entity descriptor or entity configuration where entity generically refers to the entityID with which each provider is uniquely identified. For more information on the entityID, see Extended Metadata Properties.
Standard metadata properties are defined in the Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 specification and include information such as the single sign-on service URL and the assertion consumer service URL. During installation, two standard metadata configuration files are created for use as input to the saml2meta utility. They are located in /AccessManager-base/product-directory/saml2/meta or /FederationManager-base/SUNWam/saml2/meta.
idpMeta.xml is the default standard metadata configuration file if your instance of the SAML v2 Plug-in for Federation Services will act as an identity provider.
spMeta.xml is the default standard metadata configuration file if your instance of the SAML v2 Plug-in for Federation Services will act as an service provider.
The following sections define both the identity provider and service provider standard metadata properties that have been implemented in the SAML v2 Plug-in for Federation Services.
A complete listing of all the standard metadata properties can be found in the Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0.
The identity provider standard metadata properties implemented in the SAML v2 Plug-in for Federation Services are defined in the following table.
WantAuthnRequestsSigned |
Takes a value of true or false. If true, all authentication requests received by this identity provider must be signed. |
ArtifactResolutionService |
Defines the endpoint(s) that support the Artifact Resolution profile. |
SingleLogoutService |
Defines the endpoint(s) that support the Single Logout profiles. |
ManageNameIDService |
Defines the endpoint(s) that support the Name Identifier Management profiles. |
NameIDFormat |
Defines the name identifier formats supported by the identity provider. Name identifiers are a way for providers to communicate with each other regarding a user. Single sign-on interactions support two types of identifiers:
More information about name identifiers is in Single Sign-on. |
SingleSignOnService |
Defines the endpoint(s) that support the profiles of the Authentication Request protocol. All identity providers must support at least one such endpoint. |
The service provider standard metadata properties implemented in the SAML v2 Plug-in for Federation Services are defined in the following table.
AuthnRequestsSigned |
Takes a value of true or false. If true, the service provider will sign all outgoing authentication requests. |
WantAssertionsSigned |
Takes a value of true or false. If true, all assertions received by this service provider must be signed. |
SingleLogoutService |
Defines the endpoint(s) that support the Single Logout profiles. |
ManageNameIDService |
Defines the endpoint(s) that support the Name Identifier Management profiles. |
NameIDFormat |
Defines the name identifier formats supported by the service provider. Name identifiers are a way for providers to communicate with each other regarding a user. Single sign-on interactions support two types of identifiers:
More information about name identifiers is in Single Sign-on. |
AssertionConsumerService |
Defines the endpoint(s) that support the profiles of the Authentication Request protocol. All service providers support at least one such endpoint. |
Extended metadata properties are properties used by our proprietary features and include information such as the account mapper implementation class and the local authentication URL. The properties are specific to whether the provider is an identity provider or a service provider. During installation, two extended metadata configuration files are created for use as input to the saml2meta command. They are located in /AccessManager-base/product-directory/saml2/meta or /FederationManager-base/SUNWam/saml2/meta.
idpExtended.xml is the default extended metadata configuration file if your instance of the SAML v2 Plug-in for Federation Services will act as an identity provider.
spExtended.xml is the default extended metadata configuration file if your instance of the SAML v2 Plug-in for Federation Services will act as an service provider.
The following sections define properties in the identity provider and service provider extended metadata.
The identity provider extended metadata properties are defined in the following table.
The service provider extended metadata properties are defined in the following table.
hosted |
Specifies whether the entity is hosted on, or remote to, the server to which this metadata is being applied. A value of 0 or flase specifies that the entity is hosted. A value of 1 or true specifies that the entity is hosted. |
entityID |
Specifies the EntityID of the provider you are configuring. The value of EntityID for your local provider is the unique uniform resource identifier (URI) you decide to use to identity yourself to other providers. You will get a remote provider's EntityID from the metadata they give to you. Note – This EntityID is different from the entities configured using the console in Access Manager and Federation Manager. It is specific to SAML v2 interactions. |
metaAlias |
Specifies a metaAlias for the provider being configured. 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 – The names used in the metaAlias must not contain a /. |
signingCertAlias |
Specifies the provider certificate alias used to find the correct signing certificate in the keystore. |
encryptionCertAlias |
Specifies the provider certificate alias used to find the correct encryption certificate in the keystore. |
basicAuthOn |
Basic authentication can be turned on to protect SOAP endpoints. This property takes a value of true or false. Any provider accessing these endpoints must have the user and password defined in the following two properties: basicAuthUser and basicAuthPassword. |
basicAuthUser |
The user associated with the basic authentication. |
basicAuthPassword |
The password associated with the basic authentication. |
autofedEnabled |
Auto-federation automatically federates a user's disparate provider accounts based on a common attribute. This property takes a value of true or false. |
autofedAttribute |
Specifies the attribute used to match a user's disparate provider accounts when auto-federation is enabled. |
spAccountMapper |
Specifies the implementation of the AccountMapper interface used to map a remote user account to a local user account for purposes of single sign-on. The default value is com.sun.identity.saml2.plugins.DefaultSPAccountMapper, the default implementation. |
spAttributeMapper |
Specifies the implementation of the AttributeMapper interface used to map a remote user account attribute to a local user account attribute for purposes of single sign-on. The default value is com.sun.identity.saml2.plugins.DefaultSPAttributeMapper, the default implementation |
spAuthncontextMapper |
Specifies the implementation of the SPAuthnContextMapper interface used to create the requested authentication context. The default implementation is com.sun.identity.saml2.plugins.DefaultSPAttributeMapper. |
spAuthncontextClassrefMapping |
Sets the provider's desired authentication context class and authentication level. Multiple values can be specified. The value of this property is in the format: authnContextClassRef | authlevel | default For example: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport | 1 or urn:oasis:names:tc:SAML:2.0:ac:classes:Password | 0 | default |
spAuthncontextComparisonType |
Specifies what the resulting authentication context must be when compared to the value of this property. Accepted values include:
The default value is exact. |
attributeMap |
Specifies the mapping of attributes between providers. The value of this attribute is in the format: SAML v2-attribute=user-attribute where SAML v2-attribute is the attribute name that goes over the wire and user-attribute is the attribute name it will map to once it arrives. Note – If auto-federation is enabled, the value of SAML v2-attribute is equal to the value of autofedAttribute. |
saml2AuthModuleName |
Specifies the name of the instance of the SAML v2 authentication module. The default value is SAML2. |
localAuthURL |
Specifies the URL of the local login page. For more information, see Assertion Consumer Page. |
intermediateUrl |
Specifies a URL to which a user can be directed after authentication and before the original request's URL. An example might be a successful account creation page after the auto-creation of a user account. |
defaultRelayState |
After a successful SAML v2 operation (single sign-on, single logout, or federation termination), a page is displayed. This page, generally the originally requested resource, is specified in the initiating request using the RelayState element. If a RelayState is not specified, the value of this defaultRelayState property is displayed. For more information, see Default Display Page. Caution – When RelayState or defaultRelayState contains special characters (such as &), it must be URL-encoded. For example, if the value of RelayState is http://www.sun.com/apps/myapp.jsp?param1=abc¶m2=xyz, it must be URL-encoded as: http%3A%2F%2Fwww.sun.com%2Fapps%2Fmyapp.jsp%3Fparam1%3Dabc%26param2%3Dxyz and then appended to the URL. For example, the service provider initiated single sign-on URL would be: http://host:port/deploy-uri/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=http://www.idp.com&RelayState=http%3A%2F%2Fwww.sun.com%2Fapps%2Fmyapp.jsp%3Fparam1%3Dabc%26param2%3Dxyz |
AssertionTimeSkew |
Assertions are valid for a period of time and not before or after. This property specifies a grace period (in seconds) for the notBefore value. The default value is 300. It has no relevance to the notAfter value. |
wantAttributeEncrypted |
Takes a value of true or false. If true, the identity provider must encrypt all AttributeStatement elements. |
wantAssertionEncrypted |
Takes a value of true or false. If true, the identity provider must encrypt all Assertion elements. |
wantNameIDEncrypted |
Takes a value of true or false. If true, the identity provider must encrypt all NameID elements. |
wantArtifactResponseSigned |
Takes a value of true or false. If true, the identity provider must sign the ArtifactResponse element. |
wantLogoutRequestSigned |
Takes a value of true or false. If true, the identity provider must sign the LogoutRequest element. |
wantLogoutResponseSigned |
Takes a value of true or false. If true, the identity provider must sign the LogoutResponse element. |
wantMNIRequestSigned |
Takes a value of true or false. If true, the identity provider must sign the ManageNameIDResponse element. |
wantMNIResponseSigned |
Takes a value of true or false. If true, the identity provider must sign the ManageNameIDResponse element. |
cotlist |
Specifies the name of the circle of trust to which this provider belongs. |
transientUser |
Specifies the identifier of the user to which all identity provider users will be mapped on the service provider side in cases of single sign-on using the transient name identifier. |
According to the SAML v2 specifications, one metadata file can contain configuration data for one identity provider and one service provider. Thus, it is possible to create one standard metadata configuration file and one extended configuration file which, when imported, will configure one member of a circle of trust to act as both an identity provider and a service provider. Sample files and instructions on how to generate them are found in the following sections.
The dual purpose standard metadata file would contain one <EntityDescriptor> element containing both <IDPSSODescriptor> and <SPSSODescriptor> elements. The following sample is a standard metadata configuration file in which the data configures zosma21.central.sun.com as both a service provider and an identity provider.
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="zosma21.central.sun.com/"> <IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://zosma21.central.sun.com:80/amserver/ArtifactResolver/ metaAlias/idp" index="0" isDefault="1"/> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://zosma21.central.sun.com:80/amserver/IDPSloRedirect/ metaAlias/idp" ResponseLocation="http://zosma21.central.sun.com:80/amserver/ IDPSloRedirect/metaAlias/idp"/> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://zosma21.central.sun.com:80/amserver/ IDPSloSoap/metaAlias/idp"/> <ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://zosma21.central.sun.com:80/amserver/IDPMniRedirect/ metaAlias/idp" ResponseLocation="http://zosma21.central.sun.com:80/amserver/ IDPMniRedirect/metaAlias/idp"/> <ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://zosma21.central.sun.com:80/amserver/IDPMniSoap/ metaAlias/idp"/> <NameIDFormat> urn:oasis:names:tc:SAML:2.0:nameid-format:persistent </NameIDFormat> <NameIDFormat> urn:oasis:names:tc:SAML:2.0:nameid-format:transient </NameIDFormat> <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://zosma21.central.sun.com:80/amserver/SSORedirect/ metaAlias/idp"/> <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://zosma21.central.sun.com:80/amserver/SSOSoap/ metaAlias/idp"/> </IDPSSODescriptor> <SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration= "urn:oasis:names:tc:SAML:2.0:protocol"> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://zosma21.central.sun.com:80/amserver/SPSloRedirect/ metaAlias/sp" ResponseLocation="http://zosma21.central.sun.com:80/amserver/ SPSloRedirect/metaAlias/sp"/> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://zosma21.central.sun.com:80/amserver/SPSloSoap/ metaAlias/sp"/> <ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://zosma21.central.sun.com:80/amserver/SPMniRedirect/ metaAlias/sp" ResponseLocation="http://zosma21.central.sun.com:80/amserver/ SPMniRedirect/metaAlias/sp"/> <ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="http://zosma21.central.sun.com:80/amserver/SPMniSoap/ metaAlias/sp" ResponseLocation="http://zosma21.central.sun.com:80/amserver/ SPMniSoap/metaAlias/sp"/> <NameIDFormat> urn:oasis:names:tc:SAML:2.0:nameid-format:persistent </NameIDFormat> <NameIDFormat> urn:oasis:names:tc:SAML:2.0:nameid-format:transient </NameIDFormat> <AssertionConsumerService isDefault="true" index="0" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="http://zosma21.central.sun.com:80/amserver/Consumer/ metaAlias/sp"/> <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://zosma21.central.sun.com:80/amserver/Consumer/ metaAlias/sp"/> </SPSSODescriptor> </EntityDescriptor>
The dual purpose extended metadata file would contain one <EntityConfig> element containing both <IDPSSOConfig> and <SPSSOConfig> elements. The following sample is an extended metadata configuration file in which the data configures zosma21.central.sun.com as both a service provider and an identity provider.
<EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig" xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig" hosted="1" entityID="zosma21.central.sun.com/"> <IDPSSOConfig metaAlias="/idp"> <Attribute name="signingCertAlias"> <Value></Value> </Attribute> <Attribute name="encryptionCertAlias"> <Value></Value> </Attribute> <Attribute name="basicAuthOn"> <Value>false</Value> </Attribute> <Attribute name="basicAuthUser"> <Value></Value> </Attribute> <Attribute name="basicAuthPassword"> <Value></Value> </Attribute> <Attribute name="autofedEnabled"> <Value>false</Value> </Attribute> <Attribute name="autofedAttribute"> <Value></Value> </Attribute> <Attribute name="assertionEffectiveTime"> <Value>600</Value> </Attribute> <Attribute name="idpAuthncontextMapper"> <Value>com.sun.identity.saml2.plugins.DefaultIDPAuthnContextMapper</Value> </Attribute> <Attribute name="idpAuthncontextClassrefMapping"> <Value>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</Value> </Attribute> <Attribute name="idpAccountMapper"> <Value>com.sun.identity.saml2.plugins.DefaultIDPAccountMapper</Value> </Attribute> <Attribute name="idpAttributeMapper"> <Value>com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper</Value> </Attribute> <Attribute name="attributeMap"> <Value></Value> </Attribute> <Attribute name="wantNameIDEncrypted"> <Value></Value> </Attribute> <Attribute name="wantArtifactResolveSigned"> <Value></Value> </Attribute> <Attribute name="wantLogoutRequestSigned"> <Value></Value> </Attribute> <Attribute name="wantLogoutResponseSigned "> <Value></Value> </Attribute> <Attribute name="wantMNIRequestSigned"> <Value></Value> </Attribute> <Attribute name="wantMNIResponseSigned"> <Value></Value> </Attribute> <Attribute name="cotlist"> </Attribute> </IDPSSOConfig> <SPSSOConfig metaAlias="/sp"> <Attribute name="signingCertAlias"> <Value></Value> </Attribute> <Attribute name="encryptionCertAlias"> <Value></Value> </Attribute> <Attribute name="basicAuthOn"> <Value>false</Value> </Attribute> <Attribute name="basicAuthUser"> <Value></Value> </Attribute> <Attribute name="basicAuthPassword"> <Value></Value> </Attribute> <Attribute name="autofedEnabled"> <Value>false</Value> </Attribute> <Attribute name="autofedAttribute"> <Value></Value> </Attribute> <Attribute name="transientUser"> <Value></Value> </Attribute> <Attribute name="spAccountMapper"> <Value>com.sun.identity.saml2.plugins.DefaultSPAccountMapper</Value> </Attribute> <Attribute name="spAttributeMapper"> <Value>com.sun.identity.saml2.plugins.DefaultSPAttributeMapper</Value> </Attribute> <Attribute name="spAuthncontextMapper"> <Value>com.sun.identity.saml2.plugins.DefaultSPAuthnContextMapper</Value> </Attribute> <Attribute name="spAuthncontextClassrefMapping"> <Value>PasswordProtectedTransport|0|default</Value> </Attribute> <Attribute name="spAuthncontextComparisonType"> <Value>exact</Value> </Attribute> <Attribute name="attributeMap"> <Value></Value> </Attribute> <Attribute name="saml2AuthModuleName"> <Value></Value> </Attribute> <Attribute name="localAuthURL"> <Value></Value> </Attribute> <Attribute name="intermediateUrl"> <Value></Value> </Attribute> <Attribute name="defaultRelayState"> <Value></Value> </Attribute> <Attribute name="assertionTimeSkew"> <Value>300</Value> </Attribute> <Attribute name="wantAttributeEncrypted"> <Value></Value> </Attribute> <Attribute name="wantAssertionEncrypted"> <Value></Value> </Attribute> <Attribute name="wantNameIDEncrypted"> <Value></Value> </Attribute> <Attribute name="wantArtifactResponseSigned"> <Value></Value> </Attribute> <Attribute name="wantLogoutRequestSigned"> <Value></Value> </Attribute> <Attribute name="wantLogoutResponseSigned "> <Value></Value> </Attribute> <Attribute name="wantMNIRequestSigned"> <Value></Value> </Attribute> <Attribute name="wantMNIResponseSigned"> <Value></Value> </Attribute> <Attribute name="cotlist"> </Attribute> </SPSSOConfig> </EntityConfig>
This procedure creates one standard metadata file and one extended metadata file that contains configuration information for one provider that, when imported, will define it as capable of both functions. See The saml2meta Command-line Reference for more information on the saml2meta command line interface.
Generate the dual purpose standard and extended metadata configuration files.
saml2meta [-i staging-directory] template -u amadmin -w password -e dual -s /sp1 -d /idp1 -m dualMeta.xml -x dualExtended.xml
Import the generated standard and extended metadata configuration files.
saml2meta [-i staging-directory] import -u amadmin -w password -m dualMeta.xml -x dualExtended.xml
Circles of trust need to be created to define trust relationships among identity providers and service providers. A circle of trust is a grouping of service providers (with at least one identity provider) that have, in place, pertinent business agreements regarding how they will do business and interact with identities. Any identity provider or service provider within a circle of trust will honor requests and information that come from other providers in the same circle. Requests and information will be rejected if communicating providers are not part of the same circle of trust. In the SAML v2 Plug-in for Federation Services, circles of trust are created using the saml2meta command-line interface, allowing you to configure technologically the participants and rules drawn in the business agreements. Instructions on how to use the saml2meta command-line interface to manage circles of trust is in Managing Circles of Trust using saml2meta.
AMConfig.properties is the main configuration file for Access Manager and Federation Manager. AMConfig.properties is located in the /etc/opt/product-directory/config directory in Access Manager and the /staging-directory/web-src/WEB-INF/classes directory in Federation Manager.
This list describes the properties added to AMConfig.properties when the SAML v2 Plug-in for Federation Services is installed.
Do not modify the properties configured during installation.
com.sun.identity.saml2.am_or_fm takes a value of AM for Access Manager or FM for Federation Manager. It specifies the instance type onto which the SAML v2 Plug-in for Federation Services is installed.
com.sun.identity.saml2.xmlenc.EncProviderImpl=com.sun.identity.saml2.xmlenc.FMEncProvider specifies the XML encryption provider implementation class.
com.sun.identity.saml2.xmlenc.SigProviderImpl=com.sun.identity.saml2.xmlsig.FMSigProvider specifies the XML signature provider implementation class.
com.sun.identity.common.datastore.provider.default=com.sun.identity.saml2.plugins.IdRepoDataStoreProvider specifies the data store provider implementation class. The IdRepoDataStoreProviderdefault class provides implementation using the identity repository API.
In Federation Manager, a different implementation class is already set. It is not set by the SAML v2 Plug-in for Federation Services installer.
The com.sun.identity.saml2.nameidinfo.attribute and com.sun.identity.saml2.nameidinfokey properties specify the LDAPv3 attribute to which you want federation information written in a principal's account. For more information, see Using Non-Default Federation Attributes.
This list describes the properties and accompanying values that may be added to AMConfig.properties after installation.
com.sun.identity.saml2.cacheCleanUpInterval takes a value in seconds. It specifies the amount of time between each cache cleanup.
com.sun.identity.saml2.sdk.mapping.interface-name=new-class-name is a mapping property for customized implementation classes. For more information, see The SAML v2 Plug-in for Federation Services SDK.
The SAML v2 IDP Discovery Service is an implementation of the Identity Provider Discovery Profile as described in the Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0 specification. In deployments having more than one identity provider, service providers need to determine which identity provider(s) a principal uses with the Web Browser SSO profile. To allow for this, the SAML v2 IDP Discovery Service relies on a cookie written in a domain that is common to all identity providers and service providers in a circle of trust. This predetermined domain is known as the common domain, and the cookie containing the list of identity providers to chose from is known as the common domain cookie.
When a user requests access from a service provider and an entity identifier for an identity provider is not received in the request, the service provider redirects the request to the common domain's SAML v2 IDP Discovery Service Reader URL to retrieve the identity provider's entity identifier. If more then one identity provider entity identifier is returned, the last entity identifier in the list is the one to which the request is redirected. Once received, the identity provider redirects to the Discovery Service Writer URL to set the common domain cookie using the value defined in the installation configuration properties file. See Creating an Installation Configuration Properties File for more information.
The Reader and Writer URLs for the SAML v2 IDP Discovery Service are defined when configuring the circle of trust. If the circle already exists and does not contain values for the Reader and Writer URLs, it must be deleted and recreated.
Instructions on how to install the SAML v2 IDP Discovery Service can be found in Installing the SAML v2 IDP Discovery Service. You should also be familiar with The saml2meta Command-line Reference as well as Table 3–2.
Delete the current circle of trust configuration using saml2meta, if applicable.
Create a new circle of trust configuration using saml2meta and the cotcreate subcommand.
saml2meta [-i staging-directory] cotcreate -u admin-user -w password -t COT-name -p idp-discovery-URL-path |
Make sure to specify the full path to where the SAML v2 Plug-in for Federation Services is deployed using the -p option.
Add member providers to the new circle of trust using saml2meta and the cotadd subcommand.
saml2meta [-i staging-directory] cotadd -u admin-user -w password -t COT-name -e entity-ID |
cotadd can only add a single provider at a time using the -e option. To add a group of providers, you can use the -l option with cotcreate in the previous step.
Verify that all member providers have been added to the circle using saml2meta and the cotlist subcommand.
saml2meta [-i staging-directory] cotlist -u admin-user -w password |
Service providers will be redirected to the SAML v2 IDP Discovery Service Reader URL during single sign-on.
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:
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:
saml2meta Subcommands for Managing Metadata in Table 3–1
saml2meta Subcommands for Managing Circles of Trust in Table 3–2
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.
The following command example will create both a standard and an extended metadata configuration file for service provider sp.sun.com:
# saml2meta template -u amadmin -w password -e sp.sun.com -s /sp -m spMeta.xml -x spExtended.xml |
The standard metadata is defined in spMeta.xml and the extended metadata is defined in spExtended.xml.
This command example will import the created files into the local configuration data store:
# saml2meta import -u amadmin -w password -m spMetadata.xml -x spExtended.xml |
Remember to delete old metadata before you import modified files.
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 |