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

Chapter 3 Administration

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:

Provider Metadata and Circles of Trust

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.

Note –

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.

Tip –
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.

Note –
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.

Metadata

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.

Note –

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

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.

Note –

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.

Identity Provider Standard Metadata Properties

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: A persistent identifier is saved to a particular user's data store entry as the value of two attributes. A transient identifier is temporary and no data will be written to the user's persistent data store. 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.

Service Provider Standard Metadata Properties

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: A persistent identifier is saved to a particular user's data store entry as the value of two attributes. A transient identifier is temporary and no data will be written to the user's persistent data store. 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

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.

Identity Provider Extended Metadata Properties

The identity 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`	Enables auto-federation which 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.
`assertionEffectiveTime`	Specifies (in seconds) the amount of time that an assertion is valid counting from the assertion's issue time. The default value is `600` seconds.
`idpAuthncontextMapper`	Specifies the name of the implementation class for the `IDPAuthnContextMapper` interface. This class sets the authentication context in the assertion. The default value is `com.sun.identity.saml2.plugins.DefaultIDPAuthnContextMapper`, the default implementation.
`idpAuthncontextClassrefMapping`	Sets the mappings between the requested authentication context class and the actual authentication mechanism. The value of this attribute is in the format of: `authnContextClassRef \| authnType=authnValue \| authnType=authnValue \| ...` where `authnContextClassRef` is the authentication context class reference, `authnType` is the module, level, or service, and `authnValue` is the module name, authentication level, or service name.
`idpAccountMapper`	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.DefaultIDPAccountMapper`, the default implementation.
`idpAttributeMapper`	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.DefaultIDPAttributeMapper`, the default implementation
`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`.
`wantNameIDEncrypted`	Takes a value of `true` or `false`. If `true`, the service provider must encrypt all `NameID` elements.
`wantArtifactResolveSigned`	Takes a value of `true` or `false`. If `true`, the service provider must sign the `ArtifactResolve` 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 `ManageNameIDRequest` 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(s) of trust to which this provider belongs. As one provider may be in a number of circles, this attribute might have multiple values.

Service Provider Extended Metadata Properties

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: exact where the authentication context statement in the assertion must be the exact match of, at least, one of the authentication contexts specified. minimum where the authentication context statement in the assertion must be, at least, as strong (as deemed by the identity provider) one of the authentication contexts specified. maximum where the authentication context statement in the assertion must be no stronger than any of the authentication contexts specified. better where the authentication context statement in the assertion must be stronger than any of the authentication contexts specified. 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&param2=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.

Dual Purpose Provider Metadata Files

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.

Dual Purpose Standard Metadata Configuration File

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>

Dual Purpose Extended Metadata Configuration File

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>

To Generate Dual Purpose Metadata Configuration Files

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

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`

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.

Static Properties in `AMConfig.properties`

This list describes the properties added to AMConfig.properties when the SAML v2 Plug-in for Federation Services is installed.

Caution –

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.

Note –
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.

Additional Properties in `AMConfig.properties`

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

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.

Note –

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.

To Set the Reader and Writer URLs

Before You Begin

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
Tip –
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

Next Steps

Service providers will be redirected to the SAML v2 IDP Discovery Service Reader URL during single sign-on.

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 – 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 – 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:

saml2meta Subcommands for Managing Metadata in Table 3–1
saml2meta Subcommands for Managing Circles of Trust in Table 3–2

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.

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
Note –
Remember to delete old metadata before you import modified files.
See Dual Purpose Provider Metadata Files.

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

Chapter 3 Administration

Provider Metadata and Circles of Trust

Metadata

Standard Metadata Properties

Identity Provider Standard Metadata Properties

Service Provider Standard Metadata Properties

Extended Metadata Properties

Identity Provider Extended Metadata Properties

Service Provider Extended Metadata Properties

Dual Purpose Provider Metadata Files

Dual Purpose Standard Metadata Configuration File

Dual Purpose Extended Metadata Configuration File

To Generate Dual Purpose Metadata Configuration Files

Circles of Trust

AMConfig.properties

Static Properties in AMConfig.properties

Additional Properties in AMConfig.properties

The SAML v2 IDP Discovery Service

To Set the Reader and Writer URLs

Before You Begin

Next Steps

The saml2meta Command-line Reference

Managing Metadata using saml2meta

Managing Circles of Trust using saml2meta

`AMConfig.properties`

Static Properties in `AMConfig.properties`

Additional Properties in `AMConfig.properties`

The `saml2meta` Command-line Reference

Managing Metadata using `saml2meta`

Managing Circles of Trust using `saml2meta`