Sun OpenSSO Enterprise 8.0 Administration Guide

Part II Federation, Web Services, and SAML Administration

This is part two of the Sun OpenSSO Enterprise 8.0 Administration Guide and describes how to implement, configure and manage the OpenSSO Enterprise features based on the Liberty Alliance Project Identity Federation Framework, the Liberty Alliance Project Web Services Framework, the WS-Federation specifications, and the Security Assertion Markup Language (SAML) versions 1.x and 2. The part contains the following chapters.

Chapter 7 Configuring and Managing Federation

OpenSSO Enterprise has a federation framework that can be used to configure and manage federation configurations based on the Liberty Alliance Project Identity Federation Framework (Liberty ID-FF), the Liberty Alliance Project Web Services Framework (Liberty ID-WSF), the WS-Federation specifications and the Security Assertion Markup Language (SAML) versions 1.x and 2. Federation configurations can be implemented using the OpenSSO Enterprise console or the ssoadm command line utility. For a detailed overview of the Federation framework architecture, see Chapter 10, Federation Management with OpenSSO Enterprise, in Sun OpenSSO Enterprise 8.0 Technical Overview. This chapter contains:

Configuring Federation

To configure for federation, create a circle of trust and populate it with entity types using the following high-level procedure.

  1. Decide whether the instance of OpenSSO Enterprise you are configuring will act as an identity provider, a service provider, or both, and create standard and extended metadata XML files containing the specific protocols, profiles, endpoints, and security mechanisms being used by the instance.

    • Standard metadata properties are defined in the Liberty ID-FF and SAMLv2 specification.

    • Extended metadata properties are proprietary and used by features specific to OpenSSO Enterprise.

  2. Create an entity to hold the metadata for every identity and service provider that will become a member of the circle of trust (including the instance of OpenSSO Enterprise for which you previously created metadata).

    The metadata for other entities may come from the providers themselves. See Creating an Entity.

  3. Configure a circle of trust to denote the group of entities that have joined together to exchange authentication information for purposes of federation.

    See Circle of Trust.

  4. Add the appropriate entities to the circle of trust by configuring both the entity's metadata (to add the authentication domain of the circle of trust) and the circle of trust's properties (to add the entity).

Information on an entity provider's properties are located in Chapter 6, Federation Attributes for Entity Providers, in Sun OpenSSO Enterprise 8.0 Administration Reference. Information on a circle of trust's properties can be found in To Modify a Circle of Trust Profile.


Tip –

In a federation setup, all service providers and identity providers must share a synchronized clock. You can implement the synchronization by pointing to an external clock source or by ensuring that, in case of delays in receiving responses, the responses are captured without fail through adjustments of the time outs.


Managing Federation Using the Console

The Federation component of the OpenSSO Enterprise console provides an interface for creating, modifying, and deleting circles of trust, and the corresponding member entity providers (both identity and service).

Creating an Entity

An entity holds the metadata for individual identity and service providers. (Metadata contains the specific protocols, profiles, endpoints, and security mechanisms being used by the entity.) OpenSSO Enterprise allows you create an entity for communication using either the SAML v2, the Liberty ID-FF, and the WS-Federation specifications. Within each entity type, you can assign roles by configuring the attributes to perform the specific function. The following sections describe the entity types and the roles you can assign.

SAMLv2 Entity

The SAMLv2 entity type is based on the SAML v2 specification. This entity supports various profiles (including single sign-on and single logout) and allows you to assign and configure the following roles:

ProcedureTo Create a SAMLv2 Entity Provider

Use these steps to create a hosted entity provider based on the SAMLv2 protocol. You can assign one, more than one, or all of the provider roles to the entity, but all of the roles that you define will belong to the same entity provider.

  1. Log in as an administrator.

  2. Go to the Federation tab in the console and click New in the Entity Provider table.

  3. When prompted, select SAMLv2 as the entity provider.

  4. Select the Realm to which the entity provider will belong.

  5. Type a name in the Entity Identifier field.

  6. Enter values for the following attributes under the role category to which the entity provider will be assigned.

    Entering data in the Meta Alias field will automatically create and assign the entity provider role to the entity provider upon completion.

    Meta Alias

    Specifies a metaAlias for the provider role 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 coupled with a forward slash and the provider name. For example, /suncorp/travelprovider.


    Caution – Caution –

    The names used in the metaAlias must not contain a /.


    Signing Certificate Alias

    Specifies the provider certificate alias used to find the correct signing certificate in the keystore.

    Encryption Certificate alias

    Specifies the provider certificate alias used to find the correct encryption certificate in the keystore.

    Owner ID (Hosted Affiliation only)

    An identifier for the owner of the affiliation.

    Affiliation Members (Hosted Affiliation only)

    A provider must be a member of a circle of trust, or it cannot participate in SAMLv2-based communications. The provider can belong to one or more affiliations. The selected provider must have the Affiliation Federation attribute enabled. Enter the meta alias of the provider in the New Value field and click Add.

  7. Click Create.

    The entity provider, its assigned provider roles, and location will be displayed in the Entity Providers table. To customize the entity providers' roles behavior, click the name of the entity provider from the list and choose the tab that corresponds to the role you wish to customize. See Chapter 6, Federation Attributes for Entity Providers, in Sun OpenSSO Enterprise 8.0 Administration Reference for definitions attributes for provider customization.

SAMLv2 Hosted Affiliation Customization

A Hosted Affiliation contains a grouping of service providers. The affiliation is formed and maintained by an affiliation owner who chooses the member providers from already configured provider entities. The affiliation enables a user to federate amongst the group of associated sites. The chosen providers may invoke services either as a member of the affiliation, or individually as a provider. If services are invoked as an affiliation member, a service provider might issue an authentication request for a user on behalf of an affiliation. When authentication is secured, the user can achieve single sign-on with all members of the affiliation.

A hosted affiliation provider holds the metadata that defines the grouping of one or more provider entities that comprise the affiliation. It does not contain the configuration information for any providers (which is defined in a provider entity), only the configuration information for the affiliation itself. If there are several service providers and identity providers in the same circle of trust, use an affiliate entity to avoid having to generate different name identifiers for commonly shared services. Hosted Affiliation contains the following attributes for customization:

Meta Alias

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 OpenSSO Enterprise) coupled with a forward slash and the provider name. For example, /suncorp/travelprovider.


Caution – Caution –

The names used in the metaAlias must not contain a /.


Members

A provider must be a member of a circle of trust, or it cannot participate in Liberty-based communications. The provider can belong to one or more affiliations. Enter the entity ID of the provider in the New Value field and click Add.

Cert Alias

This attribute defines the certificate alias elements for the provider. Signing specifies the provider certificate alias used to find the correct signing certificate in the keystore. Encryption specifies the provider certificate alias used to find the correct encryption certificate in the keystore.

ID-FF Entity Provider

The ID-FF provider entity is based on the Liberty Alliance Project Identity Federation Framework for implementing single sign-on with federated identities. The ID-FF provider entity allows you to assign and configure the following roles:

ProcedureTo Create an ID-FF Entity Provider

Use these steps to create an entity provider based on the ID-FF protocol for Federation Services. You can assign the identity provider or service provider (or both) role to the entity, but multiple roles will belong to the same entity provider.

  1. Log in as an administrator.

  2. Go to the Federation tab in the console and click New in the Entity Provider table.

  3. When prompted, select ID-FF as the entity provider.

  4. Select the Realm to which the entity provider will belong.

  5. Type a name in the Entity Identifier field.

  6. Choose the entity provider role you wish to assign to the entity provider.

    Entering data in the Meta Alias field will automatically create and assign the entity provider role to the entity provider upon completion.

  7. Enter values for the following attributes for one or more roles:

    Meta Alias

    Specifies a metaAlias for the provider role 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 coupled with a forward slash and the provider name. For example, /suncorp/travelprovider.


    Caution – Caution –

    The names used in the metaAlias must not contain a /.


    Signing Certificate Alias

    Specifies the provider certificate alias used to find the correct signing certificate in the keystore.

    Encryption Certificate alias

    Specifies the provider certificate alias used to find the correct encryption certificate in the keystore.

  8. Click Create.

    The entity provider, its assigned provider roles, and location will be displayed in the Entity Providers list.

  9. To customize the entity providers' roles behavior, click on the name of the entity provider and choose the tab that corresponds to the role you wish to customize. See Chapter 6, Federation Attributes for Entity Providers, in Sun OpenSSO Enterprise 8.0 Administration Reference for definitions attributes for provider customization.

WS-Federation Entity Provider

The WS-Federation entity provider type is based on the WS-Federation protocol. The implementation of this protocol allows single sign-on between OpenSSO Enterprise and the Microsoft Active Directory Federation Service. The WS-Federation provider entity allows you to assign and configure the following roles:

ProcedureTo Create a WS-Federation Entity Provider

Use these steps to create to create an entity provider based on the WS-Federation protocol for Federation Services. You can assign the identity provider or service provider (or both) role to the entity, but multiple roles will belong to the same entity provider.

  1. Log in as an administrator.

  2. Go to the Federation tab in the console and click New in the Entity Provider table.

  3. When prompted, select WS-FED as the entity provider.

  4. Select the Realm to which the entity provider will belong.

  5. Type a name in the Entity Identifier field.

  6. Choose the entity provider role you wish to assign to the entity provider.

    Entering data in the Meta Alias field will automatically create and assign the entity provider role to the entity provider upon completion.

  7. Enter values for the following attributes for one or more roles:

    Meta Alias

    Specifies a metaAlias for the provider role 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 coupled with a forward slash and the provider name. For example, /suncorp/travelprovider.


    Caution – Caution –

    The names used in the metaAlias must not contain a /.


    Signing Certificate Alias

    Specifies the provider certificate alias used to find the correct signing certificate in the keystore.

    Encryption Certificate alias

    Specifies the provider certificate alias used to find the correct encryption certificate in the keystore.

  8. Click Create.

    The entity provider, its assigned provider roles, and location will be displayed in the Entity Providers list.

  9. To customize the entity providers' roles behavior, click on the name of the entity provider and choose the tab that corresponds to the role you wish to customize. See Chapter 6, Federation Attributes for Entity Providers, in Sun OpenSSO Enterprise 8.0 Administration Reference for definitions attributes for provider customization.

Circle of Trust

A circle of trust, previously referred to as an authentication domain, is a federation of any number of service providers (and at least one identity provider) with whom principals can transact business in a secure and apparently seamless environment. To create and populate a circle of trust, you first create an entity to hold the metadata (configuration information that defines a particular identity service architecture) for each provider that will become a member of the circle of trust. Then, you configure and save the circle of trust. Finally, to add an entity (a configured provider) to the circle of trust, you edit the entity's properties.

The following tasks are associated with circles of trust:

ProcedureTo Create a New Circle of Trust

Follow this procedure to create a new circle of trust. The starting point is New Circle of Trust under the Federation interface.

  1. Click New to display the circle of trust attributes.

    The New circle of trust profile page is displayed.

  2. Type a name for the circle of trust.

  3. Type a description of the circle of trust in the Description field.

  4. Type a value for the IDFF Writer Service URL.

    The IDFF Writer Service URL specifies the location of the servlet that writes the common domain cookie. Use the format http://common-domain-host :port/deployment_uri/idffwriter.

  5. Type a value for the IDFF Reader Service URL.

    The IDFF Reader Service URL specifies the location of the servlet that reads the common domain cookie. Use the format http://common-domain-host :port/deployment_uri/idffreader.

  6. Type a value for the SAML2 Writer Service URL.

    This specifies the location of the SAML2 Writer service that writes the cookie to the common domain. Use the format http://common-domain-host :port/deployment_uri/saml2writer.

  7. Type a value for the SAML2 Reader Service URL.

    This specifies the location of the SAML2 Reader service that reads the cookie from the common domain. Use the format http://common-domain-host :port/deployment_uri/saml2reader.

  8. Choose Active or Inactive.

    The default status is Active. Choosing Inactive disables communication within the circle of trust.

  9. Select the Realm in which the circle of trust will be created.

  10. Choose one or more of the available providers and click the Add arrow to select them.

    The list provided contains the names of entities that have been created and populated with providers. For more information, see To Add Providers to a Circle of Trust.

  11. Click OK to complete the configuration.

    The new circle of trust is displayed in the Circle of Trust list.

ProcedureTo Modify a Circle of Trust Profile

Follow this procedure to edit the configured General attributes of an existing circle of trust, or to add providers to it. The starting point is Circle of Trust under the Federation interface.

  1. Click the name of a configured circle of trust to modify its profile, or to add providers to it.

    The Edit Circle of Trust page is displayed.

  2. Type new values or edit existing values for the circle of trust's General attributes:

    Name

    The static value of this attribute is the name provided when you created the circle of trust.

    Description

    The value of this attribute is a description of the circle of trust. You may modify the description already entered, if applicable.

    IDFF Writer Service URL

    This attribute specifies the location of the service that writes the common domain cookie. The URL is in the format http://common-domain-host:port/deployment_uri/idffwriter .

    IDFF Reader Service URL

    This attribute specifies the location of the service that reads the common domain cookie. The URL is in the format http://common-domain-host:port/deployment_uri//idffreader .

    SAML2 Writer URL

    This attribute specifies the location of the SAML2 Writer service that writes the cookie to the Common Domain. The URL is in the format http://common-domain-host:port/deployment_uri/saml2writer

    SAML2 Reader URL

    This attribute specifies the location of the SAML2 Writer service that writes the cookie to the Common Domain. The URL is in the format http://common-domain-host:port/deployment_uri/saml2reader

    Status

    The default status is Active. Selecting Inactive disables communication within the circle of trust.

  3. Choose one or more of the available providers and click the Add arrow to select them.

    The list provided contains the names of entities that have been created and populated with providers. For more information, see To Add Providers to a Circle of Trust.

  4. Click Save to complete the operation.

ProcedureTo Add Providers to a Circle of Trust

Identity providers and service providers must first be configured within an entity before they are available to add to a circle of trust. Once created and populated with providers, the entity (and thus the providers it contains) can be assigned to a circle of trust.


Note –

An entity will not be visible in the Available Providers list until it has been populated with providers.


  1. Select one or more providers from the Available Providers list and click Add.

  2. Finish your configurations and click Save to complete the operation.

ProcedureTo Delete a Circle of Trust Profile

A circle of trust must be empty of providers before you delete it. Follow this procedure to delete an existing circle of trust.

  1. Check the box next to the name of the circle of trust you want to delete.

  2. Click Delete.

    Deleting a circle of trust does not delete the providers that belong to it.

Managing Federation Using ssoadm

The previous sections detailed how to create and configure entities and circles of trust using the OpenSSO Enterprise console. But entities can also be created and configured using the ssoadm command-line interface. Rather than filling in provider attribute values manually, you would create an XML file containing the provider attributes and corresponding values and import it using ssoadm.


Caution – Caution –

The format of the XML file used as input is based on the sms.dtd. Alterations to the DTD files may hinder the operation of OpenSSO Enterprise.


This section contains the following information:

Managing Entity Metadata using ssoadm

ssoadm is used to manage the provider metadata. The following table describes the ssoadm subcommands specific to metadata management.

Table 7–1 ssoadm Subcommands for Managing Metadata

Subcommand 

Description 

import-entity

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


Note –

Use the –spec option to specify saml2 , idff, or wsfed.


export-entity

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


Note –

Use the –spec option to specify saml2 , idff, or wsfed.


create-meadata-templ

Generates a metadata configuration file for any provider type with defined values for default metadata properties. The generated file can be modified for use with import-entity.


Note –

Use the –spec option to specify saml2 , idff, or wsfed.


delet-entity

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


Note –

Use the –spec option to specify saml2 , idff, or wsfed.


list-entities

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


Note –

Use the –spec option to specify saml2 , idff, or wsfed.


update-entity-key-info

Update XML signing and encryption key information for a hosted IDP or SP. 

There are two types of entity provider metadata (formatted in XML files) that can be used as input to ssoadm:

Information regarding the attributes and possible values of the metadata can be found in Chapter 6, Federation Attributes for Entity Providers, in Sun OpenSSO Enterprise 8.0 Administration Reference. The following sections contain information on loading the metadata.

Loading Standard Metadata Using ssoadm

To load metadata compliant with the Liberty ID-FF, SAMLv2, or WS-Federation protocols, use the following command (options in square brackets are optional):


ssoadm import-entity --amadmin admin-ID
 --password-file password_filename [--realm] 
realm-name[--metadata-file] metadatafilename [--cot] circle_of-trust [--spec] idff_or_saml2_or_wsfed_or_wsfed

This option is usually used to load provider metadata sent from a trusted partner in an XML file Here is an example of a service provider metadata XML file compliant with the Liberty ID-FF.


Example 7–1 Service Provider Standard Metadata XML File


<!--
  Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved
  Use is subject to license terms.
-->

<EntityDescriptor meta:providerID="http://sp10.com" meta:cacheDuration="360" 
xmlns:meta="urn:liberty:metadata:2003-08" xmlns="urn:liberty:metadata:2003-08">
  <SPDescriptor cacheDuration="180" xmlns:meta="urn:liberty:metadata:2003-08" 
   aaa="aaa" protocolSupportEnumeration="urn:liberty:iff:2003-08">
   <KeyDescriptor use="signing">
    <EncryptionMethod>http://something/encrypt</EncryptionMethod>
     <KeySize>4567</KeySize>
     <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
     <ds:X509Data xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
     <ds:X509Certificate xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      MIIC1DCCApICBD8poYwwCwYHKoZIzjgEAwUAMFAxCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNTdW4x
      IDAeBgNVBAsTF1NVTiBPTkUgSWRlbnRpdHkgU2VydmVyMREwDwYDVQQDEwhzdW4tdW5peDAeFw0w
      MzA3MzEyMzA5MDBaFw0wNDAxMjcyMzA5MDBaMFAxCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNTdW4x
      IDAeBgNVBAsTF1NVTiBPTkUgSWRlbnRpdHkgU2VydmVyMREwDwYDVQQDEwhzdW4tdW5peDCCAbcw
      ggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLfSpwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR
      +1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUP
      BPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/IiAxmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1
      AoGBAPfhoIXWmz3ey7yrXDa4V7l5lK+7+jrqgvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0SRZxI+hM
      KBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8ftiegEkO8yk8b6oUZCJqIPf4Vrl
      nwaSi2ZegHtVJWQBTDv+z0kqA4GEAAKBgCNS1il+RQAQGcQ87GBFde8kf8R6ZVuaDDajFYE4/LNT
      Kr1dhEcPCtvL+iUFi44LzJf8Wxh+eA5K1mjIdxOo/UdwTpNQSqiRrm4Pq0wFG+hPnUTYLTtENkVX
      IIvfeoVDkXnF/2/i1Iu6ttZckimOPHfLzQUL4ldL4QiaYuCQF6NfMAsGByqGSM44BAMFAAMvADAs
      AhQ6yueX7YlD7IlJhJ8D4l6xYqwopwIUHzX82qCzF+VzIUhi0JG7slSpyis=
     </ds:X509Certificate>
     </ds:X509Data>
     </ds:KeyInfo>
   </KeyDescriptor>
   <SingleLogoutServiceURL>http://www.sun.com/slo"</SingleLogoutServiceURL>
   <SingleLogoutServiceReturnURL>http://www.sun.com/sloservice
    </SingleLogoutServiceReturnURL>
   <FederationTerminationServiceURL>http://www.sun.com/fts
    </FederationTerminationServiceURL>
   <FederationTerminationServiceReturnURL>http://www.sun.com/ftsr
    </FederationTerminationServiceReturnURL>
   <FederationTerminationNotificationProtocolProfile>
       http://projectliberty.org/profiles/
    fedterm-sp-http</FederationTerminationNotificationProtocolProfile>
   <SingleLogoutProtocolProfile>http://projectliberty.org/profiles/slo-sp-http
    </SingleLogoutProtocolProfile>
   <RegisterNameIdentifierProtocolProfile>http://projectliberty.org/profiles/
    rni-sp-http</RegisterNameIdentifierProtocolProfile>
   <RegisterNameIdentifierServiceURL>http://www.sun2.com/risu
    </RegisterNameIdentifierServiceURL>
   <RegisterNameIdentifierServiceReturnURL>http://www.sun2.com/rstu
    </RegisterNameIdentifierServiceReturnURL>
   <RelationshipTerminationNotificationProtocolProfile>http://projectliberty.org/
    profiles/rel-term-soap</RelationshipTerminationNotificationProtocolProfile>
   <NameIdentifierMappingBinding AuthorityKind="ppp:AuthorizationDecisionQuery" 
    Location="http://eng.sun.com" Binding="http://www.sun.com" 
    xmlns:ppp="urn:oasis:names:tc:SAML:1.0:protocol"></NameIdentifierMappingBinding>
   <AdditionalMetaLocation namespace="abc">http://www.aol.com</AdditionalMetaLocation>
   <AdditionalMetaLocation namespace="efd">http://www.netscape.com</AdditionalMetaLocation>
   <AssertionConsumerServiceURL id="jh899" isDefault="true">
    http://www.iplanet.com/assertionurl</AssertionConsumerServiceURL>
   <AuthnRequestsSigned>true</AuthnRequestsSigned>
  </SPDescriptor>
  <ContactPerson xmlns:meta="urn:liberty:metadata:2003-08" contactType="technical" 
   meta:libertyPrincipalIdentifier="myid">
  <Company>SUn Microsystems</Company>
  <GivenName>Joe</GivenName>
  <SurName>Smith</SurName>
  <EmailAddress>joe@sun.com</EmailAddress> 
  <EmailAddress>smith@sun.com</EmailAddress>
  <TelephoneNumber>45859995</TelephoneNumber>
  </ContactPerson>	
  <Organization xmlns:xml="http://www.w3.org/XML/1998/namespace">
  <OrganizationName xml:lang="en">sun com</OrganizationName>
  <OrganizationName xml:lang="en">sun micro com</OrganizationName>
  <OrganizationDisplayName xml:lang="en">sun.com</OrganizationDisplayName>
  <OrganizationURL xml:lang="en">http://www.sun.com/liberty</OrganizationURL>
  </Organization>
</EntityDescriptor>

Loading Extended Metadata Using ssoadm

OpenSSO Enterprise provides proprietary attributes that are not a specific part of the Liberty ID-FF, WS-Federation, or SAMLv2 protocols. To load OpenSSO Enterprise proprietary metadata use the following command:


ssoadm import-entity --amadmin admin-ID --password-file 
password_filename [--realm realm-name] [--meta-data-file
 metadatafilename] [--extended-data-file extended_metadata_filename] [--cot circle_of-trust] [--spec]idff_or_saml2_or-wsfed]

After loading the metadata, the ssoadm export-entity option can be used to export metadata. This file can then be exchanged with trusted partners. Here is an example of an identity provider metadata XML file for proprietary attributes.


Example 7–2 Identity Provider Extended Metadata XML File


<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Requests PUBLIC "-//iPlanet//Sun Access Manager 2005Q4 Admin CLI 
DTD//EN"    "jar://com/iplanet/am/admin/cli/amAdmin.dtd">
<Requests>
   <OrganizationRequests DN="dc=companyA,dc=com">
      <CreateHostedProvider id="http://sp.companyA.com" role="SP" 
       defaultUrlPrefix="http://sp.companyA.com:80">
          <AttributeValuePair>
              <Attribute name="iplanet-am-provider-name"/>
              <Value>sp</Value>
          </AttributeValuePair>
          <AttributeValuePair>
              <Attribute name="iplanet-am-provider-alias"/>
              <Value>sp.companyA.com</Value>
          </AttributeValuePair>
          <AttributeValuePair>
              <Attribute name="iplanet-am-list-of-authenticationdomains"/>
              <Value>samplecot</Value>
          </AttributeValuePair>
          <AttributeValuePair>
              <Attribute name="iplanet-am-certificate-alias"/>
              <Value>cert_alias</Value>
          </AttributeValuePair>
          <AttributeValuePair>
              <Attribute name="iplanet-am-trusted-providers"/>
              <Value>http://idp.companyB.com</Value>
              <Value>http://idp.companyC.com</Value>
          </AttributeValuePair>
          <SPAuthContextInfo AuthContext="Password" AuthLevel="1"/>
          <AttributeValuePair>
              <Attribute name="iplanet-am-provider-homepage-url"/>
              <Value>http://sp.companyA.com:80/idff/index.jsp</Value>
          </AttributeValuePair>
      </CreateHostedProvider>
  </OrganizationRequests>
</Requests>

Managing Circles of Trust Using ssoadm

The ssoadm command line interface creates and manages the circles of trust used by the Federation services. The following table describes the ssoadm subcommands specific to circle of trust management.

Table 7–2 ssoadm Subcommands for Managing Circles of Trust

Subcommand 

Description 

create-cot

Creates a circle of trust. 

delete-cot

Removes a circle of trust. 


Note –

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


add-cot-member

Adds a trusted provider to an existing circle of trust. 


Note –

add-cot-member can only add a single entity at a time. Add multiple entities when you first create the circle by using create-cot and the ---trustedproviders option.


remove-cot-member

Removes a trusted provider from an existing circle of trust. 

list-cot-members

Lists the member providers in a particular circle of trust. 

list-cots

Lists all the circles of trust configured on the system. 

The following command example will create a circle of trust:


ssoadm create-cot --cot COT-name --adminid 
admin-user --password-file password-filename 
[--realm realm-name] [--trustedproviders 
trusted-providers] [--prefix idp-discovery-URL-prefix]

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


ssoadm add-cot-member --cot COT-name --enitityid 
entitiy_ID --adminid admin-user --password-file 
password [--realm realm-name] 
[--spec saml2-or-idff]

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


ssoadm remove-cot-member --cot COT-name --enitityid 
entitiy_ID --adminid admin-user --password-file 
password [--realm realm-name] 
[--spec saml2-or-idff]

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


ssoadm list-cot-members --cot COT-name --adminid admin-user 
--password-file password [--realm realm-name]
 [--spec saml2-or-idff]

This command example will list all the available circles of trust:


ssoadm list-cots  --adminid admin-user --password-file password 
[--realm realm-name]

Chapter 8 Federated Operations

This chapter contains procedures illustrating how to use OpenSSO Enterprise to configure interactions based on the ID-FF and SAMLv2 protocols. The sections contained in this chapter are:

Finding an Identity Provider for Authentication

If there is only one Identity Provider in a Circle-of-Trust, Service Providers will send users directly to the Identity Provider for authentication. In the case when there are multiple Identity Providers in a Circle-of-trust, a Service Provider requires a way to determine which identity provider is used by a principal requesting authentication. Because Service Providers are configured without regard to their location, this function must work across DNS-defined domains. OpenSSO Enterprise implements the following solutions for this use case:

When these services are configured, the Service Provider determines and redirects the user agent to the appropriate identity provider for authentication. The following sections contain more information.

Configuring the SAMLv2 Identity Provider Discovery Service

The SAMLv2 Identity Provider Discovery Service is provided by OpenSSO Enterprise after deployment. Alternatively, the Identity Provider Discovery Service can be configured as a standalone service. After the SAMLv2 Identity Provider Discovery Service is configured, an administrator creates and configures a Circle-of-Trust to use the Identity Provider Discovery service for the IDPs and SPs. In OpenSSO Enterprise, the Identity Provider Discovery Service for SAMLv2 providers is configured using two URLs that point to servlets developed for writing and reading a special cookie called Common Domain cookie. Go to the circle-of-trust entity and configure the following:

SAMLv2 Writer Service URL

The Writer Service URL is used by the identity provider. After successful authentication, the common domain cookie is appended with the query parameter _saml_idp=entity-ID-of-identity-provider. This parameter is used to redirect the principal to the Writer Service URL defined for the identity provider. The URL is configured as the value for the SAML2 Writer Service URL attribute when a circle of trust is created. Use the format http://idp-discovery-host:port/deployment-uri/writer where idp-discovery-host:port refers to the machine on which the SAMLv2 Identity Provider Discovery service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

SAMLv2 Reader Service URL

The Reader Service URL is used by the service provider. The service provider redirects the principal to this URL in order to find the preferred identity provider. Once found, the principal is redirected to the identity provider for single sign-on. The URL is defined as the value for the Reader Service URL attribute when a circle of trust is created. It is formatted as http://idp-discovery-host:port/deployment-uri/transfer where idp-discovery-host:port refers to the machine on which the SAMLv2 IDP Discovery service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

Configuring the ID-FF Identity Provider Introduction Service

OpenSSO Enterprise provides the Liberty ID-FF Identity Provider Introduction Service upon deployment. Alternatively, the Identity Provider Introduction Service could be configured as a standalone service (refer to later section for details).

After the Liberty ID-FF Identity Provider Introduction Service is configured, an administrator needs create and configure a Circle-of-Trust to use the service. In OpenSSO Enterprise, the Identity Provider Introduction Service for ID-FF providers is configured using two URLs that point to servlets developed for writing and reading a special cookie called Common Domain cookie. Go to the circle-of-trust entity and configure the following:

ID–FF Writer Service URL

The Writer Service URL is used by the identity provider. After successful authentication, the common domain cookie is appended with the query parameter _liberty_idp=entity-ID-of-identity-provider. This parameter is used to redirect the principal to the ID-FF Writer Service URL defined for the identity provider. The URL is configured as the value for the ID-FF Writer Service URL attribute when a circle of trust is created. Use the format http://idp-introduction-host:port/deployment-uri/idffwriter where idp-introduction-host:port refers to the machine on which the ID-FF Identity Provider Introduction service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

ID-FF Reader Service URL

The ID-FF Reader Service URL is used by the service provider. The service provider redirects the principal to this URL in order to find the preferred identity provider. Once found, the principal is redirected to the identity provider for single sign-on. The URL is defined as the value for the ID-FF Reader Service URL attribute when a circle of trust is created. It is formatted as http://idp-introduction-host:port/deployment-uri/transfer where idp-intorductoin-host:port refers to the machine on which the ID-FF Identity Provider Introduction service is installed and deployment-uri tells the web container where to look for information specific to the application (such as classes or JARs).

Configuring WS-Federation Home Realm Discovery Service

To configure a WS-Federation service provider to use the Home Realm Discovery Service, click on the WS-Federation entity name in the OpenSSO Enterprise console, select the Service Provider (SP) tab and configure the following:

Home Realm Discovery

Specifies the service so that the service provider can identify the preferred identity provider. The service URL is specified as a contact endpoint by the service provider.

Account Realm Selection

Specifies the identity provider selection mechanism and configuration. Either the cookie or HTTP Request header attribute can be used to locate the identity provider.

Customizing SAMLv2 the Identity Provider Discovery Service and the ID-FF Identity Provider Introduction Service

There are two ways to obtain the SAMLv2 IDP Discovery Service/ID-FF IDP Introduction service:

  1. Create and deploy a specialized WAR file used for the SAMLv2 Identity Provider Discovery Service and ID-FF Identity Provider Introduction Service only. See To Create a Specialized WAR file for the Identity Provider Services.

  2. Customize the SAMLv2 Identity Provider Discovery Service and ID-FF Identity Provider Introduction Service through the console. See To Customize the Identity Provider Services Through the Console.

ProcedureTo Create a Specialized WAR file for the Identity Provider Services

OpenSSO Enterprise provides a mechanism to create a specialized WAR file for the SAMLv2 Identity Provider Discovery Service and the ID-FF Identity Provider Introduction Service. The WAR file can be deployed as standalone application, independent of Identity Provider and Service Provider domains. See Creating and Deploying Specialized OpenSSO Enterprise WAR Files in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

  1. After you deploy and run the Configurator for the specialized WAR file, locate the configuration property file named libIDPDiscoveryConfig.properties.

    This file is created under the web container user's home directory. This file is the same for both the SAMLv2 IDP Discovery service and the ID-FF IDP Introduction service.

  2. Customize the following properties to meet your specific deployment needs:

    com.sun.identity.federation.services.introduction.cookiedomain

    The value of this property is the name of the common domain.

    com.sun.identity.federation.services.introduction.cookietype

    This property takes a value of either PERSISTENT or SESSION. PERSISTENT defines the cookie as one that will be stored and reused after a web browser is closed and reopened. SESSION defines the cookie as one that will not be stored after the web browser has been closed.

    com.iplanet.am.cookie.secure

    This property takes a value of either false or true. It defines whether the cookie needs to be secured or not.

    com.iplanet.am.cookie.encode

    This property takes a value of either false or true. It defines whether the cookie will be URL encoded or not. This property is useful if, for example, the web container that reads or writes the cookie decrypts or encrypts it by default.

ProcedureTo Customize the Identity Provider Services Through the Console

  1. Login to the console as top level administrator.

  2. Click the Configuration tab.

  3. Click the Global sub-configuration tab.

  4. Select the SAMLv2 Service Configuration service.

  5. Customize the following attributes. These attributes are applicable for both the SAMLv2 Identity Provider Discovery Service and ID-FF Identity Provider Introduction Service:

    Cookie Domain for IDP Discovery Service

    Specifies the cookie domain for the SAMLv2 IDP discovery cookie.

    Cookie Type for IDP Discovery Service

    Specifies cookie type used in SAMLv2 IDP Discovery Service, either Persistent or Session. Default is Session.

    URL Scheme for IDP Discovery Service

    Specifies URL scheme used in SAMLv2 IDP Discovery Service.

Bulk Federation

OpenSSO Enterprise handles the federation of user accounts in bulk through the ssoadm command line tool. From the service provider, import the metadata to create the bulk federation data. The full command is as follows:


ssoadm do-bulk-fed-data --metaalias meta_alias --remote-entity-id 
entity_ID--useridmapping id-mapping-filename --name-id-mapping 
created_nameid_filename --adminid administrator_ID
 --password-file password_filename --spec idff_or_saml2_or_wsfed

As input, the command takes a file that maps the user distinguished name (DN) of the identity provider to the user DN of the service provider. You specify this in the –useridmapping option of the do-bulk-federation subcommand. The format is the full DN of local-user-id|remote-user-id. For example:


id=spuser1,ou=user,dc=red,dc=iplanet,dc=com|id=idpuser1,
ou=user,dc=red,dc=iplanet,dc=com
id=spuser2,ou=user,dc=red,dc=iplanet,dc=com|id=idpuser2,
ou=user,dc=red,dc=iplanet,dc=com
id=spuser3,ou=user,dc=red,dc=iplanet,dc=com|id=idpuser3,
ou=user,dc=red,dc=iplanet,dc=com
id=spuser4,ou=user,dc=red,dc=iplanet,dc=com|id=idpuser4,
ou=user,dc=red,dc=iplanet,dc=com

Note –

The users defined in this file must already exist in the identity provider and service provider.


To load the bulk data into an identity provider, use the following command. The bulk federation file created by the do-bulk-federation subcommand is specified in the bulk-data-file option:


ssoadm import-bulk-fed-data --meta-aslias meta_alias --bulk-data-file 
bulk_federation_filename --adminid administrator_ID --password-
file password_filename --spec idff_or_saml2_or_wsfed

ID-FF Federation Operations

This section describes Federation operations that are specific to the ID-FF protocol.

The Pre-Login URL

The pre-login process is the entry point for applications participating in Liberty-based single sign-on. The principal would be redirected to the location defined by the pre-login URL if no OpenSSO Enterprise session token is found. This default process, though, can be modified based on the values of query parameters passed to OpenSSO Enterprise by the service provider within a URL.

A query parameter is a name/value pair appended to the end of a URL. The parameter starts with a question mark (?) and takes the form name=value. A number of parameters can be combined in one URL; when more than one parameter exists, they are separated by an ampersand (&). Use the format http://hostname:port/deploy-uri/preLogin?metaAlias=metaAlias. Additional parameters are appended to the URL as &param1=value1&param2=value2 and so on. These parameters and their usage and values are described in the following table.

Table 8–1 Pre-login URL Parameters for Federation

Parameter 

Description 

actionOnNoFedCookie

The actionOnNoFedCookie parameter provides the flexibility to redirect a user when the fedCookie is not present in the browser, and when there is only one identity provider. It takes the following values:

  • commonlogin will redirect to a common login page.

  • locallogin will redirect to the local OpenSSO Enterprise login page.

  • passive will issue a request to the identity provider by setting the isPassive parameter of the AuthnRequest element to true.

  • active will issue a normal single sign-on request to the identity provider.

anonymousOnetime

The anonymousOnetime parameter can be used by service providers that authenticate users with anonymous, one time federation sessions. A value of true enables the service provider to issue a one time federation request and generate an anonymous session after successful verification of the authentication assertion from the identity provider. This feature is useful when the service provider doesn't have a user repository (for example, http://www.weather.com) but would like to depend on an identity provider for authentication. When the service provider receives a successful authentication assertion from an identity provider, they would generate an anonymous, temporary session.

authlevel

The authlevel parameter takes as a value a positive number that maps to an authentication level defined in the OpenSSO Enterprise Authentication Framework. The authentication level indicates how much to trust a method of authentication.

In this framework, each service provider is configured with a default authentication context (preferred method of authentication). However, the provider might like to change the assigned authentication context to one that is based on the defined authentication level. For example, provider B would like to generate a local session with an authentication level of 3 so it requests the identity provider to authenticate the user with an authentication context assigned that level. The value of this query parameter determines the authentication context to be used by the identity provider. 

goto

The goto parameter takes as a value a URL to which the principal will be redirected after a successful SSO. If the value is not specified, default redirection will occur based on the value of the Provider Home Page URL attribute defined in the service provider configuration. The value of this URL can be configured by changing the iplanet-am-provider-homepage-url attribute in the amProviderConfig.xml file.

gotoOnFedCookieNo

The gotoOnFedCookieNo parameter takes as a value a URL to which the principal is redirected if a fedCookie with a value of no is found. The default behavior is to redirect the user to the OpenSSO Enterprise login page.

In order to modify the pre-login URL, edit the relevant properties in either the AMConfig.properties file or the AMAgent.properties file, dependent on your deployment.

ProcedureTo Configure for Pre-login

In a federation setup, OpenSSO Enterprise acts as a service provider and manages an application that runs on a separate instance of Sun Java System Web Server. You must configure the agent that is protecting this application as follows:

  1. Point the com.sun.am.policy.loginURL property in the AMAgent.properties file to the pre-login service URL running on OpenSSO Enterprise.

    For example: com.sun.am.policy.loginURL = http://www.sp1.com:58080/opensso/preLogin?metaAlias=www.sp1.com

  2. Point the com.sun.am.policy.am.library.loginURL in the AMAgent.properties file to the login URL of the instance of OpenSSO Enterprise acting as the service provider.

    For example: com.sun.am.policy.am.library.loginURL = http://www.sp1.com:58080/opensso/UI/Login

ProcedureTo Configure for Global Logout

To implement the logout process for all service providers using the Liberty Logout method, do the following:

  1. Copy the AMClient.properties file to the service provider's web container.

  2. Revise the Logout method, as follows:

    ResourceBundle rsbu =ResourceBundle.getBundle("AMClient"); String logouturl = rsbu.getString ("com.sun.identity.federation.client.samples.logoutURL"); response.sendRedirect(logouturl);

    This revision is equivalent to a redirection to http://www.sp1.com:58080/opensso/liberty-logout?metaAlias=www.sp1.com.

Configuring ID-FF Single Sign-on

To setup single sign-on between two OpenSSO Enterprise instances for ID-FF protocol, one as an identity provider and one as a service provider, follow these steps:

ProcedureTo Configure ID-FF Single Sign-on

  1. Create an ID-FF identity provider. For instructions, see To Create an ID-FF Entity Provider.

  2. Export the standard identity provider metadata into an XML file using the ssoadm command's export-entity subcommand. The example filename for these instructions is IDP.xml.

  3. Create an ID-FF service provider. For instructions, see To Create an ID-FF Entity Provider


    Note –

    If the identity provider and service provider reside in the same domain, you need to modify the cookie name of one instance to be different from the other. To do so, log in to the OpenSSO Enterprise and go to Configuration>Servers and Sites, then choose the server instance. Click the Security>Inheritance Settings, and uncheck the Cookie Name field. Click Save.

    Click Back to Server Profile, go to the Cookie section, and modify the value for Cookie Name. Click Save. Restart the web container.


  4. Export the standard identity provider metadata into an XML file using the ssoadm command's export-entity subcommand. The example filename for these instructions is SP.xml.

  5. Load the remote service provider metadata to the OpenSSO Enterprise instance of the identity provider. To do so:

    1. Copy the SP.xml file to the identity provider instance.

    2. Log in to the console on the identity provider instance and click on the Federation tab.

    3. Click the Import Entity button.

    4. Choose the realm to which the identity provider resides.

    5. Select the File option and click upload to locate the SP.xml file. You can leave the extended metadata field blank.

  6. In the Federation tab, create a circle of trust and add the identity provider and service provider. For instructions, see To Create a New Circle of Trust.

  7. Load the identity provider metadata to the OpenSSO Enterprise instance of the service provider. To do so:

    1. Copy the IDP.xml file to the identity provider instance.

    2. Log in to the console on the identity provider instance and click on the Federation tab.

    3. Click the Import Entity button.

    4. Choose the realm to which the identity provider resides.

    5. Select the File option and click upload to locate the IDP.xml file. You can leave the extended metadata field blank.

  8. In the Federation tab, create a circle of trust and add the identity provider and service provider. For instructions, see To Create a New Circle of Trust.

    Single Sign-on is now established between the OpenSSO Enterprise instances.

ID-FF Auto-Federation

The auto-federation feature in OpenSSO Enterprise will automatically federate a user's disparate provider accounts based on a common attribute. This common attribute will be exchanged in a single sign-on assertion so that the consuming service provider can identify the user and create account federations. If auto-federation is enabled and it is deemed that a user at provider A and a user at provider B have the same value for the defined common attribute (for example, emailaddress), the two accounts will be federated automatically without principal interaction on the service provider side (that is, without login on the service provider side).


Note –

Auto-federating a principal's two distinct accounts at two different providers requires each provider to have agreed to implement support for this functionality beforehand.


ProcedureTo Enable ID-FF Auto Federation

Ensure that single sign-on is properly configured. For more information, see To Configure ID-FF Single Sign-on. Remote providers would not be configured in your deployment.

  1. In the OpenSSO Enterprise Console, click the Federation tab.

  2. Select the name of the identity provider to edit its profile.

  3. Click on the Auto Federation link at the top of the page, or scroll down to the Auto Federation subsection.

  4. Enable Auto Federation by checking the box.

  5. Type a value for the Auto Federation Common Attribute Name attribute.

    For example, enter emailaddress or userID. You should be sure that each participating user profile (at both providers) has a value for this attribute.

  6. Click the Identity Provider Attribute Mapper link, or scroll down to the Identity Provider Attribute Mapper subsection. Enter the following attribute values:

    Attribute Mapper Class

    com.sun.identity.federation.services.FSDefaultRealmAttributeMapper

    Identity Provider Attribute Mapping

    Enter the mapping for the Auto-Federation attribute name.

  7. Click the Plug-ins link, or scroll down to the Plug-ins subsection. Enter the following attribute value:

    Attribute Statement Plug-in

    com.sun.identity.federation.services.FSDefaultRealmAttributePlugin

  8. Click Save to complete the identity provider configuration.

  9. Go back to the Federation tab and select the service provider you wish to edit.

  10. Click on the Auto Federation link at the top of the page, or scroll down to the Auto Federation subsection.

  11. Enable Auto Federation by checking the box.

  12. Type a value for the Auto Federation Common Attribute Name attribute.

    For example, enter emailaddress or userID. You should be sure that each participating user profile (at both providers) has a value for this attribute.

  13. Click the Service Provider Attribute Mapper link, or scroll down to the Service Provider Attribute Mapper subsection. Enter the following attribute values:

    Attribute Mapper Class

    com.sun.identity.federation.services.FSDefaultRealmAttributeMapper

    Identity Provider Attribute Mapping

    Enter the mapping for the Auto-Federation attribute name.

  14. Click Save to complete the configuration.

Enabling ID-FF XML Signing

By default, ID-FF singing is turned off. To enable ID-FF XML signing on OpenSSO Enterprise server, see the following section:

ProcedureTo Enable ID-FF XML Signing

  1. Login to the console as the top-level administrator.

  2. Select the Configuration tab, select Global, and then Liberty ID-FF Service Configuration.

  3. Select YES for the XML Signing On attribute and save the configuration.

  4. Go to the Federation tab and select the service provider and/or identity provider that needs to be enabled.

  5. Under the Common Attributes section, make sure a signing certificate alias is chosen for the provider. Otherwise, you must enter your certification alias.

    If the certificate alias is added or changed, you need to send the new metadata (to be exported using ssoadm CLI) to the remote party to update its metadata.

  6. Click Save.

  7. Restart the server.

Dynamic Identity Provider Proxying

An identity provider that is asked to authenticate a principal that has already been authenticated with another identity provider may proxy the authentication request, on behalf of the requesting service provider, to the authenticating identity provider. This is called dynamic identity provider proxying. When the first identity provider (referred as Proxying Identity Provider) receives an authentication request regarding a principal, it prepares a new authentication assertion on its own behalf by referencing the relevant information from the original assertion and sending the assertion to the authenticating identity provider. After receiving the Assertion from the authenticating identity provider, the proxying identity provider generates a new Assertion based on the information from the original Assertion, and sends to the requesting service provider.


Note –

The service provider requesting authentication may control this proxy behavior by setting a list of preferred identity providers or by defining the amount of times the identity provider can proxy the request.


ProcedureTo Configure and Test Dynamic Identity Provider Proxying

The following steps describe the procedure to enable three machines for identity provider proxying and test the configuration. The procedure assumes the three machines have OpenSSO Enterprise installed and are configured as follows:

Machine 

Authentication Function 

Federation Function 

Machine 1 

Authenticating Identity Provider 

Identity Provider 

Machine 2 

Proxying Identity Provider 

Identity Provider and Service Provider 

Machine 3 

Requesting Service Provider 

Service Provider 

  1. Install and configure three OpenSSO instances.

    If those three instances resides on the same domain, you need to modify the cookie name of all three instances to be different from one another. To do so:

    1. Login to administration console and click the Configuration tab.

    2. Click Servers and Sites and choose your server instance.

    3. Click the Security tab, then click Inheritance Settings.

    4. Uncheck the box for the Cookie Name attribute.

    5. Click Save.

    6. Click the Back to Server Profile button.

    7. Modify the value for the Cookie Name attribute under the Cookie section.

    8. Click Save.

    9. Restart the web container on which the server instance is deployed.

  2. Create hosted ID-FF metadata on the requesting service provider instance on machine 3.

    For more information, see ID-FF Entity Provider. When creating the provider:

    1. Enter the service provider entity ID in the Entity Identifier field

    2. Under the Service Provider section, specify meta alias, signing/encryption cert alias if needed.

  3. Export the requesting Service Provider's standard metadata to a XML file. This could be done using the export-entity option in ssoadm CLI or the ssoadm.jsp. The rest of these steps use the file name sp.xml as an example.

  4. Create hosted metadata on the proxying Identity provider instance, o machine 2.

    1. Login to machine 2 as the top-level administrator, click Federation, then click New under Entity Providers table.

    2. Select IDFF in the pop up window

    3. Save the configuration.

    4. Enter the entity ID in the Entity Identifier field.

    5. Under the Identity Provider section, specify a meta alias, and enter signing/encryption cert alias if needed.

    6. Under the Service Provider section, specify a meta alias different from that entered for Identity Provider section, and enter signing/encryption cert alias if needed.

    7. Click create.

  5. Export the proxying identity provider's standard metadata to a XML file. This is done using the export-entity option in ssoadm CLI or ssoadm.jsp. The rest of these steps use the file name proxy.xml as an example.

  6. Create the hosted metadata on the authenticating Identity provider instance, machine 1.

    For more information, see ID-FF Entity Provider. When creating the provider:

    1. Enter the service provider entity ID in the Entity Identifier field

    2. Under the Service Provider section, specify meta alias, signing/encryption cert alias if needed.

  7. Export the authenticating Identity provider's standard metadata to a XML file using the export-entity option in the ssoadm CLI or by using the ssoadm.jsp. The rest of these steps use the file name idp.xml as an example.

  8. Load the remote proxying identity provider metadata on the requesting service provider instance.

    1. Copy the proxy.xml to machine 3.

    2. In the console of machine 3, click the Federation tab and then the Import Entity button.

    3. Choose the realm to which the requesting service provider belongs.

    4. Under Where Does the Meta Data File Reside field, choose File and click Upload.

    5. Choose proxy.xml. The Where Does the Extended Data File Reside can be left blank.

    6. Click Ok.

  9. Create a circle of trust on the requesting service provider instance to include the proxying IDP and requesting SP entity. For information, see Circle of Trust.

  10. Load the remote authenticating identity provider and requesting service provider metadata to the proxying identity provider instance.

    1. Copy the idp.xml and sp.xml files to machine 2.

    2. In the console of machine 2, click the Federation tab and then the Import Entity button.

    3. Choose the realm to which the requesting service provider belongs.

    4. Under Where Does the Meta Data File Reside field, choose File and click Upload.

    5. Choose idp.xml. The Where Does the Extended Data File Reside field can be left blank.

    6. Click OK.

    7. Repeat the steps for loading the requesting service provider meta data (sp.xml).

  11. Create circles of trust on the proxying identity provider instance, machine 2. For information, see Circle of Trust

    Add the requesting service provider and proxying identity provider to the circle of trust. Repeat this step to create a circle of trust for both the authenticating identity provider and the proxying identity provider. Make sure the circles of trust have different names.

  12. Load the remote proxying identity provider metadata on the authenticating identity provider instance, machine 1.

    1. Copy the proxy.xml to machine 1.

    2. In the console of machine 1, click the Federation tab and then the Import Entity button.

    3. Choose the realm to which the requesting service provider belongs.

    4. Under Where Does the Extended Data File Reside field, choose File and click Upload.

    5. Choose proxy.xml. The Where Does the Extended Data File Reside can be left blank.

    6. Click Ok.

  13. Create a create a circle of trust on the authenticating identity provider instance to include the proxying identity provider and authenticating identity provider entities.

  14. Enable Dynamic Identity provider proxying on the requesting service provider instance.

    1. In the console of machine 3, click the Federation tab.

    2. Select the hosted requesting service provider.

    3. Go to Proxy Authentication Configuration.

    4. Check the box for Proxy Authentication to enable it.

    5. Enter 10 for the value in the Maximum Number of Proxies attribute.

    6. Click Save.

  15. Enable dynamic identity provider proxying on the proxying identity provider instance.

    1. In the console of machine 2, click the Federation tab.

    2. Select the hosted proxying identity provider.

    3. Go to Proxy Authentication Configuration.

    4. Check the box for Proxy Authentication to enable it.

    5. Enter 10 for the value in the Maximum Number of Proxies attribute.

    6. Add the authenticating identity provider's entity ID in the Proxy Identity Providers List file.

    7. Click Save.

  16. Federate a user between machine 3 (acting as a service provider) and machine 2 (acting as an identity provider).

  17. Federate a user between machine 2 (acting as a service provider) and machine 1 (acting as an identity provider).

  18. Close the browser and attempt to perform a single sign-on again from machine 3. You will be redirected to machine 1 rather than machine 2 for authentication.

    Enter the username and password used on machine 1. You will have a successful single sign-on to machine 3.

SAMLv2 Operations

The SAMLv2 specification defines the assertion security token format as well as profiles that standardize the HTTP exchanges required to transfer XML requests and responses between an asserting authority and a trusted partner. OpenSSO Enterprise supports a number of the defined profiles. This section describes how to configure for the operations defined by the SAMLv2 profiles using OpenSSO Enterprise. It covers the following topics.

POST Binding with Single Sign-on and Single Logout

HTTP POST binding is used for an identity provider response to a request from a service provider. To configure for POST binding, the following tags must be present in the identity provider standard metadata.

<IDPSSODescriptor
WantAuthnRequestsSigned="false"
protocolSupportEnumeration="urn:oasis:names:tc:
SAML:2.0:protocol">.
  <SingleLogoutService
   Binding="urn:oasis:names:tc:SAML:2.0:
   bindings:HTTP-POST"
   Location="http://isdev-3.red.com:
   58080/fam/IDPSloPOST/metaAlias/idp"
   ResponseLocation="http://isdev-3.red.com:
   58080/opensso/IDPSloPOST/metaAlias/idp"/>
  <SingleSignOnService
   Binding="urn:oasis:names:tc:SAML:2.0:bindings:
   HTTP-POST"
   Location="http://isdev-3.red.iplanet.com:58080/opensso/
   SSOPOST/metaAlias/idp"/>
</IDPSSODescriptor> 

To configure on the service provider side the standard metadata must include the following tags.

<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-POST"
 Location="http://mach1.red.com:58080/opensso/
 SPSloPOST/metaAlias/sp"
 ResponseLocation="http://mach1.red.com:58080/
 opensso/SPSloPOST/metaAlias/sp"/>
</SPSSODescriptor> 

idpSSOInit.jsp, spSSOInit.jsp, spSingleLogoutInit.jsp and idpSingleLogoutInit.jsp will initiate single sign-on or single logout using the proper binding. Supported values are urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect and urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST. An example URL for service provider initiated single logout might be http://mach1.red.com:58080/opensso/saml2/jsp/spSingleLogoutInit.jsp?metaAlias=/sp&idpEntityID=isdev-3.red.com&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

Creating Affiliations

To configure for affiliations, the following tags must be in the identity provider standard metadata.

<AffiliationDescriptor
 affiliationOwnerID="affi.red.com">
  <AffiliateMember>mach1.red.com</AffiliateMember>
  <AffiliateMember>mach2.red.com</AffiliateMember>
</AffiliationDescriptor>

The following tags must also be present in the identity provider extended metadata.

<AffiliationConfig metaAlias="/ff">
  <Attribute name="signingCertAlias">
   <Value>test</Value>
  </Attribute>
  <Attribute name="encryptionCertAlias">
   <Value>test</Value>
  </Attribute>
</AffiliationConfig> 

The ssoadm command line interface can be used to create and import the identity provider metadata. Use the following options to create the appropriate tags in the metadata. See Part I, Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference for more information.

--affiliation, -F

Specify a metaAlias for the hosted affiliation. The format must be realm name/identifier.

--affiscertalias, -J

Specify a signing certificate alias for the hosted affiliation.

--affiecertalias, -K

Specify an encryption certificate alias for the hosted affiliation.

--affimembers, -M

Specify affiliation members.

--affiownerid, -N

Specify the identifier for the Affiliation Owner.

An example illustrating how the command line might be used to create the metadata:

ssoadm create-metadata-templ -u amadmin 
-f /tmp/pw -m /home/tmp/affimm -x /home/tmp/affixx 
-F /ff -y affi.red.com -K test -J test -M sp1.red.com 
sp2.red.com -N affiownerID

Note –

See Chapter 1, ssoadm Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference for information on the other options.


idpMNIRequestInit.jsp, idpSSOInit.jsp, spMNIRequestInit.jsp and spSSOInit.jsp can initiate single sign-on based on a configured affiliation. The affiliationID parameter should match the value of the entity ID for the affiliation in the standard metadata. A URL to initiate single sign-on from the service provider might be:

http://mach1.red.com:58080/opensso/saml2/jsp/
spSSOInit.jsp?metaAlias=/sp&idpEntityID=isdev-3.red.com&reqBinding=
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST&affiliationID=affi.red.com

Requesting Attribute Values Using a SAMLv2 Assertion

Providers may request attributes (and the corresponding values) from a specific identity profile. A successful response is the return of an assertion containing the requested information. The identity provider acting as the attribute authority uses an implementation of the com.sun.identity.saml2.plugins.AttributeAuthorityMapper interface to process queries. The implementation uses the attribute map table configured in the identity provider's extended metadata which maps attributes in the SAMLv2 assertion to attributes in the local user data store. (If an attribute map is not configured, no attributes will be returned.)

OpenSSO Enterprise contains two custom mappers:

com.sun.identity.saml2.plugins.DefaultAttributeAuthorityMapper

com.sun.identity.saml2.plugins.DefaultAttributeAuthorityMapper maps using the NameID from a single sign-on interaction. To set OpenSSO Enterprise to use a different attribute mapper implementation, modify the value of the default_attributeAuthorityMapper property in the extended metadata of the provider defined as the attribute authority. The mapper value of default_attributeAuthorityMapper is used for a standard attribute queries

com.sun.identity.saml2.plugins.X509SubjectAttributeAuthorityMapper

com.sun.identity.saml2.plugins.X509SubjectAttributeAuthorityMapper maps using the value of the X.509 Subject in the certificate in the NameID. To set OpenSSO Enterprise to use a different attribute mapper implementation, modify the value of the x509Subject_attributeAuthorityMapper property in the extended metadata of the provider defined as the attribute authority. The mapper value of x509Subject_attributeAuthorityMapper is used for attribute queries with an X509 certificate. The X509 mapper maps an X509 subject to a user by searching the identity data store for the attribute defined as the value of the x509SubjectDataStoreAttrName property in the identity provider extended metadata of the attribute authority. If the user has the specified attribute and the attribute's value is the same as that of the X509 subject in the attribute query, the user will be used.

Only SOAP binding is supported for these communications. Signing is required so make sure the Signing Certificate Alias attribute of any provider acting as the attribute requester and the attribute authority is configured. The ssoadm command line interface can be used to create and import the service provider metadata. The following tags must be in the standard metadata of the service provider (querying provider).

<RoleDescriptor
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
  xsi:type="query:AttributeQueryDescriptorType"
  protocolSupportEnumeration=
  "urn:oasis:names:tc:SAML:2.0:protocol">
</RoleDescriptor>

The following tags must be in the extended metadata of the service provider (querying provider).

<AttributeQueryConfig metaAlias="/attrq">
  <Attribute name="signingCertAlias">
   <Value>test2</Value>
  </Attribute>
  <Attribute name="encryptionCertAlias">
    <Value>test2</Value>
  </Attribute>
</AttributeQueryConfig>

Use the following options to create the appropriate tags in the service provider's metadata. See Part I, Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference for more information.

--attrqueryprovider, -S

Specify a metaAlias for the hosted querying provider. The format must be realm name/identifier.

--attrqscertalias, -A

Specify a signing certificate alias.

--attrqecertalias, -R

Specify an encryption certificate alias.

The ssoadm command line interface can also be used to create and import the identity provider metadata. The following tags must be in the standard metadata of the identity provider (attribute authority).

<AttributeAuthorityDescriptor
  protocolSupportEnumeration=
  "urn:oasis:names:tc:SAML:2.0:protocol">
</AttributeAuthorityDescriptor>

The following tags must be in the extended metadata of the identity provider (attribute authority). Note the presence of the x509SubjectDataStoreAttrName attribute.

<AttributeAuthorityConfig metaAlias="/attra">
  <Attribute name="signingCertAlias">
   <Value>test2</Value>
  </Attribute>
  <Attribute name="encryptionCertAlias">
   <Value>test2</Value>
  </Attribute>
  <Attribute name="default_attributeAuthorityMapper">
   <Value>com.sun.identity.saml2.plugins.DefaultAttributeAuthorityMapper</Value>
  </Attribute>
  <Attribute name="x509Subject_attributeAuthorityMapper">
   <Value>com.sun.identity.saml2.plugins.X509SubjectAttributeAuthorityMapper</Value>
  </Attribute>
  <Attribute name="x509SubjectDataStoreAttrName">
   <Value></Value>
  </Attribute>
</AttributeAuthorityConfig>

Use the following options to create the appropriate tags in the identity provider's metadata. See Part I, Command Line Interface Reference, in Sun OpenSSO Enterprise 8.0 Administration Reference for more information.

--attrauthority, -I

Specify a metaAlias for the hosted attribute authority. The format must be realm name/identifier.

--attrascertalias, -B

Specify a signing certificate alias.

--attraecertalias, -G

Specify an encryption certificate alias.

To initiate this query, create and import the standard and extended metadata for both the service provider and identity provider. Add the mapped values to the attributeMap property in the extended identity provider metadata in the following format:

attribute in SAML assertion=local attribute

Tip –

You can specify the attributes to be returned in the Attribute tag of the AttributeAuthorityDescriptor element of the identity provider standard metadata. If this attribute has no value, all requested attributes will be returned.


To send an attribute query from the provider use the method of com.sun.identity.saml2.profile.AttributeQueryUtil.

public static Response sendAttributeQuery(
  AttributeQuery attrQuery,
  String attrAuthorityEntityID, 
  String realm, 
  String attrQueryProfile,
  String attrProfile, String binding) throws SAML2Exception;

To construct an AttributeQuery object, use the com.sun.identity.saml2.assertion.* and com.sun.identity.saml2.protocol.* packages.

Requesting a SAMLv2 Assertion

The Assertion Query/Request profile specifies a means for requesting existing assertions using a unique identifier. The requester initiates the profile by sending an assertion request, referenced by the identifier, to a SAMLv2 authority. The SAMLv2 authority processes the request, checks the assertion cache for the identifier, and issues a response to the requester.


Note –

To store assertions generated during single sign-on, add the following attribute to the metadata file of the identity provider acting as the SAMLv2 authority.

<IDPSSOConfig metaAlias="/idp">
<Attribute name="assertionCacheEnabled">
<Value>true</Value>
</Attribute>
</IDPSSOConfig>

To configure for assertion queries, the following tags must be defined in the identity provider standard metadata.

<IDPSSODescriptor WantAuthnRequestsSigned=
"false" protocolSupportEnumeration="urn:oasis:names:tc:
SAML:2.0:protocol">

  <AssertionIDRequestService Binding="urn:oasis:names:tc:
   SAML:2.0: bindings:SOAP" Location=
   "http://isdev-3.red.iplanet.com:58080/
   fam/AIDReqSoap/IDPRole/metaAlias/idp"/>
    <AssertionIDRequestService Binding=
     "urn:oasis:names:tc:SAML:
     2.0:bindings:URI" Location=
     "http://isdev-3.red.iplanet.com:
     58080/fam/AIDReqUri/IDPRole/metaAlias/idp"/>
</IDPSSODescriptor>

<AttributeAuthorityDescriptor protocolSupportEnumeration=
"urn:oasis:names:tc:SAML:2.0:protocol">
  <AssertionIDRequestService Binding=
   "urn:oasis:names:tc:SAML:
   2.0:bindings:SOAP" Location=
   "http://isdev-3.red.iplanet.com:
   58080/fam/AIDReqSoap/AttrAuthRole/metaAlias/attra"/>
    <AssertionIDRequestService Binding=
     "urn:oasis:names:tc:SAML:
     2.0:bindings:URI" Location=
     "http://isdev-3.red.iplanet.com:
     58080/fam/AIDReqUri/AttrAuthRole/
     metaAlias/attra"/>
</AttributeAuthorityDescriptor>

<AuthnAuthorityDescriptor protocolSupportEnumeration=
"urn:oasis:names:tc:SAML:2.0:protocol">
..<AssertionIDRequestService Binding="urn:oasis:names:tc:SAML:
   2.0:bindings:SOAP" Location="http://isdev-3.red.iplanet.com:
   58080/fam/AIDReqSoap/AuthnAuthRole/metaAlias/authna"/>
  <AssertionIDRequestService Binding="urn:oasis:names:tc:SAML:
   2.0:bindings:URI" Location="http://isdev-3.red.iplanet.com:
   58080/fam/AIDReqUri/AuthnAuthRole/metaAlias/authna"/>
..</AuthnAuthorityDescriptor>

The following tags must be defined in the identity provider extended metadata.

<IDPSSOConfig metaAlias="/idp">
..<Attribute name="assertionIDRequestMapper">
   <Value>com.sun.identity.saml2.plugins.
    DefaultAssertionIDRequestMapper</Value>
   </Attribute>
</IDPSSOConfig>

<AttributeAuthorityConfig metaAlias="/attra">
..<Attribute name="assertionIDRequestMapper">
   <Value>com.sun.identity.saml2.plugins.
    DefaultAssertionIDRequestMapper</Value>
  </Attribute>
</AttributeAuthorityConfig>

<AuthnAuthorityConfig metaAlias="/authna">
..<Attribute name="assertionIDRequestMapper">
   <Value>com.sun.identity.saml2.plugins.
    DefaultAssertionIDRequestMapper</Value>
  </Attribute>
</AuthnAuthorityConfig> 

com.sun.identity.saml2.plugins.DefaultAssertionIDRequestMapper is the default implementation used to process the assertion request. (See com.sun.identity.saml2.plugins.AssertionIDRequestMapper in the Sun OpenSSO Enterprise 8.0 Java API Reference.) To define a customized mapper, change the value of the assertionIDRequestMapper property in the IDP, attribute authority or authentication authority extended metadata.

Supported bindings are SOAP and URI however in order to implement URI binding, you must do the following.

  1. Write an implementation of com.sun.identity.saml2.plugins.AssertionIDRequestMapper.

    The method authenticateRequesterURI() should be returned without throwing an exception.

  2. Modify the value of the assertionIDRequestMapper element in the identity provider metadata to match the name of the custom implementation.

Requesting a SAMLv2 Assertion for Authentication Context

A SAMLv2 assertion contains information regarding the context of a principal's authentication. The requesting party may require this additional information (for example, the authenticating technology or protocol used) in order to assess the level of confidence they can place in the assertion. To retrieve authentication context information, the service provider issues a query to the authentication authority. Only SOAP binding is supported for this request And signing is required so make sure the Signing Certificate Alias attribute of the service provider and the authentication authority is configured.

ProcedureTo Configure for Authentication Context Queries

  1. Create and load the metadata for the service provider.

  2. Create the metadata for the identity provider using ssoadm and define these additional options for it's role as an authentication authority.

    -C

    Defines the meta Alias for the hosted authentication authority to be created. The format must be realm name/identifier.

    -D

    Defines the authentication authority signing certificate alias.

    -E

    Defines the authentication authority encryption certificate alias.

    For example:

    ssoadm create-metadata-templ -u amadmin -f /tmp/pw -m /home/user1/tmp/mm -x
    /home/usr1/tmp/xx -s /idp -a test -r test -C /authna -D test2 -E test2 -y
    example.com
  3. Add the following attribute to the identity provider metadata file just created.

    This allows the identity provider to store assertions generated during the SAMLv2 Single Sign-on process.

    <IDPSSOConfig metaAlias="/idp">
    <Attribute name="assertionCacheEnabled">
    <Value>true</Value>
    </Attribute>
    </IDPSSOConfig>
  4. Configure for SAMLv2 single sign-on as documented in Configuring SAMLv2 Single Sign-on without Service Provider User Accounts.

  5. Do either of the following:

    • To send an authentication query from the service provider use the method of com.sun.identity.saml2.profile.AuthnQueryUtil.

      public static Response sendAuthnQuery(AuthnQuery authnQuery,
        String authnAuthorityEntityID, String realm, String binding)
        throws SAML2Exception;
    • To construct an AuthnQuery object, use com.sun.identity.saml2.assertion.* and com.sun.identity.saml2.protocol.*.

Encoding Artifacts

When an identity provider sends a response to a service provider using artifact binding, OpenSSO Enterprise supports either URI or form encoding. To specify the encoding, toggle the value of the responseArtifactMessageEncoding tag in the service provider's extended metadata. Possible values are URI and FORM as in:

<Attribute name="responseArtifactMessageEncoding">
  <Value>FORM</Value>
</Attribute>

Managing SAMLv2 Name Identifiers

With this release, OpenSSO Enterprise enhances its implementation of the Name Identifier Management Profile to include the termination of the association of a name identifier between a service provider and an identity provider (including the accompanying federation) and the issuance of a new name identifier. When metadata is created using OpenSSO Enterprise, XML is defined to support HTTP-Redirect, SOAP and HTTP-POST bindings. Following is the code for an identity provider.

<IDPSSODescriptor
  <ManageNameIDService
   Binding="urn:oasis:names:tc:SAML:2.0:bindings:
   HTTP-Redirect" Location="http://isdev-3.red.iplanet.com:
   58080/fam/IDPMniRedirect/metaAlias/idp" ResponseLocation=
   "http://isdev-3.red.iplanet.com:58080/fam/IDPMniRedirect/
   metaAlias/idp"/>
  <ManageNameIDService
   Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   Location="http://isdev-3.red.iplanet.com:58080/fam/
   IDPMniPOST/metaAlias/idp" ResponseLocation=
   "http://isdev-3.red.iplanet.com:58080/fam/IDPMniPOST/
   metaAlias/idp"/>
  <ManageNameIDService
   Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
   Location="http://isdev-3.red.iplanet.com:58080/fam/
   IDPMniSoap/metaAlias/idp"/>
</IDPSSODescriptor> 

The ManageNameID (MNI) JSP provide a way to initiate name identifier changes or terminations. For example, after establishing a name identifier for use when referring to a principal, the identity provider may want to change its value and/or format. Additionally, an identity provider might want to indicate that a name identifier will no longer be used to refer to the principal. The identity provider will notify service providers of the change by sending them a ManageNameIDRequest. A service provider also uses this message type to register or change the SPProvidedID value (included when the underlying name identifier is used to communicate with it) or to terminate the use of a name identifier between itself and the identity provider. To initiate termination of a name identifier or creation of a new identifier, access the appropriate JSP using the URL and URL parameter information in the following sections.

The JSP are located in /OpenSSO-Deploy-base/opensso/saml2/jsp/. idpMNIRedirect.jsp, spMNIRedirect.jsp, idpMNIPOST.jsp, and spMNIPOST.jsp, also in that directory, are process pages served as endpoints.

idpMNIRequestInit.jsp

idpMNIRequestInit.jsp initiates name identifier modifications or termination from the identity provider. The URL for this JSP is protocol://host:port/service-deploy-uri/saml2/jsp/idpMNIRequestInit.jsp. The following URL parameters are appended to it.

An example URL for using HTTP-POST communication might be:

http://dev-3.sun.com:58080/opensso/saml2/
  jsp/idpMNIRequestInit.jsp?metaAlias=/idp&spEntityID=
  mach1.sun.com&requestType=Terminate&binding=
  urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

spMNIRequestInit.jsp

spMNIRequestInit.jsp initiates name identifier modifications or termination from the service provider. The URL for this JSP is protocol://host:port/service-deploy-uri/saml2/jsp/spMNIRequestInit.jsp. The following URL parameters are appended to it.

An example URL for using SOAP communication might be:

http://dev-3.sun.com:58080/opensso/saml2/
  jsp/idpMNIRequestInit.jsp?metaAlias=/sp&idpEntityID=
  mach1.sun.com&requestType=NewID&binding=
  urn:oasis:names:tc:SAML:2.0:bindings:SOAP

Mapping SAMLv2 Name Identifiers

The NameID Mapping Protocol allows a service provider that shares an identifier for a principal with an identity provider to obtain a name identifier for said principal in another format or that is in another federation namespace (for example, is shared between the identity provider and another service provider). The requester initiates the profile by sending a NameIDMappingRequest message to the identity provider. After processing the request, the identity provider issues a NameIdMappingResponse message to the requester.

Only SOAP binding is supported. Signing is required so make sure the Signing Certificate Alias attribute of the identity provider and the service provider is configured.

To send a NameIDMappingRequest message from the service provider, use the method of the com.sun.identity.saml2.profile.NameIDMapping.

public static NameIDMappingResponse initiateNameIDMappingRequest(
  Object session,
  String realm, 
  String spEntityID, 
  String idpEntityID,
  String targetSPEntityID, 
  String targetNameIDFormat,
  Map paramsMap) throws SAML2Exception;

Enhanced Client and Proxy

The Enhanced Client and Proxy (ECP) profile assumes the client can contact an appropriate provider using the reverse SOAP (PAOS) binding. The ECP process flow is as follows:

  1. The principal, through the ECP, makes an HTTP request for a secured resource at a service provider, which does not have an established security context for the ECP or principal.

  2. The service provider issues an authentication request to the ECP using PAOS binding.

  3. The ECP obtains the location of an endpoint at an identity provider for the authentication request protocol that supports its binding.

  4. The ECP conveys the authentication request to the identity provider.

  5. The identity provider identifies the principal.

  6. The identity provider issues a response to the ECP that is to be delivered to the service provider.

  7. The ECP conveys a response message to the service provider.

  8. The service provider grants or denies access to the principal.

See the following procedures for configuration information.

After completing the configuration, use the following URL format to access a resource on the service provider.

SP protocol://SP host:SP port/SP deploy URI/SPECP?metaAlias=sp metaAlias&RelayState=resource url

ProcedureTo Configure for ECP on the Identity Provider Side

  1. Click the Federation tab and select the hosted SAMLv2 identity provider you wish to edit.

  2. Click on the IDP tab.

  3. Click the Advanced tab.

  4. Edit the IDP Session Mapper attribute for you deployment.

    The session mapper SPI com.sun.identity.saml2.plugins.IDPECPSessionMapper finds a valid session from the HTTP servlet request on the identity provider side with the ECP profile. The default implementation will construct a session object from the OpenSSO Enterprise server cookie. To construct a session from other cookies or HTTP headers, you need to implement this SPI and set your implementation here.

  5. Click Save.

ProcedureTo Configure for ECP on the Service Provider Side (Optional)

  1. Click the Federation tab and select the hosted SAMLv2 identity provider you wish to edit.

  2. Click on the SP tab.

  3. Click the Advanced tab.

  4. Click ECP Configuration.

  5. Edit Request IDP List Finder Implementation the IDP Finder SPI.

    com.sun.identity.saml2.plugins.SAML2IDPFinder finds a list of preferred identity providers. You can write your own implementation of this interface and set it here. The default implementation will read Request IDP List attribute. Request IDP List Get Complete Specifies an URI reference that can be used to retrieve the complete IDP list if the IDPList element is not complete. Request IDP List Defines a list of IDPs for the ECP to contact. This is used by the default implementation of the IDP Finder.

  6. Click Save.

Formatting Name Identifiers

Name identifiers are used by the identity provider and the service provider to communicate with each other regarding a principal. As of this release, OpenSSO Enterprise supports the following name identifier formats.

OpenSSO Enterprise defines these name identifiers in the identity provider's standard metadata. If no specific name identifier format is requested by the service provider, a default format must be used in the authentication response. To enable one or more of the supported formats you must add a name identifier format/user attribute map to the identity provider extended metadata to generate the name identifier based on the specified user profile attribute. The value is formatted as name ID format=user profile attribute as in the following XML sample

<Attribute name="nameIDFormatMap">
  <Value>urn:oasis:names:tc:SAML:1.1:nameid-format:
   emailAddress=mail</Value>
  <Value>urn:oasis:names:tc:SAML:1.1:nameid-format:
   X509SubjectName=</Value>
  <Value>urn:oasis:names:tc:SAML:1.1:nameid-format:
   WindowsDomainQualifiedName=</Value>
  <Value>urn:oasis:names:tc:SAML:2.0:nameid-format:
   kerberos=</Value>
</Attribute>

If a user profile attribute is specified, the name ID value will be the value of the user profile attribute. If no user profile attribute is specified an exception will be thrown. If the name ID format is persistent or transient, a random string will be generated. For more information on persistent and transient identifiers, see Configuring SAMLv2 Single Sign-on without Service Provider User Accounts.


Note –

To disable one or more name ID formats, the format XML tags can be removed from the identity provider's standard metadata.


Configuring SAMLv2 Single Sign-on without Service Provider User Accounts

Name identifiers are used by the identity provider and the service provider to communicate with each other regarding a user. Single sign-on interactions can support both persistent and transient identifiers. A persistent identifier is saved to a particular user entry as the value of two attributes. A transient identifier is temporary and no data will be written to the user's data store entry. OpenSSO Enterprise supports persistent identifiers by default and transient identifiers with configuration. NameID formats other than persistent and transient are supported by mapping the NameID format to a user profile attribute.

In some deployments, there might be no user account on the service provider side of an interaction. In this case, single sign-on with the transient name identifier is used. All users passed from the identity provider to the service provider will be mapped to this one user account. All attributes defined in the AttributeStatement will be set as properties of the specific user's single sign-on token. The following procedures describe some interactions using the transient name identifier.

ProcedureTo Use the Transient Name Identifier

  1. Append the NameIDFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:transient query parameter to the URL that initiates a single sign-on JavaServer Page™ (JSP™).

    spSSOInit.jsp and idpSSOInit.jsp both initiate single sign-on interactions.

  2. To test, invoke the URL.

    For more information, see Sun OpenSSO Enterprise 8.0 Developer’s Guide.

ProcedureTo Federate Disparate Accounts with Auto Federation

The auto-federation feature in OpenSSO Enterprise will automatically federate a user's disparate provider accounts based on a common attribute. This common attribute will be exchanged in a single sign-on assertion so that the consuming service provider can identify the user and create account federations. If auto-federation is enabled and it is deemed that a user at provider A and a user at provider B have the same value for the defined common attribute (for example, emailaddress), the two accounts will be federated automatically without principal interaction.


Note –

Auto-federating a principal's two distinct accounts at two different providers requires each provider to have agreed to implement support for this functionality beforehand.


Ensure that each local service and identity provider participating in auto federation is configured for it. Remote providers would not be configured in your deployment.

  1. In the OpenSSO Enterprise Console, click the Federation tab.

  2. Select the name of the hosted identity provider to edit its profile.

  3. Click the Assertion Processing tab.

  4. In the Attribute Map attribute, add the autofedAttribute=local-attribute value. For example, employeeNumber=employeeID.

  5. Click Save.

  6. Go back to the Federation tab and select the name of the hosted service provider to edit its profile.

  7. If the Auto Federation Common Attribute Name is the same as local attribute name, skip to next step. If not, enter the autofedAttribute=local-attribute value in the New Value field under Attribute Map. For example:

    employeeNumber=employeeID

  8. Click on the Auto Federation link at the top of the page, or scroll down to the Auto Federation subsection.

  9. Enable Auto Federation by checking the box.

  10. Click Save to complete the configuration.

ProcedureTo Map Attributes to anonymous User Account

In some deployments, the service provider side of an interaction might not store user accounts. The single sign-on solution is for all identity provider user accounts to be mapped to one service provider user account. Any attributes inside the Attribute Statement will be set as properties of the single sign-on token. The following procedure maps an identity provider user to a service provider anonymous user and passes two attributes to the service provider.

  1. In the console, select the identity provider you wish to configure.

  2. Edit Attribute Map attribute.

    attribute Map defines the mapping between the provider that this metadata is configuring and the remote provider. This attribute takes a value of autofedAttribute-value=remote-provider-attribute. For example:

    mail=mail
    employeeNumber=employeeNumber
  3. From the console, select the service provider you wish to configure.

  4. Edit the following attributes for the service provider.

    • transient User will take a value of one of the existing transient user identifiers on the service provider side, for example, anonymous.

    • attribut eMap defines the mapping between the provider that this metadata is configuring and the remote provider. This attribute takes a value of autofedAttribute_value=remote_provider_attribute. For example:

      >mail=mail
      employeeNumber=employeeNumber
  5. To test, invoke the single sign-on URL with the NameIDFormat=transient query parameter appended to it.

    All identity provider users will be mapped to anonymous on the service provider side. mail and employeeNumber will be set as properties in the identity provider user's single sign-on token.

ProcedureTo Achieve Single Sign-on Without Data Store Writes

This interaction uses auto-federation with the transient name identifier. There is one-to-one mapping between user accounts configured with the identity provider and the service provider based on the value of one attribute. The following procedure describes how to configure single sign-on without writing to the user's data store entry.

  1. Edit the following attributes in the OpenSSO Enterprise console for the identity provider.

    • Auto Federation – enable this attribute.

    • Auto Federation Attribute defines the common attribute on the identity provider side. For example, mail.

    • Attribute Map defines the mapping between the identity provider's attribute and the remote provider's attribute. It takes a value of autofedAttribute-value=remote-provider-attribute. For example:

      <Attribute name="attributeMap">
      <Value>mail=mail</Value>
      </Attribute>
  2. Edit the following attributes in the OpenSSO Enterprise console for the service provider.

    • Transient User takes a null value.

    • Auto Federation enable this attribute.

    • Auto Federation Attribute defines the common attribute. For example, mail.

    • Attribute Map defines the mapping between the provider that this metadata is configuring and the remote provider. This attribute takes a value of autofedAttribute-value=remote-provider-attribute. For example:

      mail=mail
  3. Invoke the single sign-on URL with the NameIDFormat=transient query parameter appended to it to test.

    All identity provider users will be mapped to the corresponding user on the service provider side based on the mail attribute but the auto-federation attributes will not be written to the user entry.

Auto-creation of User Accounts

Auto-creation of user accounts can be enabled on the service provider side. An account would be created when there is none corresponding to the identity provider user account requesting access. This might be necessary, for example, when a new service provider has joined an existing circle of trust.


Note –

Auto-creation is supported only when the service provider is running on an instance of OpenSSO Enterprise as it extends that product's Dynamic Profile Creation functionality.


ProcedureTo Enable Auto-creation

Before You Begin

You must configure the attribute mapper on the identity provider side to include an AttributeStatement from the user. The account mapper on the service provider side will perform user mapping based on the AttributeStatement.

  1. Enable auto Federation for the Identity Provider. For more information, see To Federate Disparate Accounts with Auto Federation.

  2. Click Save.

  3. Repeat the above steps to modify the service provider's extended metadata.

  4. Enable Dynamic Profile Creation using the OpenSSO Enterprise console.

    1. Log in to the OpenSSO Enterprise console as the top-level administrator, by default, amadmin.

    2. Under the Access Control tab, select the appropriate realm.

    3. Select the Authentication tab.

    4. Select Advanced Properties.

    5. Set User Profile to Dynamic or Dynamic with User Alias and click Save.

    6. Log out of OpenSSO Enterprise.

  5. To test, invoke single sign-on from the service provider.

Using Non-Default Federation Attributes

If OpenSSO Enterprise is retrieving data from an LDAPv3–compliant directory, the object class sunFMSAML2NameIdentifier (containing two allowed attributes, sunfm- saml2-nameid-info and sun-fm-saml2-nameid-infokey) needs to be loaded into the entries of all existing users. When the directory contains a large user database the process is time-intensive. The following procedure can be used to modify your SAML v2 Plug-in for Federation Services installation to use existing LDAP attributes to store user federation information. In this case, there is no need to change the schema.

ProcedureTo Store Federation Information in Existing Attributes

  1. In the OpenSSO Enterprise console, go to Configuration>Global>SAMLv2 Service Configuration.

  2. Modify the following attributes:

    • Attribute name for Name ID information

    • Attribute name for Name ID information key

    See SAMLv2 Service Configuration in Sun OpenSSO Enterprise 8.0 Administration Reference for more information.

  3. Restart the web container.

    Federation information will now be written to the specified attributes.

Enabling XML Signing and Encryption

XML signing and encryption is most easily configured through the OpenSSO Enterprise console. To enable request/response signing and encryption, click on the name of the entity provider you wish to edit in the Federation tab. For both service and identity providers, the signing attributes are located under the Assertion Content sub tab.

For definitions for service provider attributes, see SAMLv2 Service Provider Customization in Sun OpenSSO Enterprise 8.0 Administration Reference.

For definitions of identity provider attributes, see SAMLv2 Identity Provider Customization in Sun OpenSSO Enterprise 8.0 Administration Reference.

Securing SOAP Binding

SOAP binding supports the following authentication methods to protect interactions between SAML v2 entities:

Basic Authentication

Once basic authentication is set up to protect a SAML v2 SOAP endpoint, all entities communicating with this endpoint must configure three basic authentication-related attributes in the extended metadata as described in the following table. These attributes are located in the Assertion Content tab of the SAMLv2 entity provider profile.

Table 8–2 Securing SOAP Endpoint with Basic Authentication

Attribute 

Description 

Basic Authenticaion Enabled

Establishes that the SOAP endpoint is using basic authentication. Takes a value of true or false.

User Name

Defines the user allowed access to the protected SOAP endpoint in the original SAML v2 entity. 

Password

Defines an encrypted password for the user. The password is encrypted using ampassword on the partner side. .

Secure Socket Layer/Transport Layer Security

Secure Socket Layer/Transport Layer Security (SSL/TLS) can also be enabled to protect SOAP endpoints and secure communications between SAML v2 entities. When one SAML v2 entity initiates communication with a SAML v2 entity deployed in an SSL/TLS-enabled web container, the initiating entity is referred to as the SSL/TLS client and the replying entity is referred to as the SSL/TLS server.

Server Certificate Authentication

For SSL/TLS server authentication (the server needs to present a certificate to the client), the following properties need to be set in the Virtual Machine for the Java™ platform (JVM™) running the SSL/TLS client:

-Djavax.net.ssl.trustStore

Defines the full path to the file containing the server's CA certificates. 

-Djavax.net.ssl.trustStoreType

Takes a value of JKS (Java Key Store).

In addition, the client's CA certificate needs to be imported into the certificate store/database of the server's web container and marked as a trusted issuer of client certificates.

Client Certificate Authentication

For SSL/TLS client authentication (the client needs to present a certificate to the server), the following properties need to be set in the JVM software running the SSL/TLS client:

-Djavax.net.ssl.keyStore

Defines the full path to the keystore containing the client certificate and private key. This may be the same as that defined in Server Certificate Authenticaion.. 

-Djavax.net.ssl.keyStoreType

Takes a value of JKS.

-Djavax.net.ssl.keyStorePassword

Specifies the password to the keystore. 

On the SSL/TLS server side, the client's CA certificate needs to be imported into the web container's keystore and marked as a trusted issuer of client certificates.

Load Balancing

In cases of large deployments, a load balancer can be put in front of multiple instances of OpenSSO Enterprise that have the SAML v2 Plug-in for Federation Services installed. The following procedure describes how to enable load balancer support.

ProcedureTo Enable Load Balancer Support

  1. Install OpenSSO Enterprise and follow the documentation to set up a load balancer.

    Load balancing information for OpenSSO Enterprise can be found in Configuring the Directory Server Load Balancer in Deployment Example: SAML v2 Using Sun OpenSSO Enterprise 8.0.

  2. Create an identity provider or a service provider through the OpenSSO Enterprise Console or with the ssoadm CLI.

  3. On any service provider machines, copy the metadata configuration files into the same directory and rename as follows:

    • spMeta.xml to spMeta.xml.lb

    • spExtended.xml to spExtended.xml.lb

  4. Edit the new service provider load balancer metadata configuration files as follows:

    • Change the host name of the service provider to that of the load balancer on the service provider side.

    • Change the protocol on the service provider side.

    • Change the port of the service provider to that of the load balancer on the service provider side.

    • Change the metaAlias of the service provider to any new metaAlias, for example, /splb.

  5. On any identity provider machines, copy the metadata configuration files into the same directory and rename as follows:

    • idpMeta.xml to idpMeta.xml.lb

    • idpExtended.xml to idpExtended.xml.lb

  6. Edit the new identity provider load balancer metadata configuration files as follows:

    • Change the host name of the identity provider to that of the load balancer on the identity provider side.

    • Change the protocol on the identity provider side.

    • Change the port of the identity provider to that of the load balancer on the identity provider side.

    • Change the metaAlias of the identity provider to any new metaAlias, for example, /idplb.

  7. Import the new hosted metadata onto the service provider machines.

  8. Import the new remote identity provider metadata onto the service provider machines.

  9. Import the new hosted metadata onto the identity provider machines.

  10. Import the new remote service provider metadata onto the identity provider machines.

  11. Restart the web containers.

Access Control

The following procedure will allow user access on the service provider side based on the user's configured roles on the identity provider side. This information is passed to the service provider in an assertion. No matching user entry is necessary on the service provider side.

ProcedureTo Enable Access Control Using Agents

  1. Create a SAMLv2 identity provider. For more information, see To Create a SAMLv2 Entity Provider.

  2. Create a SAMLv2 service provider.

  3. Install the Sun Policy Agents 3.0 to protect the service provider configured on the instance of OpenSSO Enterprise

    For more information, see the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents.

  4. In the OpenSSO Enterprise console, go to Access Control>Realms>Agents and select the web policy agent profile you wish to configure.

  5. Go to the OpenSSO Services sub tab and edit the OpenSSO Login URL attribute .

    Its value is a URL (appended with the NameIDFormat=transient query parameter) that points to a single sign-on JSP on the service provider side.


    SP-protocol://SP-host:SP-port/service-deploy-uri/
    saml2/jsp/spSSOInit.jsp?NameIDFormat=transient&metaAlias=SP-metaAlias&
    idpEntityID=IDP_EntityID
    

    For example:


    http://example1.com:58080/
    opensso/saml2/jsp/spSSOInit.jsp?NameIDFormat=transient&metaAlias=/sp&
    idpEntityID=sample.com
  6. (Required only if using Web Agent 2.1) Set the value of the com.sun.am.policy.am.library.loginURL property to the service provider's login URL so the agent can authenticate itself.

    If the login URL is a URL that initiates a SAML v2 single sign-on interaction, the value of this property will be used to authenticate the agent itself to your instances of OpenSSO Enterprise. An example value might be http://host:port/opensso/UI/Login.

  7. Modify spSSOInit.jsp on the service provider side to use goto parameter as the value for RelayState.

    The differences are as follows:


    ***************
    *** 143,148 ****
    --- 143,154 ----
    }
    idpEntityID = request.getParameter("idpEntityID");
    paramsMap = SAML2Utils.getParamsMap(request);
    + String gotoURL = (String) request.getParameter("goto");
    + if (gotoURL != null) {
    + List list = new ArrayList();
    + list.add(gotoURL);
    + paramsMap.put(SAML2Constants.RELAY_STATE, list);
    + }
    if ((idpEntityID == null) || (idpEntityID.length() == 0)) {
    // get reader url
  8. Set up single sign-on without requiring writes to the data store by following the procedure described in To Achieve Single Sign-on Without Data Store Writes.

    To test, assume the employeenumber attribute stores the user's role. In addition, the identity provider should have the following configured users:

    • User 1 has employeenumber set to manager (the manager's role).

    • User 2 has employeenumber set to employee (the employee's role).

  9. Create a policy with the Session Property condition on the service provider instance of OpenSSO Enterprise.

    1. Log in to the OpenSSO Enterprise console as the top-level administrator, by default, amadmin.

    2. Under the Access Control tab, select the appropriate realm.

    3. Select the Policies tab.

    4. Click New Policy.

    5. Enter a name for the policy.

    6. Click New under Rules.

    7. Select URL Policy Agent (with resource name) and click Next.

    8. Enter a name for the rule.

    9. Enter the application's URL as the value for Resource Name.

    10. Select Allow under both GET and POST and click Finish.

    11. Click New under Conditions.

    12. Select Session Property and click Next.

    13. Enter a name for the condition.

    14. Click Add under Values.

    15. Enter the single sign-on token property name as the value for Property Name.

      To test, use employeenumber.

    16. Add the match value to the Values field and click Add.

      To test, use manager.

    17. Click Add to return to the New Condition page.

    18. Click Finish to save the condition.

    19. Click Create to create the policy.

    For more information on creating policy, see Creating Policies and Referrals.

  10. Access the application using a web browser.

    You will be redirected to the service provider single sign-on JSP defined in the previous step. From there, you will be redirected to the identity provider to login. Single sign-on with the service provider will be accomplished using SAML v2 and, finally, you will be redirected back to the application for policy enforcement. If you logged in as User 1, you will be allowed to access the application as a manager which is allowed by the policy. If you logged in as User 2, an employee, you will be denied access to the application.

Certificate Revocation List Checking

The certificate revocation list (CRL) is a list of revoked certificates that contains the reasons for the certificate's revocation, the date of it's issuance, and the entity that issued it. When a potential user attempts to access the OpenSSO Enterprise server, first access is allowed or denied based on the CRL entry for the root certificate included with the request. When the SAML v2 Service receives the incoming XML request, it parses the issuer Distinguished Name (DN) from the root certificate and retrieves the value defined by the com.sun.identity.crl.cache.directory.searchattr attribute in the Advanced properties of the Sites and Server tab. For more information, see Advanced in Sun OpenSSO Enterprise 8.0 Administration Reference. If the attribute value is CN and the issuer DN is, for example, CN="Entrust.net Client Certification Authority", OU=..., the SAML v2 Service uses Entrust.net Client Certification Authority to retrieve the CRL from the LDAP directory which acts as the CRL repository.

With this action, one of the following will occur:

  1. If the LDAP directory returns a CRL that is not valid, the SAML v2 Service retrieves the value of the IssuingDistributionPointExtension attribute (usually an HTTP or LDAP URI) from the CRL and uses it to get new CRL from the certificate authority. If the certificate authority returns a valid CRL, it is saved to the LDAP directory and to memory and used for certificate validation.

  2. If the LDAP directory returns no CRL but the certificate that is being validated has a defined CRL Distribution Point Extension, the SAML v2 Service retrieves it's value (usually an HTTP or LDAP URI) and uses the value to get a new CRL from the certificate authority. If the certificate authority returns a valid CRL, it is saved to the LDAP directory and to memory and used for certificate validation.

  3. If the certificate authority returns a valid CRL, it is saved to the LDAP directory and to memory and used for certificate validation.


Note –

Currently, Certificate Revocation List Checking works only with an instance of Sun Directory Server.


After the CRL is loaded into memory and the root certificate validation is successful, the single sign-on process continues with validation of the signed XML message. The following are procedures to set up the SAML v2 Service for CRL checking.


Caution – Caution –

CRL checking currently only works in the case of XML-based signature validation; for example, service provider side POST Artifact profile, or SOAP based logout. CRL checking does not work in the case of URL string based signature validation, XML signing, XML encryption or decryption.


ProcedureTo Set Up for Certificate Revocation List Checking

Before You Begin

A local instance of Directory Server must be designated as the CRL repository. It can be the same directory in which the OpenSSO Enterprise schema is stored or it can be standalone. The Java Development Kit (JDK) must be version 1.5 or higher.

  1. Create one entry in Directory Server for each certificate authority.

    For example, if the certificate authority's subjectDN is CN="Entrust.net Client Certification Authority",OU="www.entrust.net/GCCA_CPS incorp. by ref. (limits lib.)",O=Entrust.net and the base DN for Directory Server is dc=sun,dc=com, create an entry with the DN cn="Entrust.net Client Certification Authority",ou=people,dc=sun,dc=com.


    Note –

    If the certificate authority's subjectDN does not contain uid or cn attributes, do the following:

    1. Create a new object class.

      For example, sun-am-managed-ca-container.

    2. Populate the new object class with the following attributes:

      • objectclass

      • ou

      • authorityRevocationList

      • caCertificate

      • certificateRevocationList

      • crossCertificatePair

    3. Add the following entry (modified per your deployment) to Directory Server.

      dn: ou=1CA-AC1,dc=sun,dc=com
      objectClass: top
      objectClass: organizationalunit
      objectClass: iplanet-am-managed-ca-container
      ou: 1CA-AC1

    You will publish the appropriate CRL to the entry created in the last step.


  2. Publish the appropriate CRL to the corresponding LDAP entry.

    This part can be done automatically by OpenSSO Enterprise or manually. If the certificate being validated has a CRL Distribution Point Extension value, the publishing of the CRL is done automatically. If the certificate being validated has an IssuingDistributionPointExtension value, the initial publishing of the CRL must be done manually but future updates are done in runtime. If the certificate being validated has neither of these values, updates must be done manually at all time. See To Manually Populate a Directory Server with a Certificate Revocation List for information on manual population.

  3. Configure OpenSSO Enterprise in the console to point to the instance of Directory Server designated as the CRL repository.

    1. In the OpenSSO Enterprise Console, click the Configuration tab.

    2. Click Servers and Sites tab.

    3. Click the Server Name.

    4. Click Security tab.

    5. Click Inheritance Settings.

    6. Uncheck the following properties:

      • LDAP Search Base DN

      • LDAP Server Bind Password

      • LDAP Server Bind Username

      • LDAP Server Host Name

      • LDAP server port number

      • Search Attributes

      • SSL Enabled

    7. Click Save and then Back to Server Profile.

    8. Click Certificate Revocation List Caching.

    9. Configure the following attributes. See Certificate Revocation List Caching in Sun OpenSSO Enterprise 8.0 Administration Reference for definitions of the properties:

      • LDAP Server Host Name

      • LDAP Server Port Number

      • SSL Enabled

      • LDAP Server Bind User Name

      • LDAP Server Bind Password

      • LDAP Search Base DN

      • Search Attributes

    10. Click Save.

    11. Restart the web container.

  4. Import all the certificate authority certificates into the cacerts keystore under the java.home/jre/lib/secure directory using the keytool utility.

    Certificates must be imported as trustedcacert. More information on keytool can be found at http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html.

ProcedureTo Manually Populate a Directory Server with a Certificate Revocation List

  1. Use your browser to get the initial CRL from the certificate authority manually.

  2. Save the initial CRL file in the binary DER format to your local machine.

  3. Convert the DER file to the text-based PEM format and finally LDAP Data Interchange Format (LDIF) using the following command:

    ldif -b certificaterevocationlist;binary crl.ldif


    Note –

    The ldif command is available in your Directory Server installation.


    The crl.ldif file contains text similar to the following:

    certificaterevocationlist;binary:: MIH7MIGmMA0GCSqGSIb3DQEBBQUAMGExCzAJBgNVBA
      YTAlVTMRgwFgYDVQQKEw9VLlMuIEdvdmVybm1lbnQxDDAKBgNVBAsTA0RvRDEMMAoGA1UECxMDUE
      tJMRwwGgYDVQQDExNEb0QgQ2xhc3MgMyBSb290IENBFw0wNzA1MDExNDMzMDNaFw0wNzA1MDExNz
      UzMDNaMBQwEgIBTxcNMDcwNDI3MTY1NzMzWjANBgkqhkiG9w0BAQUFAANBADUd7lBe7JeQKQnKCK
      GddnsCXqii7EitbPuYT55M4Nn3qBgPFSG8bX9H5XBGTB4iofb3h0Y9DCqe10vc8dBM0
  4. Do one of the following to define the LDAP entry in which the CRL will be stored.

    • For an existing entry, specify the DN in the LDIF file.

      # entry-id: famouseCA dn: CN=famouseCA,ou=People,dc=sun,dc=com 
      certificaterevocationlist;binary:: MIH7MIGmMA0GCSqGSIb3DQEBBQUAMGExCzAJBgNVBA
        YTAlVTMRgwFgYDVQQKEw9VLlMuIEdvdmVybm1lbnQxDDAKBgNVBAsTA0RvRDEMMAoGA1UECxMDUE
        tJMRwwGgYDVQQDExNEb0QgQ2xhc3MgMyBSb290IENBFw0wNzA1MDExNDMzMDNaFw0wNzA1MDExNz
        UzMDNaMBQwEgIBTxcNMDcwNDI3MTY1NzMzWjANBgkqhkiG9w0BAQUFAANBADUd7lBe7JeQKQnKCK
        GddnsCXqii7EitbPuYT55M4Nn3qBgPFSG8bX9H5XBGTB4iofb3h0Y9DCqe10vc8dBM0
    • For a new entry, specify the DN and object classes in the LDIF file.

      # entry-id: tester200
      dn: CN=famouseCA,ou=People,dc=sun,dc=com
      sn: famouseCA
      cn: famouseCA
      employeeNumber: 1001
      telephoneNumber: 555-555-5555
      postalAddress: 555 Test Drive
      iplanet-am-modifiable-by: cn=Top-level Admin Role,dc=iplanet,dc=com
      mail: famouseCA@test.com
      givenName: Test
      inetUserStatus: Active
      uid: tester200
      objectClass: iplanet-am-user-service
      objectClass: inetAdmin
      objectClass: iPlanetPreferences
      objectClass: inetOrgPerson
      objectClass: organizationalPerson
      objectClass: person
      objectClass: iplanet-am-managed-person
      objectClass: inetuser
      objectClass: top
      userPassword: {SSHA}E3TJ4DT7IoOLETVny1ktxUGWNTpBYq8tj3C1Sg==
      creatorsName: cn=puser,ou=dsame users,dc=iplanet,dc=com
      modifiersName: cn=puser,ou=dsame users,dc=iplanet,dc=com
      createTimestamp: 20031125043253Z
      modifyTimestamp: 20031125043253Z
      certificaterevocationlist;binary:: MIH7MIGmMA0GCSqGSIb3DQEBBQUAMGExCzAJBgNVBA
        YTAlVTMRgwFgYDVQQKEw9VLlMuIEdvdmVybm1lbnQxDDAKBgNVBAsTA0RvRDEMMAoGA1UECxMDUE
        tJMRwwGgYDVQQDExNEb0QgQ2xhc3MgMyBSb290IENBFw0wNzA1MDExNDMzMDNaFw0wNzA1MDExNz
        UzMDNaMBQwEgIBTxcNMDcwNDI3MTY1NzMzWjANBgkqhkiG9w0BAQUFAANBADUd7lBe7JeQKQnKCK
        GddnsCXqii7EitbPuYT55M4Nn3qBgPFSG8bX9H5XBGTB4iofb3h0Y9DCqe10vc8dBM0G8=
  5. Run one of the following ldapmodify commands based on whether you are adding the LDIF file to an existing entry or creating a new entry.

    • To add a CRL to an existing LDAP entry (using an LDIF file with a specified DN), use the following command:

      ldapmodify -r -h Directory Server_host -p Directory Server_port 
      -f ldif-file -D cn=Directory Manager -w password
      
    • To add a CRL to a new LDAP entry (using an LDIF file with a specified DN and object classes), use the following command:

      ldapmodify -a -h Directory Server_host -p Directory Server_port 
      -f ldif-file -D cn=Directory Manager -w password
      

ProcedureTo Enable Certificate Revocation List Checking for SAMLv2

  1. In the OpenSSO Enterprise Console, click the Configuration tab.

  2. Click the Global sub tab.

  3. Click SAMLv2 Service Configuration.

  4. Check the box for XML Signing Certificate Validation.

  5. Check the box for CA Certificate Validation. This step is optional.

  6. Click Save.

  7. Restart the web container.

SAMLv2 IDP Discovery Service

In deployments having more than one identity provider, service providers need to determine which identity provider 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.

The Reader and Writer URLs, used by the SAML v2 IDP Discovery Service, are defined when configuring the circle of trust. 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. The following section describes the procedure for setting up and testing the Identity Provider Discovery Service.

For steps to deploy the IDP Discovery Service, see Chapter 10, Deploying the Identity Provider (IDP) Discovery Service, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

Bootstrapping the Liberty ID-WSF with SAML v2

SAML v2 can be used to bootstrap into the Liberty Alliance Project Identity Web Services Framework (Liberty ID-WSF) version 1.1. For example, a service provider communicating with the SAML v2 specifications might want to communicate with web services based on the Liberty ID-WSF regarding a principal. To do this, the SAML v2 Assertion returned to the service provider must contain a Discovery Service endpoint. The service provider than acts as a web services consumer, using the value included within the Endpoint tag to bootstrap the Discovery Service. This then allows access to other Liberty ID-WSF services.

A sample SAMLv2 assertion is reproduced below. Note the SAML v2 security token stored in the Discovery Service resource offering: urn:liberty:security:2003-08:null:SAML. Both are stored within the attribute statement.

<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" 
ID="s21bdfd298f332ef2ada1d4fd00bab21c0f64cc90a" 
IssueInstant="2007-03-27T08:25:26Z">
<saml:Issuer>http://example.com</saml:Issuer>
<saml:Subject>
<saml:NameID NameQualifier="http://example.com" 
  SPNameQualifier="http://isdev-2.red.iplanet.com" Format=
  "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
  HuCJIy9v5MdrjJQOgsuT4NWmVUl3</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2007-03-27T08:35:26Z" 
  InResponseTo="s20711ed113989a9bff544f61c700d0bd0a08b78fd" 
  Recipient="http://isdev-2.red.iplanet.com:58080/
  opensso/Consumer/metaAlias/sp"  >
  </saml:SubjectConfirmationData>
  </saml:SubjectConfirmation>
  </saml:Subject>
<saml:Conditions NotBefore="2007-03-27T08:25:26Z" 
  NotOnOrAfter="2007-03-27T08:35:26Z">
<saml:AudienceRestriction>
<saml:Audience>http://isdev-2.red.iplanet.com</saml:Audience>
  </saml:AudienceRestriction>
  </saml:Conditions>
<saml:AuthnStatement AuthnInstant="2007-03-27T08:19:24Z" 
  SessionIndex="s234f01958bf364aff26829d9d9846ba51afc2b201">
  <saml:AuthnContext>
  <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:
  2.0:ac:classes:PasswordProtectedTransport
  </saml:AuthnContextClassRef>
  </saml:AuthnContext>
  </saml:AuthnStatement>
<saml:AttributeStatement>
<saml:Attribute Name="offerings" NameFormat="urn:liberty:disco:2003-08">
<saml:AttributeValue xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
<ResourceOffering xmlns="urn:liberty:disco:2003-08">
<ResourceID xmlns="urn:liberty:disco:2003-08">http://example.iplanet.com
  /aWQ9aWRwLG91PXVzZXIsZGM9aXBsYW5ldCxkYz1jb20sYW1zZGtkbj11aWQ9aWRwLG91PXBlb3BsZ
  SxkYz1pcGxhbmV0LGRjPWNvbQ%3D%3D</ResourceID>
<ServiceInstance xmlns="urn:liberty:disco:2003-08">
<ServiceType>urn:liberty:disco:2003-08</ServiceType>
<ProviderID>http://mach1.red.com</ProviderID>
<Description xmlns="urn:liberty:disco:2003-08" 
  id="sf6a6d3dcc16e729eea0d7e5587a5ff27f234f991">
<SecurityMechID>urn:liberty:security:2003-08:null:SAML
  </SecurityMechID>
<CredentialRef>s5dc88819de075e4e9c8db3deb8b46d4d8758b4b901
  </CredentialRef>
<Endpoint>http://mach1.red.com:58080/opensso/Liberty/disco
  </Endpoint></Description>
  </ServiceInstance></ResourceOffering></saml:AttributeValue></saml:Attribute>
<saml:Attribute Name="credentials" NameFormat="urn:liberty:disco:2003-08">
<saml:AttributeValue xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
<saml:Assertion  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" 
  MajorVersion="1" MinorVersion="1" 
  AssertionID="s5dc88819de075e4e9c8db3deb8b46d4d8758b4b901" Issuer=
  "http://mach1.red.com" IssueInstant="2007-03-27T08:25:26Z" >
<sec:ResourceAccessStatement xmlns:sec="urn:liberty:sec:2003-08">
<saml:Subject xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
<saml:NameIdentifier NameQualifier="http://isdev-2.red.com" 
  Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
  HuCJIy9v5MdrjJQOgsuT4NWmVUl3</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sendervouches
  </saml:ConfirmationMethod>
  </saml:SubjectConfirmation>
  </saml:Subject>
<ResourceID xmlns="urn:liberty:disco:2003-08">http://example.com/
aWQ9aWRwLG91PXVzZXIsZGM9aXBsYW5ldCxkYz1jb20sYW1zZG
tkbj11aWQ9aWRwLG91PXBlb3BsZSxkYz1pcGxhbmV
0LGRjPWNvbQ%3D%3D</ResourceID>
<sec:ProxySubject xmlns:sec="urn:liberty:sec:2003-08">
<saml:NameIdentifier xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" 
Format="urn:liberty:iff:nameid:entityID">http://isdev-2.red.com
  </saml:NameIdentifier>
<saml:SubjectConfirmation xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
  </saml:ConfirmationMethod>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"><KeyName>CN=sun-unix, OU=Sun 
  Access Manager, O=Sun, C=US</KeyName><KeyValue><RSAKeyValue><Modulus>AOA/2kpfKFWvRXOMbrmTlKe102ibw/
  aTd3HBVgI8cHsywww8M1J0X+vJvvk6eabTNWY5jBfTo9i1bC4AXXoRlxgsE/
  6Uq5+6NGrd+iwfvj25x8HzHX8LrJ+7EzlGVsKO
  M+A3vTP0tCkmYE4jatZbWlRoto0wyInP2wMFdKPrmYWL</Modulus>
<Exponent>AQAB</Exponent></RSAKeyValue>
  </KeyValue></KeyInfo></saml:SubjectConfirmation>
  </sec:ProxySubject><sec:SessionContext xmlns:sec="urn:liberty:sec:2003-08" AuthenticationInstant=
  "2007-03-27T08:25:26Z" AssertionIssueInstant="2007-03-27T08:25:26Z">
<sec:SessionSubject xmlns:sec="urn:liberty:sec:2003-08">
<saml:NameIdentifier xmlns:saml="urn:oasis:names:tc:SAML:1.0:
  assertion" NameQualifier="http://isdev-2.red.com" 
  Format="urn:oasis:names:tc:SAML:
  2.0:nameid-format:persistent">HuCJIy9v5MdrjJQOgsuT4NWmVUl3
  </saml:NameIdentifier>
<saml:SubjectConfirmation xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:2.0:cm:bearer</saml:ConfirmationMethod>
</saml:SubjectConfirmation>
<lib:IDPProvidedNameIdentifier  xmlns:lib="http://projectliberty.org/
  schemas/core/2002/12" 
  NameQualifier="http://example.com" Format="urn:oasis:names:tc:SAML:2.0:
  nameid-format:persistent"  >HuCJIy9v5MdrjJQOgsuT4NWmVUl3
  </lib:IDPProvidedNameIdentifier>
  </sec:SessionSubject>
<sec:ProviderID>http://mach1.red.com</sec:ProviderID>
  <lib:AuthnContext xmlns:lib="urn:liberty:iff:2003-08"><lib:AuthnContextClassRef>urn:oasis:
  names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</lib:AuthnContextClassRef>
  <lib:AuthnContextStatementRef>http://www.projectliberty.org/schemas/authctx/classes/
  Password</lib:AuthnContextStatementRef></lib:AuthnContext></sec:SessionContext>
  </sec:ResourceAccessStatement>
<saml:AuthenticationStatement xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" 
  AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password" 
  AuthenticationInstant="2007-03-27T08:19:24Z">
<saml:Subject>
<saml:NameIdentifier Format="urn:liberty:iff:nameid:entityID">
  http://isdev-2.red.com</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
  </saml:ConfirmationMethod>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"><KeyName>CN=sun-unix, OU=Sun 
  Access Manager, O=Sun, C=US</KeyName><KeyValue><RSAKeyValue><Modulus>AOA/2kpfKFWvRXOMbrmTlKe102ibw/
  aTd3HBVgI8cHsywww8M1J0X+vJvvk6eabTNWY5jBfTo9i1bC4AXXoRlxgsE/6Uq
  5+6NGrd+iwfvj25x8HzHX8LrJ+7EzlGVsKOM+
  A3vTP0tCkmYE4jatZbWlRoto0wyInP2wMFdKPrmYWL</Modulus>
<Exponent>AQAB</Exponent>
  </RSAKeyValue>
  </KeyValue></KeyInfo></saml:SubjectConfirmation>
</saml:Subject>
</saml:AuthenticationStatement>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<Reference URI="#s5dc88819de075e4e9c8db3deb8b46d4d8758b4b901">
<Transforms>
<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<DigestValue>td1CqmbWC5eMXCK6IFhzZxn3GJg=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>
YJ4g+jV5KIQRpkI9jlsZMbKx9lBhEB5ngB8NrH5nPh8+XFTK2gPZNzovOYOzxlznuxxbvC3A4rpg
UoSeE3N+oE4sl5KnY1GewFgjckAdeWafcLhGd9O68A+9nqMnRW/5fR9mnbk9eqZO8zx2bO8toiWi
pQCTU5XcDYkCNb8LgFs=
</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>
MIICOTCCAeOgAwIBAgIBEjANBgkqhkiG9w0BAQQFADBFMQswCQYDVQQGEwJVUzEYMBYGA1UEChMP
cmVkLmlwbGFuZXQuY29tMRwwGgYDVQQDExNDZXJ0aWZpY2F0ZSBNYW5hZ2VyMB4XDTA1MDYwMjE3
NTkxOFoXDTA2MDYwMjE3NTkxOFowVzELMAkGA1UEBhMCVVMxDDAKBgNVBAoTA1N1bjEnMCUGA1UE
CxMeU1VOIEphdmEgU3lzdGVtIEFjY2VzcyBNYW5hZ2VyMREwDwYDVQQDEwhzdW4tdW5peDCBnzAN
BgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA4D/aSl8oVa9Fc4xuuZOUp7XTaJvD9pN3ccFWAjxwezLD
DDwzUnRf68m++Tp5ptM1ZjmMF9Oj2LVsLgBdehGXGCwT/pSrn7o0at36LB++PbnHwfMdfwusn7sT
OUZWwo4z4De9M/S0KSZgTiNq1ltaVGi2jTDIic/bAwV0o+uZhYsCAwEAAaNoMGYwEQYJYIZIAYb4
QgEBBAQDAgZAMA4GA1UdDwEB/wQEAwIE8DAfBgNVHSMEGDAWgBQqOASyzZ41LergF+cSQN1Gokpa
XjAgBgNVHREEGTAXgRVoZW5nLW1pbmcuaHN1QHN1bi5jb20wDQYJKoZIhvcNAQEEBQADQQDKxdPy
821aQRVZ0wLqa6LBYZCUcZD5AMvzl3EylwtniHmzPtOeZe4NmFj7qQziSb1H57NSkiwKaLZ7Mt6F
jaUU
</X509Certificate>
</X509Data>
</KeyInfo>
</Signature></saml:Assertion>
</saml:AttributeValue></saml:Attribute></saml:AttributeStatement></saml:Assertion>

Following are the procedures to enable bootstrapping of the Liberty ID-WSF Discovery Service using SAML v2.

ProcedureTo Enable an Identity Provider for SAML v2 Bootstrapping of Liberty ID-WSF

  1. If metadata for the identity provider you are configuring has not yet been imported, or signing and encryption certificate aliases have not been configured in the for the existing identity provider metadata, create the identity provider in the OpenSSO Enterprise console or with the ssoadm command line utility. See Creating an Entity.

  2. In the OpenSSO Enterprise Console, click the Federation tab.

  3. Click the hosted Identity Provider you wish to edit.

  4. Check Discovery Bootstrapping Enabled check box.

  5. Click Save.

  6. Go to the Configuration tab.

  7. Click the Servers and Sites tab.

  8. Click Default Server Settings.

  9. Click the Advanced tab.

  10. If the com.sun.identity.liberty.ws.util.providerManagerClass property does not exist in the Advanced attribute table, add it and define the following value for it:

    com.sun.identity.liberty.ws.util.providerManagerClass = com.sun.identity.saml2.plugins.SAML2ProviderManager


    Note –

    By default, this property has no value. In this case, Liberty ID-WSF 1.1 works with ID-FF providers. After you change this value, ID-WSF 1.1 works with SAMLv2 providers but not ID-FF providers. To switch back to ID-FF providers, delete the attribute from the Advanced attribute table.


  11. Click Save.

  12. Restart the web container.

ProcedureTo Enable a Service Provider for SAML v2 Bootstrapping of Liberty ID-WSF

  1. In the OpenSSO Enterprise Console, click the Federation tab.

  2. Click the hosted Service Provider you wish to configure.

  3. Click the Assertion Processing tab.

  4. In the Attribute Map attribute, add the following value:

    urn:liberty:disco:2003-08:DiscoveryResourceOffering=urn:liberty:disco:2003-08:DiscoveryResourceOffering

  5. Click Save.

Retrieving SAMLv2 Bootstrapping of Liberty ID-WSF from the WSC

You can use the following API to retrieve the Discovery Service bootstrap resource offering and included security token from the web services client:

ResourceOffering SAML2SDKUtil.getDiscoveryBootStrapResourceOffering(
HttpServletRequest request)

List SAML2SDKUtil.getDiscoveryBootStrapCredentials(
HttpServletRequest request) 

For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

WS-Federation Operations

This section provides steps for configuring OpenSSO Enterprise's implementation of WS-Federation so that single sign-on can work among OpenSSO and ADFS (Microsoft Active Directory Federation Service)-based environments. For a detailed description of deployment considerations, use cases, and configuration overviews, see Chapter 9, Enabling Web Services Federation Between Active Directory Federation Service and OpenSSO Enterprise, in Sun OpenSSO Enterprise 8.0 Deployment Planning Guide. For a detailed overview of OpenSSO Enterprise's implementation, see Using WS-Federation in Sun OpenSSO Enterprise 8.0 Technical Overview.


Note –

The steps provided here are based on the assumption that you are proficient in setting up ADFS-based environment as described in


Enabling WS-Federation between an ADFS environment and an OpenSSO Enterprise environment involves exchanging metadata to enable a trust relationship. The steps in this section use host names consistent with those outlined in the Microsoft Active Directory Federation Services (ADFS) Step-by-Step Guide. You can, however, use any host names you wish.

Prior to this, the following requirements must be met:

Proceed to the following sections to see the configuration steps.

ProcedureTo Configure OpenSSO Enterprise as a Service Provider

  1. In the ADFS environment, Add a new Resource Partner to adfsaccount.adatum.com and configure the following attributes:

    Display Name

    Enter a name, for example OpenSSO SP.

    Federation Service URI

    This must be the same as the TokenIssuerName in the service provider metadata file that you will create. For example:

    urn:federation:mywsfedsp

    Federation Service endpoint URL

    The last path component of this URL must the match metaAlias in the service provider extended meta data file that you will create. For example:

    https://amhost(:amsecureport)/fam/WSFederationServlet/metaAlias

    /mywsfedsp

  2. Convert the Active Directory machine's token signing certificate file (for example, adfsaccount_ts.cer) to PEM format. You use OpenSSL for this conversion. For example:

    openssl x509 in adfsaccount_ts.cer inform DER -out adfsaccount_ts.pem outform PEM

  3. Create the metadata and extended metadata for an identity provider using the ssoadm command line utility. For example purposes, the files are named adatum.xml and adatumx.xml..

    For example:

    create-meadata-templ –u amadmin –f password_file –m adatum.xml –x adtumx.xml –i /metaalias –y entity_id –c wsfed

  4. Create the metadata and extended metadata for a service provider using the ssoadm command line utility. For example purposes, the files are named wsfedsp.xml and wsfedspx.xml.


    Note –

    You can also use the OpenSSO Enterprise console to create a hosted service provider or identity provider. For more information, see WS-Federation Entity Provider.


    For example:

    create-metadata-templ –u amadmin –f password_file –m wsfedsp.xml –x wsfedspx.xml –s /metaalias –y entity_id –c wsfed

  5. In adatum.xml, paste the PEM-encoded certificate from adfsaccount_ts.pem into the <ns2:X509Certificate> element.

  6. In the hosted service provider (wsfedsp.xml), change the hostname and port in the <ns3:Address> element to match your configuration. For example:


    <?xml version="1.0" encoding="UTF8"
    standalone="yes"?>
    <Federation FederationID="mywsfedsp"
    xmlns="http://schemas.xmlsoap.org/ws/2006/12/federation">
    <TokenIssuerName>urn:federation:mywsfedsp</TokenIssuerName>
    <TokenIssuerEndpoint>
    <ns3:Address
    xmlns:ns3="http://www.w3.org/2005/08/addressing">https://patlinux.red.ip
    lanet.com:8443/fam/WSFederationServlet/metaAlias/mywsfedsp</ns3:Address>
    </TokenIssuerEndpoint>
    </Federation>
  7. In the hosted service provider (adatumx.xml), change the hostname and port in the <HomeRealmDiscoveryService> attribute to match your configuration. For example:


    <FederationConfig xmlns="urn:sun:fm:wsfederation:1.0:federationconfig"
    xmlns:fm="urn:sun:fm:wsfederation:1.0:federationconfig"
    hosted="1" FederationID="mywsfedsp">
    <SPSSOConfig metaAlias="/mywsfedsp">
    <Attribute name="displayName">
    <Value>My Open Federation Service Provider</Value>
    </Attribute>
    <Attribute name="AccountRealmSelection">
    <Value>cookie</Value>
    </Attribute>
    <Attribute name="AccountRealmCookieName">
    <Value>amWSFederationAccountRealm</Value>
    </Attribute>
    <Attribute name="HomeRealmDiscoveryService">
    <Value>http://patlinux.red.com:8180/fam/RealmSelectio
    n/metaAlias/mywsfedsp</Value>
    </Attribute>
    <Attribute name="spAccountMapper">
    <Value>com.sun.identity.wsfederation.plugins.DefaultADFSPartn
    erAccountMapper</Value>
    </Attribute>
    <Attribute name="spAttributeMapper">
    <Value>com.sun.identity.wsfederation.plugins.DefaultSPAttribu
    teMapper</Value>
    </Attribute>
    </SPSSOConfig>
    </FederationConfig>
  8. Load the identity provider and service provider metadata to OpenSSO Enterprise. From the console:

    1. Log in to the console and click the Federation tab and then the Import Entity button.

    2. Choose the realm to which the requesting service provider belongs.

    3. In the Where Does the Meta Data File Reside field, choose File and click Upload.

    4. Choose adatum.xml.

    5. Click Ok.

    6. In the Where Does the Extended Meta Data File Reside field, choose File and click Upload.

    7. Choose adtumx.xml.

    8. Click Ok.

    9. Repeat the steps for loading the service provider meta data (wsfedsp.xml and wsfedspx.xml).

  9. Create a circle of trust and add the identity provider and service provider. For instructions, see Circle of Trust.

  10. On the OpenSSO Enterprise instance, go to https://opensssohost(:openssosecureport)/opensso WSFederationServlet/metaAlias/mywsfedsp?goto=https://openssohost(:openssosecureport)/opensso

    You should be forwarded to the realm selection page. Click 'Proceed. You may see a few redirections in the browser's address bar before reaching the user's profile page in OpenSSO Enterprise.

    If you do this from outside the Window domain, you will get an HTTPBasic authentication username/password dialog. Enter the user's Active Directory credentials to gain access.

    The realm selection process sets a persistent cookie. If you enter the same URL a second time, you should not be prompted for a realm and should be redirected to the OpenSSO Enterprise user page.

  11. Configure your installed policy agent profile with the WS-Federation servlet as its login URL.

    For the J2EE policy agent profile:

    • Log in to the console and go to Access Control>realm>Agents

    • Click the name of the J2EE policy agent you wish to edit.

    • In the OpenSSO Login URL attribute, enter the WS-Federation servlet, for example:

      https://openssohost(:openssosecureport)/opensso/WSFederationServlet/metaAlias/mywsfedsp

    For the web policy agent profile:

    • Log in to the console and go to Access Control>realm>Agents

    • Click the name of the web policy agent you wish to edit.

    • In the OpenSSO Login URL attribute, enter the WS-Federation servlet, for example:

      https://openssohost(:openssosecureport)/opensso/WSFederationServlet/metaAlias/mywsfedsp

    When accessing the resource protected by the policy agent, you should be authenticated through WS-Federation.

ProcedureTo Configure OpenSSO Enterprise as an Identity Provider

  1. Create a token signing certificate in a Java Keystore on the OpenSSO Enterprise machine. For example:

    keytool keystore keystore.jks genkey dname "CN=amhost" alias mywsfedidp

    Specify the same password for the keystore and key. Put the keystore in any location, since you will need to specify the full path

  2. Encrypt the keystore/key password. The easiest method is to use the OpenSSO Enterprise encode.jsp:

    1. Go to https://host:port/opensso/encode.jsp.

    2. Enter the password.

    3. Create two files, .storepass and .keypass, whose only content is the encrypted password.

  3. Set the path to keystore.jks and the two files containing encrypted the passwords. To do so:

    1. Log into the OpenSSO Enterprise console.

    2. Go to Configuration>Sites and Servers.

    3. Click the Default Server Settings button and click the Security tab.

    4. Configure the following attributes:

      Keystore File

      Set to /path/keystore.jks

      Keystore Password File

      Set to /path/.storepass

      Private Key Password File

      Set to /path/.keypass

    5. You must restart the web container for the changes to take effect.

  4. Export the token signing certificate in DER format. For example:

    keytool keystore keystore.jks export alias mywsfedidp file cert.der

  5. Copy cert.der to the adfsresource machine.

  6. Create the metadata and extended metadata for a remote service provider using the ssoadm command line utility.

    For example:

    create-meadata-templ –u amadmin –f password_file –m treyresearrch.xml.xml –x treyresearch.xmlx.xml –s /metaalias –y entity_id –c wsfed

    For this example, the files are named treyresearch.xml and treyresearchx.xml.

  7. Create the metadata and extended metadata for a hosted identity provider using the ssoadm command line utility.


    Note –

    You can also use the OpenSSO Enterprise console to create a hosted service provider or identity provider. For more information, see WS-Federation Entity Provider.


    For example:

    create-meadata-templ –u amadmin –f password_file –m wsfedidp.xml –x wsfedidpx.xml –i /metaalias –y entity_id –c wsfed

    For this example, the files are named wsfedidp.xml and wsfedidpx.xml.

  8. In the remote service provider (treyresearch.xml), change the hostname and port in the <ns3:Address> element to match your configuration.

  9. In the remote service provider (wsfedidpx.xml), change the hostname and port in the <HomeRealmDiscoveryService> attribute to match your configuration. For example:


    <FederationConfig xmlns="urn:sun:fm:wsfederation:1.0:federationconfig"
    xmlns:fm="urn:sun:fm:wsfederation:1.0:federationconfig"
    hosted="1" FederationID="mywsfedidp">
    <IDPSSOConfig metaAlias="/mywsfedidp">
    <Attribute name="displayName">
    <Value>My Open Federation Identity Provider</Value>
    </Attribute>
    <Attribute name="upnDomain">
    <Value>red.com</Value>
    </Attribute>
    <Attribute name="signingCertAlias">
    <Value>mywsfedidp</Value>
    </Attribute>
    <Attribute name="assertionEffectiveTime">
    <Value>600</Value>
    </Attribute>
    <Attribute name="idpAccountMapper">
    <Value>com.sun.identity.wsfederation.plugins.DefaultIDPAccoun
    tMapper</Value>
    </Attribute>
    <Attribute name="idpAttributeMapper">
    <Value>com.sun.identity.wsfederation.plugins.DefaultIDPAttrib
    uteMapper</Value>
    </Attribute>
    </IDPSSOConfig>
    </FederationConfig>
  10. Load the identity provider and service provider metadata to OpenSSO Enterprise. From the console:

    1. Log in to the console and click the Federation tab and then the Import Entity button.

    2. Choose the realm to which the requesting service provider belongs.

    3. In the Where Does the Meta Data File Reside field, choose File and click Upload.

    4. Choose wsfedidp.xml.

    5. Click OK.

    6. In the Where Does the Extended Meta Data File Reside field, choose File and click Upload.

    7. Choose wsfedidpx.xml.

    8. Click Ok.

    9. Repeat the steps for loading the service provider meta data (treyresearch.xml and treyresearchx.xml).

  11. Create a circle of trust and add the identity provider and service provider. For instructions, see Circle of Trust.

  12. In the ADFS environment, add a new Account Partner to adfsresource.treyresearch.net and configure the following attributes:

    Display Name

    Enter a name, for example OpenSSO IDP.

    Federation Service URI

    This must be the same as the TokenIssuerName in the identity provider metadata. For example:

    urn:federation:mywsfedidp

    Federation Service endpoint URL

    The last path component of this URL must the match metaAlias in the identity provider extended metadata. For example:

    https://amhost(:amsecureport)/fam/WSFederationServlet

    /metaAlias/mywsfedidp

    Account Partner Verification Certificate

    Import the OpenSSO token signing certificate that you copied to the adfsresource machine.

  13. Delete all cookies in your browser and go to the sample claims-aware application at https://adfsweb.treyresearch.net:8081/claimapp/.

    You should see the OpenSSO Enterprise identity provider listed in the drop down list. Select the OpenSSO identity provider. You will be redirected to the standard OpenSSO Enterprise login screen. After logging in, you will be redirected back to the sample application

  14. Click the Sign Out link to do a single logout.

    Check that you are logged out by trying the https://adfsweb.treyresearch.net:8081/claimapp/ URL again. You should be redirected to the OpenSSO login page, demonstrating that neither ADFS or OpenSSO have an active session for the browser.

    The realm choice is stored in a persistent cookie. If you close and restart the browser, return to https://adfsweb.treyresearch.net:8081/claimapp/. You should directly proceed to the OpenSSO Enterprise login page.

Chapter 9 Identity Web Services

OpenSSO Enterprise implements the Liberty Identity Web Services Framework (Liberty ID-WSF) which defines a web services stack that can be used to support the Liberty Alliance Project business model. These web services leverage the Liberty ID-FF for principal authentication, federation, and privacy protections.

Web services are distributed applications developed using open technologies such as eXtensible Markup Language (XML), SOAP, and HyperText Transfer Protocol (HTTP). Enterprises use these technologies as a mechanism for allowing their applications to cross network boundaries and communicate with those of their partners, customers and suppliers. OpenSSO Enterprise implements the Liberty ID-WSF which is designed to operate in concert with a federated identity framework, such as the Liberty Identity Federation Framework (Liberty ID-FF). Federated includes the following Liberty ID-WSF web services:

Authentication Web Service

The Authentication Web Service adds authentication functionality to the SOAP binding. It provides authentication to a WSC, allowing the WSC to obtain security tokens for further interactions with other services at the same provider. These other services may include a discovery service or single sign-on service. Upon successful authentication, the final Simple Authentication and Security Layer (SASL) response contains the resource offering for the Discovery Service.


Caution – Caution –

Do not confuse the Liberty-based Authentication Web Service with the proprietary OpenSSO Enterprise Authentication Service discussed in About Identity Web Services in Sun OpenSSO Enterprise 8.0 Technical Overview.


Authentication Web Service Attribute

The Authentication Web Service attributes are global attributes. The value is carried across the OpenSSO Enterprise configuration and inherited by every organization.

The attribute for the Authentication Web Service is defined in the amAuthnSvc.xml service file and is called the Mechanism Handlers List.

Mechanism Handlers List

The Mechanism Handler List attribute stores information about the SASL mechanisms that are supported by the Authentication Web Service.

key Parameter

The required key defines the SASL mechanism supported by the Authentication Web Service.

class Parameter

The required class specifies the name of the implemented class for the SASL mechanism. Two authentication mechanisms are supported by the following default implementations:

Table 9–1 Default Implementations for Authentication Mechanism

Class 

Description 

com.sun.identity.liberty.ws.authnsvc.mechanism.PlainMechanismHandler

This class is the default implementation for the PLAIN authentication mechanism. It maps user identifiers and passwords in the PLAIN mechanism to the user identifiers and passwords in the LDAP authentication module under the root organization. 

com.sun.identity.liberty.ws.authnsvc.mechanism.CramMD5MechanismHandler

This class is the default implementation for the CRAM-MD5 authentication mechanism. 


Note –

The Authentication Web Service layer provides an interface that must be implemented for each SASL mechanism to process the requested message and return a response.


Challenge Cleanup Interval

Specifies cleanup interval (in seconds) in the default CRAM-MD5 mechanism handler implementation class com.sun.identity.liberty.ws.authnsvc.mechanism.CramMD5MechanismHandler. The internal thread will start to cleanup the challenge map based on this value.

Transform Classes

Specifies the transform name to the implementation class mapping. Values are comma separated with a pipe (|) as delimiter for the transform name and implementation class name. For example, name1|class1, name2|class2.

PLAIN Mechanism Handler Authentication Module

Specifies the default authentication module used for the PLAIN mechanism handler. The default value is the Data Store authentication module.

CRAM-MD5 Mechanism Handler Authentication Module

This specifies the default authentication module used for the CRAM MD5 mechanism handler. The default value is the Data Store authentication module

Liberty Personal Profile Service

The Liberty Personal Profile Service is a data service that supports storing and modifying a principal's identity attributes. It maps attributes defined in a user's personal profile to LDAP attributes in a data store. These identity attributes might include the user's first name, last name, home address, or emergency contact information. The Liberty Personal Profile Service is queried or updated by a WSC acting on behalf of the principal. .

Liberty Personal Profile Service Attributes

The Liberty Personal Profile Service attributes are global attributes. The values of these attributes are carried across the OpenSSO Enterprise configuration and inherited by each configured organization.

The attributes are:

ResourceID Mapper

The value of this attribute specifies the implementation of com.sun.identity.liberty.ws.interfaces.ResourceIDMapper. Although a new implementation can be developed, OpenSSO Enterprise provides the default com.sun.identity.liberty.ws.idpp.plugin.IDPPResourceIDMapper, which maps a discovery resource identifier to a user identifier.

Authorizer

Before processing a request, the Liberty Personal Profile Service verifies the authorization of the WSC making the request. There are two levels of authorization verification:

Authorization occurs through a plug-in to the Liberty Personal Profile Service, an implementation of the com.sun.identity.liberty.ws.interfaces.Authorizer interface. Although a new implementation can be developed, OpenSSO Enterprise provides the default class, com.sun.identity.liberty.ws.idpp.plugin.IDPPAuthorizer. This plug-in defines four policy action values for the query and modify operations:

The resource values for the rules are similar to x-path expressions defined by the Liberty Personal Profile Service. For example, a rule can be defined like this:


/PP/CommonName/AnalyzedName/FN    Query   Interact for consent
/PP/CommonName/*                  Modify  Interact for value
/PP/InformalName                  Query   Deny

Authorization can be turned off by deselecting one or both of the following attributes, which are also defined in the Liberty Personal Profile Service:

Attribute Mapper

The value of this attribute defines the class for mapping a Liberty Personal Profile Service attribute to an OpenSSO Enterprise user attribute. By default, the class is com.sun.identity.liberty.ws.idpp.plugin.IDPPAttributeMapper.


Note –

com.sun.identity.liberty.ws.idpp.plugin.IDPPAttributeMapper is not a public class.


Provider ID

The value of this attribute defines the unique identifier for this instance of the Liberty Personal Profile Service. Use the format protocol://hostname:port/deloy-uri/Liberty/idpp.

Name Scheme

The value of this attribute defines the naming scheme for the Liberty Personal Profile Service common name. Choose First Last or First Middle Last.

Namespace Prefix

The value of this attribute specifies the namespace prefix that is used for Liberty Personal Profile Service XML protocol messages. A namespace differentiates elements with the same name that come from different XML schemas. The Namespace Prefix is prepended to the element.

Supported Containers

The values of this attribute define a list of supported containers in the Liberty Personal Profile Service. A container, as used in this instance, is an attribute of the Liberty Personal Profile Service.


Note –

The term container as described in this section is not related to the OpenSSO Enterprise identity-related object that is also called container.


For example, Emergency Contact and Common Name are two default containers for the Liberty Personal Profile Service. To add a new container, click Add, enter values in the provided fields and click OK.

PPLDAP Attribute Map List

Each identity attribute defined in the Liberty Personal Profile Service maps one-to-one with a OpenSSO Enterprise LDAP attribute. For example, JobTitle=sunIdentityServerPPEmploymentIdentityJobTitle maps the Liberty JobTitle attribute to the OpenSSO Enterprise sunIdentityServerPPEmploymentIdentityJobTitle attribute.

The value of this attribute is a list that specifies the mappings. The list is used by the attribute mapper defined in Attribute Mapper, by default, com.sun.identity.liberty.ws.idpp.plugin.IDPPAttributeMapper.


Note –

When adding new attributes to the Liberty Personal Profile Service or the LDAP data store, ensure that the new attribute mappings are configured as values of this attribute.


Require Query PolicyEval

If selected, this option requires that a policy evaluation be performed for Liberty Personal Profile Service queries. For more information, see Authorizer.

Require Modify PolicyEval

If selected, this option requires that a policy evaluation be performed for Liberty Personal Profile Service modifications. For more information, see Authorizer.

Extension Container Attributes

The Liberty Personal Profile Service allows you to specify extension attributes that are not defined in the Liberty Alliance Project specifications. The values of this attribute specify a list of extension container attributes. All extensions should be defined as:

    /PP/Extension/PPISExtension [@name=’extensionattribute’]

The following sample illustrates an extension query expression for creditcard, an extension attribute.


Example 9–1 Extension Query for creditcard


 /pp:PP/pp:Extension/ispp:PPISExtension[@name=’creditcard’]
Note: The prefix for the PPISExtension is different,
 and the schema for the PP extension is as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.sun.com/identity/liberty/pp"
  targetNamespace="http://www.sun.com/identity/liberty/pp">
  <xs:annotation>
      <xs:documentation>
      </xs:documentation>
  </xs:annotation>

  <xs:element name="PPISExtension">
     <xs:complexType>
        <xs:simpleContent>
           <xs:extension base="xs:string">
              <xs:attribute name="name" type="xs:string"
                use="required"/>
           </xs:extension>
        </xs:simpleContent>
     </xs:complexType>
   </xs:element>
</xs:schema>

Type the new attribute and click Add.

Extension Attributes Namespace Prefix

The value of this attribute specifies the namespace prefix for the extensions defined in the Extension Container Attributes. This prefix is prepended to the element and helps to distinguish metadata from different XML schema namespaces.

Service Update

The SOAP Binding Service allows a service to indicate that requesters should contact it on a different endpoint or use a different security mechanism and credentials to access the requested resource. If selected, this attribute affirms that there is an update to the service instance.

Service Instance Update Class

The value of this attribute specifies the default implementation class com.sun.identity.liberty.ws.idpp.plugin.IDPPServiceInstanceUpdate. This class is used to update the information for the service instance.

Alternate Endpoint

The value of this attribute specifies an alternate SOAP endpoint to which a SOAP request can be sent.

Discovery Service

The Discovery Service is a framework for describing and discovering identity web services. It allows a requesting entity, such as a web service client, to dynamically determine a principal's registered web services provider (WSP), such as an attribute provider. Typically, a service provider queries the Discovery Service, which responds by providing a resource offering that describes the requested WSP. (A resource offering defines associations between a piece of identity data and the service instance that provides access to the data.) The implementation of the Discovery Service includes Java and web-based interfaces. The service is bootstrapped using SAMLv2, Liberty ID-FF single sign-on or the Liberty ID-WSF Authentication Web Service. .


Note –

By definition, a discoverable service is assigned a service type URI, allowing the service to be registered in Discovery Service instances. The service type URI is typically defined in the Web Service Definition Language (WSDL) file that defines the service.


Discovery Service Attributes

The Discovery Service attributes are global attributes whose values are applied across the OpenSSO Enterprise configuration and inherited by every configured organization. The Discovery Service attributes are:

Provider ID

This attribute takes a URI that points to the Discovery Service. Use the format protocol://host:port/opensso/Liberty/disco. This value can be changed only if other relevant attributes values are changed to match the new pointer.

Supported Authentication Mechanisms

This attribute specifies the authentication methods supported by the Discovery Service. These security mechanisms refer to the way a web service consumer authenticates to the web service provider or provides message-level security. By default, all available methods are selected. If an authentication method is not selected and a WSC sends a request using that method, the request is rejected.

Supported Directives

This attribute allows you to specify a policy-related directive for a resource. If a service provider wants to use an unsupported directive, the request will fail. The following table describes the available options. .

Table 9–2 Policy-Related Directives

Directive 

Purpose 

AuthenticateRequester

The Discovery Service should include a SAML assertion containing an AuthenticationStatement in its query responses to enable the client to authenticate to the service instance hosting the resource.

AuthenticateSessionContext

The Discovery Service should include a SAML assertion containing a SessionContextStatement in its query responses that indicate the status of the session.

AuthorizeRequestor

The Discovery Service should include a SAML assertion containing a ResourceAccessStatement in its responses that indicate whether the client is allowed to access the resource.

EncryptResourceID

The Discovery Service should encrypt the resource identifier in responses to all clients. 

GenerateBearerToken

For use with Bearer Token Authentication, the Discovery Service should generate a token that grants the bearer permission to access the resource. 

Policy Evaluation for Discovery Lookup

If enabled, the service will perform a policy evaluation for the DiscoveryLookup operation. By default, the check box is not selected.

Policy Evaluation for Discovery Update

If enabled, the service will perform a policy evaluation for the DiscoveryUpdate operation. By default, the check box is not selected.

Authorizer Plug-in Class

The value of this attribute is the name and path to the class that implements the com.sun.identity.liberty.ws.interfaces.Authorizer interface used for policy evaluation of a WSC. The default class is com.sun.identity.liberty.ws.disco.plugins.DefaultDiscoAuthorizer.

Entry Handler Plug-in Class

The value of this attribute is the name and path to the class that implements the com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler interface. This interface is used to set or retrieve a principal’s discovery entries. To handle discovery entries differently, implement the com.sun.identity.liberty.ws.disco.plugins.DiscoEntryHandler interface and set the implementing class as the value for this attribute. The default implementation for the Discovery Service is com.sun.identity.liberty.ws.disco.plugins.UserDiscoEntryHandler.

Classes For ResourceIDMapper Plug-in

The value of this attribute is a list of classes that generate identifiers for a resource offering configured for an organization or role. com.sun.identity.liberty.ws.interfaces.ResourceIDMapper is an interface used to map a user identifier to the resource identifier associated with it. The Discovery Service provides two implementations for this interface:

Different implementations may also be developed with the interface and added as a value of this attribute by clicking New and defining the following attributes:

Authenticate Response Message

If enabled, the service authenticates the response message. By default, the function is not enabled.

SessionContextStatement for Bootstrapping

If enabled, this attribute specifies whether to generate a SessionContextStatement for bootstrapping. A SessionContextStatement conveys the session status of an entity. By default, this function is not enabled.

Encrypt NameIdentifier in Session Context for Bootstrapping

If enabled, the service encrypts the name identifier in a SessionContextStatement. By default, this function is not enabled.

Implied Resource

If enabled, the service does not generate a resource identifier for bootstrapping. By default, this function is not enabled.

Name Identifier Mapper

Defines the class and path that implements the NameIdentifierMapper interface. It is used to map user's Name Identifier from one provider to another.

Global Entry Handler Plug-in Class

Defines the class and path that implements the DiscoEntryHandler interface. It is used to get and set Disco Entries for a user stored in a realm. When an implied resource is used in a discovery service request, this implementation is used to perform the operation.

Resource Offerings for Bootstrapping

This attribute defines a resource offering for bootstrapping a service. After single sign-on (SSO), this resource offering and its associated credentials will be sent to the client in the SSO assertion. Only one resource offering is allowed for bootstrapping. The value of the Resource Offerings for Bootstrapping attribute is a default value configured during installation. If you want to define a new resource offering, you must first delete the existing resource offering, then click New to define the attributes for a new resource offering. If you want to edit an existing resource offering, click the name of the existing Service Type to modify the attributes.

Storing Resource Offerings

A resource offering defines an association between a type of identity data and a URI to the WSDL file that provides information about obtaining access to the data. In OpenSSO Enterprise, a resource offering can be stored as a user attribute or as a dynamic attribute. Storing resource offerings within a user profile supports both DiscoveryLookup and DiscoveryUpdate operations. Storing resource offerings within a service and assigning that service to a realm supports only the DiscoveryLookup operation using the discovery protocol. (Updates can still be done using the OpenSSO Enterprise Console.) More information is provided in the following sections:

Storing Resource Offerings as User Attributes

Resource offerings can be stored as an attribute under a user’s profile using the Lightweight Directory Access Protocol (LDAP). Storing resource offerings within a user profile supports both DiscoveryLookup and DiscoveryUpdate operations. The following procedure explains how to access and create a user’s resource offerings.

ProcedureTo Store a Resource Offering as a User Attribute

  1. In the OpenSSO Enterprise Console, click the Access Control tab.

  2. Select the name of the realm that contains the user profile you want to modify.

  3. Select Subjects to access user information.

  4. Select the name of the user profile that you want to modify.

  5. Select Services to access the user's services.

  6. Click Discovery Service.

  7. Click Add.

  8. (Optional) Type a value for the Resource ID Attribute.

    This field defines an identifier for the resource offering.

  9. Type the Resource ID Value.

    This field defines the resource identifier. A resource identifier is a URI registered with the Discovery Service that point to a particular discovery resource. It is generated by the profile provider. The value of this attribute must not be a relative URI and should contain a domain name that is owned by the provider hosting the resource. If a discovery resource is exposed in multiple Resource Offerings, the Resource ID Value for all of those resource offerings would be the same. An example of a valid Resource ID value is http://profile-provider.com/profiles/14m0B82k15csaUxs.


    Tip –

    urn:libery:isf:implied-resource can be used as a Resource ID Value when only one resource can be operated upon at the service instance being contacted. The URI only implicitly identifies the resource in question. In some circumstances, the use of this resource identifier can eliminate the need for contacting the discovery service to access the resource.


  10. (Optional) Enter a description of the resource offering in the Description field.

  11. Type a URI for the value of the Service Type attribute.

    This URI defines the type of service.


    Tip –

    It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:id-sis-pp:2003-08.


  12. Type a URI for the value of the Provider ID attribute.

    This attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://profile-provider.com.


    Note –

    The provider represented by the URI in the Provider ID attribute must also have a class entry in the ResourceIDMapper attribute.


  13. Click New Description to define the Service Description.

    For each resource offering, at least one service description must be created.

    1. Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.

      This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.

    2. Type a value for the End Point URL.

      This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.

    3. (Optional) Type a value for the SOAP Action.

      This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.

    4. Click OK to complete the configuration.

  14. Check the Options box if there are no options or add a URI to specify options for the resource offering.

    This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options.

  15. Select a directive for the resource offering.

    Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:

    • GenerateBearerToken specifies that a bearer token be generated.

    • AuthenticateRequester must be used with any service description that use SAML for message authentication.

    • EncryptResourceID specifies that the Discovery Service encrypt the resource ID.

    • AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.

    • AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.

    If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.

  16. Click Save to save the configuration.

Storing Resource Offerings as Dynamic Attributes

Due to the repetition inherent in storing discovery entries as user attributes, OpenSSO Enterprise has established the option of storing a discovery entry as a dynamic attribute within a realm. The realm can then be assigned to an identity-related object, making the entry available to all users within the object. Unlike storing a discovery entry as a user attribute, this scenario only supports the DiscoveryLookup operation.

ProcedureTo Store Resource Offerings as Dynamic Attributes in a Realm

To create a discovery entry as a dynamic attribute in a realm, the Discovery Service must first be added and a template created.

  1. In the OpenSSO Enterprise Console, click the Access Control tab.

  2. Select the name of the realm you want to modify.

  3. Select Services to access the realm's services.

  4. Click Add to add the Discovery Service to the realm.

    A list of available services is displayed.

  5. Select Discovery Service.

  6. Click Next.

  7. Click Discovery Service to add a resource offering to the service.

  8. Click Add to add a resource offering.

  9. (Optional) Enter a description of the resource offering in the Description field.

  10. Type a URI for the value of the Service Type attribute.

    This URI defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:id-sis-pp:2003-08.

  11. Type a URI for the value of the Provider ID attribute.

    The value of this attribute contains the URI of the provider of the service instance. This information is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://profile-provider.com.


    Note –

    The provider represented by the URI in the Provider ID attribute must also have an entry in the ResourceIDMapper attribute.


  12. Click New Description to define the Service Description.

    For each resource offering, at least one service description must be created.

    1. Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.

      This field lists the security mechanisms that the service instance supports. Select the security mechanisms that you want to add and click Add. To prioritize the list, select the mechanism and click Move Up or Move Down.

    2. Type a value for the End Point URL.

      This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.

    3. (Optional) Type a value for the SOAP Action.

      This value is the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.

    4. Click OK to complete the configuration.

  13. Check the Options box if there are no options or add a URI to specify options for the resource offering.

    This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options.

  14. Select a directive for the resource offering.

    Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:

    • GenerateBearerToken specifies that a bearer token be generated.

    • AuthenticateRequester must be used with any service description that use SAML for message authentication.

    • EncryptResourceID specifies that the Discovery Service encrypt the resource ID.

    • AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.

    • AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.

    If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.

  15. Click OK.

  16. Click Close to close the Discovery Resource Offering window.

  17. Click Save to save the configuration.

Storing a Resource Offering for Discovery Service Bootstrapping

Before a WSC can contact the Discovery Service to obtain a resource offering, the WSC needs to discover the Discovery Service. Thus, an initial resource offering for locating the Discovery Service is sent back to the WSC in a SAML assertion generated during authentication. The following procedure describes how to configure a global attribute for bootstrapping the Discovery Service. For more information on bootstrapping the Discovery Service, see Resource Offerings for Bootstrapping.

ProcedureTo Store a Resource Offering for Discovery Service Bootstrapping

  1. In the OpenSSO Enterprise Console, select the Web Services tab.

  2. Under Web Services, click the Discovery Service tab.

  3. Choose New under the Resource Offerings for Bootstrapping Resources attribute.

    By default, the resource offering for bootstrapping the Discovery Service is already configured. In order to create a new resource offering, you must first delete the default resource offering.

  4. (Optional) Type a description of the resource offering.

  5. Enter a URI for the value of the Service Type attribute.

    This field defines the type of service. It is recommended that the value of this attribute be the targetNamespace URI defined in the abstract WSDL description for the service. An example of a valid URI is urn:liberty:disco:2003-08.

  6. Enter a URI for the value of the Provider ID attribute.

    This attribute contains the URI of the provider of the service instance. This is useful for resolving trust metadata needed to invoke the service instance. A single physical provider may have multiple provider IDs. An example of a valid URI is http://sample_disco.com.


    Note –

    The provider represented by the URI in the Provider ID attribute must also have an entry in the Classes for ResourceIDMapper Plugin attribute.


  7. Click Add Description to define a security mechanism ID.

    For each resource offering, at least one service description must be created.

    1. Select the values for the Security Mechanism ID attribute to define how a web service client can authenticate to a web service provider.

      This field lists the security mechanisms that the service instance supports. Select the security mechanisms you wish to add and click the Add button. To arrange the priority of the list, select the mechanism and use the Move Up or Move Down buttons.

    2. Type a value for the End Point URL.

      This value is the URL of the SOAP-over-HTTP endpoint. The URI scheme must be HTTP or HTTPS as in https://soap.profile-provider.com/soap.

    3. (Optional) Type a value for the SOAP action.

      This field contains the equivalent of the wsdlsoap:soapAction attribute of the wsdlsoap:operation element in the service's concrete WSDL-based description.

    4. Click OK to save the configuration.

  8. Check the Options box if there are no options or add a URI to specify options for the resource offering.

    This field lists the options that are available for the resource offering. Options provide hints to a potential requestor about the availability of certain data or operations to a particular offering. The set of possible URIs are defined by the service type, not the Discovery Service. If no option is specified, the service instance does not display any available options. .

  9. Select a directive for the resource offering.

    Directives are special entries defined in SOAP headers that can be used to enforce policy-related decisions. You can choose from the following:

    • GenerateBearerToken specifies that a bearer token be generated.

    • AuthenticateRequester must be used with any service description that use SAML for message authentication.

    • EncryptResourceID specifies that the Discovery Service encrypt the resource ID.

    • AuthenticateSessionContext is specified when a Discovery Service provider includes a SAML assertion containing a SessionContextStatement in any future QueryResponse messages.

    • AuthorizeRequester is specified when a Discovery Service provider wants to include a SAML assertion containing a ResourceAccessStatement in any future QueryResponse messages.

    If you want to associate a directive with one or more service descriptions, select the check box for that Description ID. If no service descriptions are selected, the directive is applied to all description elements in the resource offering.

  10. Click OK to complete the configuration.

SOAP Binding Service

The SOAP Binding Service is the method of transport used to convey identity data between web services. It includes a set of Java APIs used by the developer of a Liberty-enabled identity service. The APIs are used to send and receive identity-based messages using SOAP, an XML-based messaging protocol. The service invokes the correct request handler class (specified by a service endpoint) to handle the messages.

SOAP Binding Service Attributes

The SOAP Binding Service attributes are global attributes. The values of these attributes are carried across the OpenSSO Enterprise configuration and inherited by every organization.

The SOAP Binding Service attributes are as follows:

Request Handler List

The Request Handler List stores information about the classes implemented from the com.sun.identity.liberty.ws.soapbinding.RequestHandler interface. The SOAP Binding Service provides the interface to process requests and return responses. The interface must be implemented on the server side for each Liberty-based web service that uses the SOAP Binding Service.

To add a new implementation, click New and define values for the following parameters.

Key Parameter

The Key parameter is the last part of the URI path to a SOAP endpoint. The SOAP endpoint in OpenSSO Enterpriseis the SOAPReceiver servlet. The URI to the SOAPReceiver uses the format protocol://host:port/deloy-uri/Liberty/key. If you define disco as the Key, the URI path to the SOAPReceiver for the corresponding Discovery Service would be protocol://host:port/opensso/Liberty/disco.


Note –

Different service clients must use different keys when connecting to the SOAPReceiver.


Class Parameter

The Class parameter specifies the name of the class implemented from com.sun.identity.liberty.ws.soapbinding.RequestHandler for the particular web service. For example, class=com.example.identity.liberty.ws.disco.DiscoveryService.

SOAP Action Parameter

The optional SOAP Action can be used to indicate the intent of the SOAP HTTP request. The SOAP processor on the receiving system can use this information to determine the ultimate destination for the service. The value is a URI. No defined value indicates no intent.


Note –

SOAP places no restrictions on the format or specificity of the URI or that it is resolvable.


Web Service Authenticator

This attribute takes as a value the implementation class for the Web Service Authenticator interface. This class authenticates a request and generates a credential for a WSC.


Note –

This interface is not public. The value of the attribute is configured during installation.


Supported Authentication Mechanisms

This attribute specifies the authentication mechanisms supported by the SOAP Receiver. Authentication mechanisms offer user authentication as well as data integrity and encryption. By default, all available authentication mechanisms are selected. If a mechanism is not selected and a WSC sends a request using it, the request is rejected. Following is a list of the supported authentication mechanisms:

Enforce Only Known Providers

If enabled, this property will enforce the ProviderID header sent in a SOAP message to ensure that the provider exists in the system. If it does not, the request will be rejected. If this attribute is not enabled, the check will be skipped.

Certification Alias For SSL Client Authentication

Value is set during installation. Client certificate alias that will be used in SSL connection for Liberty SOAP Binding.

Time Limit for Stale Message

Default value is 300000. Determines if a message is stale and thus no longer trustworthy. If the message timestamp is earlier than the current timestamp by the specified number of milliseconds, the message the considered to be stale.

Message ID Cache Cleanup Interval

Default value is 60000. Specifies the number of milliseconds to elapse before cache cleanup events begin. Each message is stored in a cache with its own message ID to avoid duplicate messages. When a message's current time less the received time exceeds thestaleTimeLimit value, the message is removed from the cache.

Supported SOAP Actors

Default value is http://schemas.xmlsoap.org/soap/actor/next. Specifies supported SOAP actors. Each actor must be separated by a pipe character (|).

Namespace Prefix Mapping

Default value is:


=S=http://schemas.xmlsoap.org/soap/envelope/|sb=urn:liberty:sb:2003-08
|pp=urn:liberty:id-sis-pp:2003-08|ispp=http://www.sun.com/identity/
liberty/pp|is=urn:liberty:is:2003-08

Specifies the namespace prefix mapping used when marshalling a JAXB content tree to a DOM tree. The syntax is prefix=namespace|prefix=namespace|...

JAXB Package List

Specifies JAXB package list used when constructing JAXBContext. Each package must be separated by a colon (:).

Liberty Identity Web Service Version

This property determines the Liberty ID-WSF framework when the framework cannot determine from the in-bound message or from the resource offering when OpenSSO is acting as the WSC. Values can be 1.0 or 1.1. The default is 1.1.

Liberty Interaction Service

The Liberty Interaction Service allows the user to interact during web services communication for any authorization. .

The Liberty Interaction Service is configurable through the OpenSSO Enterprise console at Configuration>Global>Liberty ID-WSF Interaction Service. See Liberty Interaction Service in Sun OpenSSO Enterprise 8.0 Administration Reference for attribute definitions.

Liberty ID-WSF Security Service

The Liberty ID-WSF Security Service is configurable through the OpenSSO Enterprise console at Configuration>Global>Liberty ID-WSF Interaction Service. See Liberty ID-WSF Security Service in Sun OpenSSO Enterprise 8.0 Administration Reference for attribute definitions.

Chapter 10 SAML 1.x Administration

Security Assertion Markup Language (SAML) is an open-standard protocol that uses a L framework to exchange security information between an authority and a trusted partner site. The security information concerns itself with a subject's authentication status, access authorization and attribute information. (A person identified by an email address is a subject as might be a printer.) A SAML authority (also referred to as the asserting party) is a platform or application that has been integrated with SAML API, allowing it to relay security information. For example, asserting that a subject has been authenticated into its system by passing the required attributes. Trusted partner sites receive the security information and rely on its authenticity.

SAML Attributes

All attributes associated with SAML1.x can be configured and defined in the OpenSSO Enterprise console. This section describes how to create and configure the SAML1.x service.


Note –

By default character escaping is enabled so that you can use the following special characters in SAML 1.x attributes in the OpenSSO Enterprise console:

To disable character escaping:

  1. In the OpenSSO Enterprise Console, go to Configuration>Servers and Sites>Default Server Setting>Advanced.

  2. Enter the com.sun.identity.saml.escapeattributevalue as the key, and false as the value.

  3. Restart the server.

If you wish to enable character escaping, change the value to true and restart the server.


The following SAML attributes can be configured for your implementation by clicking the Local Site Properties button:

Target Specifier

This attribute assigns a name to the destination site URL used in SAML redirects. The default is TARGET. Only sites configured in the Trusted Partners attribute can be specified as a TARGET.

Site Identifiers

For information about site identifiers and to see the procedure for configuring a site identifier, see the following section.

ProcedureTo Configure a Site Identifier

The Site Identifier defines any site hosted by the server on which OpenSSO Enterprise is installed. A default value and an automatically generated Site ID are defined for the host during installation. Multiple entries are possible. For example, load balancing or multiple instances of OpenSSO Enterprise sharing the same data store would all need to be defined. The starting point is the Site Identifiers attribute on the SAML screen under the Federation interface. Site IDs are defined in the Servers and Sites configuration screen. For more information, see Servers and Sites in Sun OpenSSO Enterprise 8.0 Administration Reference.

  1. Click New to add a new site identifier or click on the name of a configured site identifier to modify its profile.

    The Site Identifier attributes are displayed.

  2. Provide values for the Site Identifier attributes based on the following information:

    Instance ID

    The value of this property is protocol ://host: port.

    If configuring SAML for SSL (in both the source and destination site), ensure that the protocol defined here is https//.

    Site ID

    The site ID is an identifier generated for each site (although the value will be the same for multiple servers behind a load balancer). There is a class in the com.sun.identity.saml.common package that can be used to generate this identifier manually, if needed. Type the following at the command line:


    % java -classpath FM-classpath com.sun.identity.saml.common.SAMLSiteID 
    protocol://host:port
    
    Issuer Name

    The default value of this property is host :port, but it could be any URI.

  3. Click OK to complete the Site Identifier configuration.

  4. Click Save on the Local Site Properties page to complete the SAML configuration.

Trusted Partners

For information on trusted partners and to see the procedure for configuring a new Trusted Partner, see the following section.

ProcedureTrusted Partners: Selecting Partner Type and Profile

This attribute defines any trusted partner (remote to the server on which OpenSSO Enterprise is installed) that will be communicating with OpenSSO Enterprise.


Note –

The trusted partner site must have a prearranged trust relationship with one or more of the sites configured in the Site Identifiers attribute.


The first step in configuring a trusted partner is to determine the partner's role in the trust relationship. A trusted partner can be a source site (one that generates a single sign-on assertion) or a destination site (one that consumes a single sign-on assertion). For example, if the partner is the source site, this attribute is configured based on how it will send assertions. If the partner is the destination site, this attribute is configured based on the profile in which it will be receiving assertions. Following is the first part of the procedure for configuring a trusted partner. The starting point is the SAML screen under Federation.


Note –

To edit or duplicate the attributes of a trusted partner profile, click the appropriate button in the Actions column next to the configured trusted partner name.


  1. Select the role (Destination or Source) of the partner site you are configuring by checking the appropriate profile that will be used to communicate with it.

    You may choose Web Browser Artifact Profile or Web Browser Post Profile for either Destination, Source or both, or SOAP Query for Destination only. The choices made dictate which of the attributes in the following steps need to be configured.


    Note –

    Click Edit to change the role of the partner site if you are modifying an existing trusted partner.


  2. Click Next.

ProcedureTrusted Partners: Configuring Trusted Partner Attributes

Following is the second part of the procedure for configuring a trusted partner. Based on the roles selected in the first part, any of the sub-attributes listed in the following sections may need to be defined.


Note –

If you reached this page by clicking Edit or Duplicate on the SAML configuration screen under Federation, modify the trusted partner profile based on the steps below and click Save to change the values. Click Save on the SAML Profile page to complete the modification.


  1. Type in values for the Common Settings sub-attributes.

    Name

    Can be any string, such as an organization name.

    Source ID

    This is a 20 byte sequence (encoded using the Base64 format) that comes from the partner site. It is generally the same value as that used for the Site ID attribute when configuring the Site Identifiers attribute.

    Target

    This is the domain of the partner site (with or without a port number). If you want to contact a web page that is hosted in this domain, the redirect URL is picked up from the values defined in the Trusted Partner attribute.


    Note –

    If there are two defined entries for the same domain (one containing a port number and one without a port number), the entry with the port number takes precedence. For example, assume the following two trusted partner definitions: target=sun.com and target=sun.com:8080. If the principal is seeking http://machine.sun.com:8080/index.html, the second definition will be chosen.


    SAML URL

    The URL that points to the servlet that implements the Web Browser Artifact Profile.

    Site Attribute Mapper

    The class is used to return a list of attribute values defined as AttributeStatements elements in an Authentication Assertion. A site attribute mapper needs to be implemented from the PartnerSiteAttributeMapper interface.

    If no class is defined, no attributes will be included in the assertion.

    Name Identifier Mapper

    The class that defines how the subject of an assertion is related to an identity at the destination site. An account mapper needs to be implemented from the com.sun.identity.saml.plugins.PartnerAccountMapper interface. The default is com.sun.identity.saml.plugins.DefaultAccountMapper.

    If no class is defined, no attributes will be included in the assertion.

    Version

    The SAML version used (1.0 or 1.1) to send SAML requests. To change the version or protocol, click on the Local Site Properties button and change the Protocol and Assertion attributes as necessary.

    Signing Certificate Alias

    A certificate alias that is used to verify the signature in an assertion when it is signed by the partner and the certificate cannot be found in the KeyInfo portion of the signed assertion.

  2. Type in values for the Destination sub-attributes.

    Artifact: SAML URL

    The URL that points to the servlet that implements the Web Browser Artifact Profile.

    Post: Post URL

    The URL that points to the servlet that implements the Web Browser POST Profile.

    Host List

    A list of the IP addresses, the DNS host name, or the alias of the client authentication certificate used by the partner. This is configured for all hosts within the partner site that can send requests to this authority. This list helps to ensure that the requestor is indeed the intended receiver of the artifact. If the requester is defined in this list, the interaction will continue. If the requester’s information does not match any hosts defined in the host list, the request will be rejected.

  3. Type in values for the Source sub-attributes.

    Artifact: SOAP URL

    The URL to the SAML SOAP Receiver.

    Authentication Type

    Authentication types that can be used with SAML:

    • Specify None if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is not protected by HTTP basic authentication and/or SSL.

    • Specify Basic if the URL to the SAML SOAP receiver is accessed using HTTP, and the SAML SOAP receiver is protected by HTTP basic authentication.

    • Specify SSL if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is not protected by HTTP SSL.

    • Specify SSL with Basic if the URL to the SAML SOAP receiver is accessed using HTTPS, and the SAML SOAP receiver is not protected by BASIC AUTH WITH SSL.


    Note –

    If you are protecting the SAML SOAP receiver URL with HTTP basic authentication, you do so in the web container configuration and not in the OpenSSO Enterprise configuration. You do, however, supply the HTTP basic authentication user ID and password in the OpenSSO Enterprise configuration.


    This attribute is optional. If not specified, the default is NOAUTH. If BASICAUTH or SSLWITHBASICAUTH is specified, the Trusted Partners attribute is required and should be HTTPS.

    User

    When BASICAUTH is chosen as the Authentication Type, the value of this attribute defines the user identifier of the partner being used to protect the partner’s SOAP receiver.

    User's Password

    When BASICAUTH is chosen as the Authentication Type, the value of this attribute defines the password for the user identifier of the partner being used to protect the partner’s SOAP receiver.

    User's Password (reenter)

    Reenter the password defined previously.

  4. Type a value for the Post sub attribute.

    Issuer

    The creator of a generated assertion. The default syntax is hostname: port.

  5. Click Finish.

  6. Click Save on the SAML Profile page to complete the configuration.

Target URLs

If the Target URL received using either profile is listed as a value of this attribute, the received assertions will be sent to the Target URL using an HTTP FORM POST.


Note –

To edit or duplicate the attributes of a trusted partner profile, click the Local Site Properties button and click New in the Target URL table.


ProcedureTo Configure a Target URL

The following sub attributes can be defined (or modified) for each Target URL that will receive assertions using POST.

  1. Click New to add a new target URL.

    The Add New Post to Target URL page is displayed. You can also reach this page by selecting the Edit or Duplicate button of a defined Target URL.

  2. Type values for the attributes.

    Protocol

    Choose either http or https.

    Server Name

    The name of the server on which the TARGET URL resides, such as www.sun.com.

    Port

    This attribute contains the port number such as 58080.

    Path

    This attribute contains the URI such as /opensso/console.

  3. Click OK to complete the Target URL configuration.

  4. Click Save on the SAML Profile page to complete the SAML configuration.

Default Protocol Version

This attribute specifies the default SAML protocol version this entity uses to communicate with remote partners. Default value is 1.1.

Default Assertion Version

This attribute specifies the default SAML assertion version this entity uses to communicate with remote partners.

Remove Assertion

If enabled (true), the SAML entity will remove assertions from memory once they are used. Otherwise, all assertions remain in memory until expiration. It is enabled by default.

Assertion Timeout

This attribute specifies the number of seconds before a timeout occurs on an assertion. The default is 420.

Assertion Skew Factor for notBefore Time

This attribute is used to calculate the notBefore time of an assertion. For example, if IssueInstant is 2002-09024T21:39:49Z, and Assertion Skew Factor For notBefore Time is set to 300 seconds (180 is the default value), the notBefore attribute of the conditions element for the assertion would be 2002-09-24T21:34:49Z.


Note –

The total valid duration of an assertion is defined by the values set in both the Assertion Timeout and Assertion Skew Factor For notBefore Time attributes.


Artifact Timeout

This attribute specifies the period of time an assertion that is created for an artifact will be valid. The default is 400.

SAML Artifact Name

This attribute assigns a variable name to a SAML artifact. The artifact is bounded-size data that identifies an assertion and a source site. It is carried as part of a URL query string and conveyed by redirection to the destination site. The default name is SAMLart . Using the default SAMLart, the redirect query string could be http://host:port /deploy-URI/ SamlAwareServlet?TARGET=target-URL /&SAMLart=artifact123.

Sign SAML Assertion

This attribute specifies whether all SAML assertions will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.

Sign SAML Request

This attribute specifies whether all SAML requests will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.

Sign SAML Response

This attribute specifies whether all SAML responses will be digitally signed (XML DSIG) before being delivered. Selecting the check box enables this feature.


Note –

All SAML responses used by the Web Browser POST Profile will be digitally signed whether this option is enabled or not enabled.


Attribute Query

Defines the list of the Attribute Query Profile for X. 509 subjects only.

SAML Operations

This section contains procedures illustrating how to use the OpenSSO Enterprise SAML Service.

Setting Up SAML Single Sign-on

The following procedures explain how to configure and access instances of OpenSSO Enterprise for single sign-on using SAML 1.x assertions. Machine A (exampleA.com) is the source site which authenticates the user and creates the SAML authentication assertion. Machine B (exampleB.com) is the destination site which consumes the assertion and generates a SSOToken for the user.


Note –

If both machines are in the same domain, the cookie names must be different. You can change the cookie name by modifying the Coopkie Name property in Configuration>Servers and Sites>Security, located in the OpenSSO Enterprise console.


This section contains the following procedures:

ProcedureTo Set Up SAML Single Sign-on

This procedure assumes the following values:

Deployment URI 

opensso

Port 

58080 

Protocol 

http

  1. Write down or copy the value of the Site ID attribute from the destination site (machine B).

    1. Login to the console running at exampleB.com as the default administrator, amadmin.

    2. Click the Federation tab.

    3. Click the SAML button.

    4. Click the sole entry listed under Site Identifiers.

      This takes you to the Edit site identifier page.

    5. Write down or copy the value of the Site ID attribute.

    6. Click Cancel.

    7. Log out of this instance of OpenSSO Enterprise.

  2. Configure the source site (machine A) to trust the destination site (machine B) AND write down or copy the value of the Site ID attribute from the source site.

    1. Login to the console running at exampleA.com as the default administrator, amadmin.

    2. Click the Federation tab.

    3. Click New under Trusted Partners.

      This takes you to the Select trusted partner type and profile page.

    4. Check Artifact and Post under Destination and click Next.

      This takes you to the Add New Trusted Partner page.

    5. Set the values of the following attributes to configure machine B as a trusted partner of machine A:

      name 

      Type the name of the trusted partner. The name will be displayed in the trusted partner table. 

      Source ID 

      Type the Site ID copied from the destination site, machine B, in the previous step. 

      Target 

      The value of this attribute contains the host's domain or domain with port. Do not include the accompanying protocol. For example, exampleB.com and exampleB.com:58080 are valid but, http://exampleB.com:58080.

      SAML URL 

      http://exampleB.com:58080/opensso/SAMLAwareServlet

      HOST LIST 

      exampleB.com

      POST URL 

      http://exampleB.com:58080/opensso/SAMLPOSTProfileServlet

    6. Click Finish.

    7. Click Save.

    8. Click the sole entry listed under Site Identifiers.

      This takes you to the Edit site identifier page.

    9. Write down or copy the value of the Site ID attribute.

    10. Click Cancel to go to previous page.

    11. Log out of OpenSSO Enterprise.

  3. Configure the destination site (machine B) to trust the source site (machine A).

    1. Login to the OpenSSO Enterprise console running at exampleB.com as the default administrator, amadmin.

    2. Click the Federation tab.

    3. Click New under Trusted Partners.

      This takes you to the Select trusted partner type and profile page.

    4. Check Artifact and Post under Source and click Next.

      This takes you to the Add New Trusted Partner page.

    5. Set the values of the following attributes to configure machine A as a trusted partner of machine B:

      Name 

      Type the name of the trusted partner. This will appear in the Trusted Partners table. 

      Source ID 

      Type the Site ID you copied from the source site, machine A, in the previous step. 

      SOAP URL 

      http://exampleA.com:58080/opensso/SAMLSOAPReceiver

      Issuer 

      exampleA.com:58080


      Note –

      If machine B uses https, check SSL under Authentication Type. Be sure to modify the protocol in the other attributes as necessary.


    6. Click Finish.

    7. Click Save.

    8. Log out of OpenSSO Enterprise.

ProcedureTo Verify the SAML Single Sign-on Configurations

  1. Login to the OpenSSO Enterprise console running at exampleA.com as the default administrator, amadmin.

  2. To initialize single sign-on from machine A, do one of the following:

    • Access the following URL to use the SAML Artifact profile:

      http://exampleA.com:58080/opensso/SAMLAwareServlet?TARGET=exampleB.com_Target_URL

    • Access the following URL to use the SAML POST profile:

      http://exampleA.com:58080/opensso/SAMPOSTProfileServlet?TARGET=exampleB.com_Target_URL


      Note –

      XML signing must be enabled before running the SAML POST profile. .


    exampleB.com_Target_URL is any URL on the exampleB.com site to which the user will be redirected after a successful single sign-on. For testing purpose, this could be the login page as in TARGET=http://exampleB.com:58080/opensso/UI/Login. If the administrator successfully accesses the OpenSSO Enterprise console on the destination site without manual authentication, an SSOtoken has been created for the principal on the destination site and single sign-on has been properly established.