Secure Attribute Exchange (SAE) is a new OpenSSO feature that provides a mechanism for one application to communicate identity information to a second application in a different domain. In essence, SAE provides a secure gateway that enables legacy applications to communicate user attributes used for authentication without having to deal specifically with federation protocols and processing. An SAE interaction allows:

• Identity provider applications to push user authentication, profile and transaction information to a local instance of OpenSSO. OpenSSO then passes the data to a remote instance of OpenSSO at the service provider using federation protocols.
• Service provider applications to consume the received information.

NOTE: The scope of the implementation of SAE is currently limited to SAMLv2 based single sign-on.

SAE uses the SAMLv2-based protocols (based on the HTTP GET and POST methods as well as URL redirects) to transfer identity data between the communicating entities. The SAE client API (which includes Java and .NET interfaces) runs independently of OpenSSO and are used to enable existing applications, allowing them to handle SAMLv2 interactions. The components of a secure attribute exchange are listed and illustrated below.

• Legacy identity provider application (blue IDP)
• Service provider application (blue SP)
• Independent instances of OpenSSO on both the identity provider and the service provider sides (green)
• A user agent

More information is in the following sections:

• How Secure Attribute Exchange Works
• Securing the Attribute Exchange
• Use Cases
• Preparing to Use Secure Attribute Exchange
• Configuration
• Using the Secure Attribute Exchange Sample

How Secure Attribute Exchange Works

This image illustrates the process behind a secure attribute exchange. Details follow.

1. A user authenticates.
   This may be done by the identity provider application or it may be delegated to an authentication authority.
2. The authenticated user uses the identity provider application and, at some point, accesses a link representing a service provided by an application in a different domain.
3. The identity provider application assembles the appropriate user attributes (authentication and user profile data), encodes and signs it using the com.sun.identity.sae.api.SecureAttrs class, and posts the secure data to the local instance of OpenSSO.
   This API is provided by OpenSSO and carries the user identifier and the service provider destination.
4. The SAE authentication module on the instance of OpenSSO local to the identity provider verifies the authenticity of the attributes also using the SAE API, and initiates the appropriate SAMLv2 single sign-on protocol to send the attributes to the instance of OpenSSO local to the service provider being accessed.
5. The instance of OpenSSO local to the service provider secures the user attributes, and sends them to the service provider application.
   The service provider application uses interfaces supplied by OpenSSO to verify the authenticity of the attributes.

6. The service provider application provides the service to the user based on the attributes previously received.

NOTE: It is not mandatory for the service provider end of the process to implement SAE. Since the attributes are carried in a SAML assertion, the service provider could choose another way to invoke the requested application. For example, the service provider can use standard SAMLv2 protocols to invoke a SAMLv2-compliant service provider that does not implement SAE. The RelayState element as defined in the SAMLv2 specification can be used to redirect to the local service provider application.

Securing the Attribute Exchange

• Symmetric involves the use of a shared secret key known only to the participants in the communication. The key is agreed upon beforehand and will be used to encrypt and decrypt the message.
• Asymmetric uses two separate keys for encryption and the corresponding decryption - one public and one private. The information is encrypted with a public key known to all and decrypted, by the recipient only, using a private key to which no one else has access. This process is known as a public key infrastructure. On the identity provider side, the public key must be added to the OpenSSO keystore. The private key must be stored in a protected keystore such as a Hardware Security Module (HSM) for access by the identity provider application. On the service provider side, the private key must be added to the OpenSSO keystore, and the public key stored in a keystore, local to the service provider application.

Both mechanisms result in an encrypted string (referred to as a cryptostring) generated for the asserted attributes. The symmetric cryptostring is a SHA-1 hash of the attributes. The asymmetric cryptostring is a digital signature of the attributes.

NOTE: As each pairing of application to OpenSSO instance is independent, different applications involved can use different security methods.

Use Cases

The following use cases are applicable to SAE:

• Authentication at Identity Provider
• Secure Attribute Exchange at Identity Provider
• Secure Attribute Exchange at Identity Provider
• Global Single Logout

Authentication at Identity Provider

When a user is already authenticated in an enterprise, the legacy identity provider application sends a secure HTTP GET/POST message to OpenSSO asserting the identity of the user. OpenSSO verifies the authenticity of the message and establishes a session for the authenticated user. You can use SAE to transfer the user's authentication information to the local instance of OpenSSO in order to create a session.

Secure Attribute Exchange at Identity Provider

When a user is already authenticated by, and attempts access to, a legacy identity provider application, the legacy application sends a secure HTTP POST message to the local instance of OpenSSO asserting the user's identity, and containing a set of attribute/value pairs related to the user (for example, data from the persistent store representing certain transactional states in the application). OpenSSO verifies the authenticity of the message, establishes a session for the authenticated user, and populates the session with the user attributes.

Secure Attribute Exchange at Service Provider

When a user is already authenticated by the instance of OpenSSO at the identity provider and invokes an identity provider application that calls for redirection to a service provider, the identity provider invokes one of the previous use cases and encodes a SAMLv2 single sign-on URL as a part of the request. The identity provider instance of OpenSSO then initiates SAMLv2 single sign-on with the instance of OpenSSO at the service provider. The service provider's instance of OpenSSO then verifies the SAMLv2 assertion and included attributes, and redirects to the service provider application, securely transferring the user attributes via a secure HTTP POST message. The service provider application consumes the attributes, establishes a session, and offers the service to the user.

Global Single Logout

When a user is already authenticated and has established, for example, single sign-on with the instance of OpenSSO at the service provider, the user might click on a Global Logout link. The identity provider will then invalidate its local session (if created) and trigger SAMLv2 single log out by invoking a provided OpenSSO URL. The OpenSSO identity provider executes the SAMLv2 single log out, terminating the session on both provider instances of OpenSSO.

NOTE: An identity provider side application can initiate single logout by sending sun.cmd=logout attributes via an SAE interaction to a local instance of OpenSSO acting as the identity provider. In turn, this instance will execute SAMLv2 single logout based on the current session.

Preparing to Use Secure Attribute Exchange

Before configuring and using the SAE, you will need to make some decisions regarding security, applicable keys, and applications. This section lists what you will need to do before configuring for SAE.

NOTE: Because OpenSSO currently uses SAMLv2 for its implmentation of SAE, you should familiarize yourself with SAMLv2 concepts by running the useCaseDemo SAMLv2 sample included with OpenSSO.

1. Establish trust between the application(s) and the instance of OpenSSO on the identity provider side

   Decide the application(s) on the identity provider side that will use SAE to push identity attributes to the local instance of OpenSSO. You will need values for the following:

   Application Name	This is used for easy identification and can be any string. Use of the application's URL is recommended.
   CryptoType	Can be Symmetric or Asymmetric.
   Shared Secret or Private and Public Keys	You need the shared secret if using Symmetric, and the private and public keys if using Asymmetric.

   NOTE: Multiple applications can share the same application name only if they also share the same shared secret or key.

2. Establish trust between the application(s) and the instance of OpenSSO on the service provider side

   Decide the applications on the service provider side that will receive the identity attributes from the local instance of OpenSSO using SAE. You will need the following:

   Application Name	This is used for easy identification and can be any string. Use of the application's URL is recommended because the default implementation of the SAE on the service provider side uses a prefix string match from the requested application URL to determine the parameters used to secure the communication.
   CryptoType	Can be Symmetric or Asymmetric.
   Shared Secret or Private and Public Keys	You need the shared secret if using Symmetric, and the private and public keys if using Asymmetric. If Asymmetric is chosen, use the same keys defined when the SAMLv2 service provider was configured as an OpenSSO service provider. You can find these keys in the service provider's metadata.

   NOTE: Multiple applications can share the same application name only if they also share the same shared secret or key.

3. OPTIONAL: The following steps are specific to using SAMLv2 and auto-federation.

   1. Decide which identity attributes you want transferred as part of the SAMLv2 single sign-on interaction.

      We choose the branch and mail attributes.

      ---

      NOTE: If any attribute needs to be supplied from a local user data store, you must first populate the data store.

      ---

   2. Decide which attribute will be used to identify the user on the service provider side.

      In this instance, we choose the branch attribute for user identification.

      ---

      NOTE: The attribute may be one transferred in the SAMLv2 assertion or it can be configured statically at the service provider.

      ---

4. Decide which URL on the service provider side will be responsible for handling logout requests from the identity provider.

   The URL will be responsible for terminating the local session state. Only one is allowed per logical service provider configured on the service provider side.

Configuring Secure Attribute Exchange

Configuring for Secure Attribute Exchange communication involves modifications on two different OpenSSO installations: one that is local to the identity provider and one that is local to the service provider. The following sections assume that you have downloaded and deployed the OpenSSO WAR to a supported web container, and that you are ready to configure a SAMLv2 provider either by executing the included SAMLv2 sample, by running one of the Common Tasks using the Administration Console, by importing metadata using the Administration Console, or by using the famadm command line interface. SAE functionality is found in three places:

• deployable-war/opensso.war - for FAM8 side
• libraries/dll/openssosae.dll - for client application using .NET API
• libraries/jars/openssoclientsdk.jar - for client application using Java API

• Configure the Instance of OpenSSO Local to the Identity Provider

  1. Update the identity provider standard metadata.
     • If you have existing identity provider standard metadata, export it using famadm export-entity and make your modifications. After updating, delete the original file using famadm delete-entity and re-load the modified metadata using famadm import-entity.
     • If you have not yet configured identity provider standard metadata, use famadm to generate an identity provider metadata template. After updating the template, import the modified metadata using famadm import-entity.
  2. Set up the keystore(s).

     If using the asymmetric cryptotype, add the public and private keys to the application's keystore. Additionally, populate the identity provider's keystore with the application's public key.

  3. Update the identity provider extended metadata.
     1. Setup the application's security configuration as symmetric or asymmetric.
        • Symmetric : Encrypt each shared secret using ampassword.
          famtools/bin/ampassword -e secretfile
          For example, if ampassword returns a value of AQICHgRg..., populate the saeAppSecretList attribute in the extended metadata with this output as in:

          <Attribute name="saeAppSecretList">
             <Value>url=application_name|type=symmetric|secret=AQICHgRg...</Value>
          </Attribute>
          

        • Asymmetric : Obtain each application's public key and add it to the OpenSSO keystore.
          For example, if the public key alias is testcert, populate the saeAppSecretList attribute.
          

          <Attribute name="saeAppSecretList">
             <Value>url=application_name|type=asymmetric|pubkeyalias=testcert</Value>
          </Attribute>
          

     2. OPTIONAL: Modify the saeIDPUrl attribute.
        This attribute is populated with a value specific to your identity provider instance of OpenSSO. It can be changed if you want to use an alternatve or custom SAE landing URL. Modify the value of the saeIDPUrl attribute. For example:

        <Attribute name="saeIDPUrl">
           <Value>http://host:port/idp/idpsaehandler</Value>
        </Attribute>
        

• Configure the Instance of OpenSSO Local to the Service Provider

  1. Update the service provider standard metadata.
     • If you have existing service provider standard metadata, export it using famadm export-entity and make your modifications. After updating, delete the original file using famadm delete-entity and re-load the modified metadata using famadm import-entity.
     • If you have not yet configured service provider standard metadata, use famadm to generate a service provider metadata template. After updating the template, import the modified metadata using famadm import-entity.
  2. Set up the keystore.
     If using the asymmetric cryptotype, add the public and private keys for the service provider application to the OpenSSO keystore. Additionally, populate the application's keystore with the service provider's public key.
  3. Update the service provider extended metadata.
     • Turn on auto-federation and specify the attribute that will identify the user's identity.

       <Attribute name="autofedEnabled">
          <Value>true</Value>
       </Attribute>
       
       <Attribute name="autofedAttribute">
          <Value>branch</Value>
       </Attribute>
       

     • Specify attributes from the incoming SAMLv2 assertion to be used to populate the local OpenSSO session.

       <Attribute name="attributeMap">
          <Value>mail=mail</Value>
          <Value>branch=branch</Value>
       </Attribute>
       

     • Setup the application's security configuration as symmetric or asymmetric.
       • Symmetric : Encrypt each shared secret using ampassword.
         famtools/bin/ampassword -i staging_directory -e clearpassword
         For example, if ampassword returns a value of AQICl..., populate the saeAppSecretList attribute in the extended metadata with this output as in:

         <Attribute name="saeAppSecretList">
            <Value>url=application_name|type=symmetric|secret=AQICl...</Value>
         </Attribute>
         

       • Asymmetric : Obtain each application's public key and add it to the OpenSSO keystore.
         For example, if the public key alias is testcert, populate the saeAppSecretList attribute.

         <Attribute name="saeAppSecretList">
            <Value>url=application_name|type=asymmetric|pubkeyalias=testcert</Value>
         </Attribute>
         

     • OPTIONAL: Modify the value for the saeSPUrl attribute.
       This attribute is populated with a value specific to your service provider instance of OpenSSO. It can be changed if you want to use an alternatve or custom SAE landing URL. For example:

       <Attribute name="saeSPUrl">
          <Value>http://www.sp1.com:9080/sp/spsaehandler</Value>
       </Attribute>
       

     • Configure the value of the saeSPLogoutURL attribute.
       The value of this attribute is the URL that will receive global logout requests. For example:

       <Attribute name="saeSPLogoutURL">
          <Value>http://www.sp1.com:9080/sp/samples/saml2/sae/saeIDPApp.jsp</Value>
       </Attribute>
       

       ---

       NOTE: The configured URL must have a defined CryptoType (symmetric or asymmetric) and corresponding shared secret and certificates established.

       ---

• Configure the Instance of OpenSSO Local to the Identity Provider for the Remote Service Provider
  1. Get the remote service provider metadata for import to the instance of OpenSSO local to the identity provider.
     • The standard metadata is the same as the one used in Configure the Instance of OpenSSO Local to the Service Provider.
     • The extended metadata used in Configure the Instance of OpenSSO Local to the Service Provider must be changed by the service provider before giving it to the identity provider as follows:
       1. Remove all shared secrets
       2. Set the hosted attribute to 0 (false)
          

          <EntityConfig .. hosted="0" ....>
          

       3. Remove the value for the saeSPLogoutURL attribute.

       4. Add the following attribute:

          <Attribute name="attributeMap">
             <Value>mail=mail</Value>
             <Value>branch=branch</Value>
          </Attribute>
          

  2. Import both metadata files to the instance of OpenSSO local to the identity provider using famadm.
• Configure the Instance of OpenSSO Local to the Service Provider for the Remote Identity Provider
  If the SAMLv2 sample has been executed on the instance of OpenSSO local to the service provider, nothing else needs to be done. If metadata has been manually configured on the instance of OpenSSO local to the service provider, do the following:
  1. Get the remote identity provider metadata for import to the instance of OpenSSO local to the service provider.
     The standard metadata is the same as the one used in Configure the Instance of OpenSSO Local to the Identity Provider.
  2. Import the standard metadata to the instance of OpenSSO local to the service provider using famadm.
  3. Add the identity provider to the service provider's configured circle of trust.
  NOTE: If using a flat file for a datastore, both the instance of OpenSSO at the service provider and the instance at the identity provider must be restarted.

Using the Secure Attribute Exchange Sample

OpenSSO includes a sample that can be run for testing your configurations. It is located in container_context_root/opensso/samples/saml2/sae. In the sample, auto-federation and transient name identifier, two features of SAMLv2, are used.

1. Login to OpenSSO administration console as administrator.
   By default, this is amadmin.
2. Click the name of the realm you are modifying.
3. Click the Authentication tab.
4. Click Advanced Properties.
5. Select the Ignore Profile radio button under User Profile.
6. Click Save.
7. Log out of the console.