Sun OpenSSO Enterprise 8.0 Developer's Guide

Using SAML v2 for Virtual Federation Proxy

Secure Attribute Exchange (also referred to as Virtual Federation Proxy) provides a mechanism for one application to communicate identity information to a second application in a different domain. In essence, Virtual Federation Proxy (VFP) 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. A VFP interaction allows:

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

Note –

The scope of the implementation of VFP is currently limited to SAML v2 based single sign-on. It 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 client API (which includes Java and .NET interfaces) run independently of OpenSSO Enterprise and are used to enable existing applications, allowing them to handle SAML v2 interactions.

VFP functionality can be found in three places:

deployable-war/opensso.war on the OpenSSO Enterprise side.
libraries/dll/openssosae.dll for client applications using the OpenSSO Enterprise NET API.
libraries/jars/openssoclientsdk.jar for client applications using the OpenSSO Enterprise Java API.

The following sections contain more information on Virtual Federation Proxy.

How Virtual Federation Proxy Works

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

Figure 8–1 A Secure Attribute Exchange Using SAML v2

Illustration of a secure attribute exchange components
and interactions

The following graphic illustrates the process behind a secure attribute exchange interaction. Details are below the illustration.

A user authenticates.

This may be done by the identity provider application or it may be delegated to an authentication authority.
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.
The identity provider application assembles the appropriate user attributes (authentication and user profile data), encodes and signs it using the API, and posts the secure data to the local instance of OpenSSO Enterprise.

The com.sun.identity.sae.api.SecureAttrs class is provided by OpenSSO Enterprise and carries the user identifier and the service provider destination.
The SAE authentication module on the instance of OpenSSO Enterprise local to the identity provider verifies the authenticity of the attributes also using the SAE API, and initiates the appropriate SAML v2 single sign-on protocol to send the attributes to the instance of OpenSSO Enterprise local to the service provider being accessed.
The instance of OpenSSO Enterprise 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 Enterprise to verify the authenticity of the attributes.
The service provider application provides or denies the service to the user based on the attributes received.

Note –

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

Use Cases

The following sections contain information on applicable use cases for SAE.

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 Enterprise asserting the identity of the user. OpenSSO Enterprise verifies the authenticity of the message and establishes a session for the authenticated user. You can use VFP to transfer the user's authentication information to the local instance of OpenSSO Enterprise 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 Enterprise 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 Enterprise 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 Enterprise 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 SAML v2 single sign-on URL as a part of the request. The identity provider instance of OpenSSO Enterprise then initiates SAML v2 single sign-on with the instance of OpenSSO Enterprise at the service provider. The service provider's instance of OpenSSO Enterprise then verifies the SAML v2 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 Enterprise 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 executes SAML v2 single log out by invoking a provided OpenSSO Enterprise URL. The identity provider terminates the session on both provider instances of OpenSSO Enterprise.

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 Enterprise acting as the identity provider. In turn, this instance will execute SAML v2 single logout based on the current session.

Securing Virtual Federation Proxy

VFP provides two ways to secure identity attributes between an instance of OpenSSO Enterprise and an application:

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 Enterprise keystore. The private key must be stored in a protected keystore (such as a Hardware Security Module) for access by the identity provider application. On the service provider side, the private key must be added to the OpenSSO Enterprise 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 Enterprise instance is independent, different applications involved can use different security methods.

Preparing to Use Virtual Federation Proxy

Before configuring and using the VFP, 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 VFP.

Note –

Because OpenSSO Enterprise currently uses SAML v2 for its implementation of SAE, you should familiarize yourself with SAML v2 concepts by running the useCaseDemo SAML v2 sample included with OpenSSO Enterprise.

Establish trust between the application(s) and the instance of OpenSSO Enterprise 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 Enterprise. 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.

Tip –
Multiple applications can share the same application name only if they also share the same shared secret or key.
Establish trust between the application(s) and the instance of OpenSSO Enterprise 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 Enterprise 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 SAML v2 service provider was configured as an OpenSSO Enterprise service provider. You can find these keys in the service provider's metadata.

Tip –
Multiple applications can share the same application name only if they also share the same shared secret or key.
OPTIONAL: The following steps are specific to using SAML v2 and auto-federation.
1. Decide which identity attributes you want transferred as part of the SAML v2 single sign-on interaction.
  
  We choose the branch and mail attributes.
  
  Caution –
  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 SAML v2 assertion or it can be configured statically at the service provider.
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 for Virtual Federation Proxy

Configuring for VFP communication involves modifications on two different installations of OpenSSO Enterprise: 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 the OpenSSO Enterprise bits and deployed the application to a supported web container. You should also be ready to configure a SAML v2 provider by executing the included SAML v2 sample, by running one of the Common Tasks using the Administration Console, or by importing provider metadata using the Administration Console or ssoadm command line interface. The following procedures contain more information.

Configure the Instance of OpenSSO Enterprise Local to the Identity Provider

The following procedure illustrates how to configure the instance of OpenSSO Enterprise local to the identity provider.

Update the identity provider standard metadata.
- If you have existing identity provider standard metadata, export it using ssoadm and make your modifications. After updating, delete the original file and reload the modified metadata using ssoadm.
- If you have not yet configured identity provider standard metadata, use ssoadm to generate an identity provider metadata template. After updating the template, import the modified metadata also using ssoadm.
Set up the keystore.

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.
Update the identity provider configuration.
1. Setup the application's security configuration as symmetric or asymmetric by defining the Per Application Security Configuration attribute under the Advanced tab of the identity provider configuration.
  
  Note –
  Use ampassword to encrypt the shared secret used for a symmetric configuration.
2. OPTIONAL: Modify the IDP URL attribute (if you want to use an alternative or custom SAE landing URL) under the local identity provider's Advanced tab with a value specific to your identity provider instance of OpenSSO Enterprise.

Configure the Instance of OpenSSO Enterprise Local to the Service Provider

The following procedure shows how to configure the instance of OpenSSO Enterprise local to the service provider.

Update the service provider standard metadata.
- If you have existing service provider standard metadata, export it using ssoadm and make your modifications. After updating, delete the original file and reload the modified metadata also using ssoadm.
- If you have not yet configured service provider standard metadata, use ssoadm to generate a service provider metadata template. After updating the template, import the modified metadata also using ssoadm.
Set up the keystore.

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.
Update the service provider extended metadata.
1. Enable auto-federation and specify the attribute that will identify the user's identity under the Assertion Processing tab of the service provider configuration.
2. Specify attributes from the incoming SAML v2 assertion to be used to populate the local OpenSSO Enterprise session under the Assertion Processing tab of the service provider configuration.
3. Setup the application's security configuration as symmetric or asymmetric by defining the Per Application Security Configuration attribute under the Advanced tab of the service provider configuration.
  
  Note –
  Use ampassword to encrypt the shared secret used for a symmetric configuration.
4. OPTIONAL: Modify the SP URL attribute ( if you want to use an alternative or custom SAE landing URL) under the local service provider's Advanced tab with a value specific to your identity provider instance of OpenSSO Enterprise.
5. Configure the value of the SP Logout URL attribute. The value of this attribute is the URL that will receive global logout requests
  
  Note –
  The configured URL must have a defined symmetric or asymmetric CryptoType with corresponding shared secret and certificates established.

Configure the Instance of OpenSSO Enterprise Local to the Identity Provider for the Remote Service Provider

Both the standard and extended metadata retrieved from the remote service provider will be imported to the instance of OpenSSO Enterprise local to the identity provider.

Get both the remote service provider standard metadata and the remote service provider extended metadata used in Configure the Instance of OpenSSO Local to the Service Provider.
Modify the remote service provider extended metadata as follows:
- Remove all shared secrets defined in the actual provider metadata file.
- Set the hosted attribute to 0 (false) as in <EntityConfig .. hosted="0" ....>. This defines the entity as remote and can only be done using the actual provider metadata file.
- Remove the value for the SP Logout URL attribute under the Advanced tab of the service provider configuration.
- Add the following attribute and values to the Attribute Map attribute under the Assertion Processing tab.
```
mail=mail
branch=branch
```
Import both metadata files to the instance of OpenSSO Enterprise local to the identity provider.

Use ssoadm the command line interface.

Configure the Instance of OpenSSO Enterprise Local to the Service Provider for the Remote Identity Provider

If the SAMLv2 sample has been executed on the instance of OpenSSO Enterprise local to the service provider, nothing else needs to be done. If metadata has been manually configured on the instance of OpenSSO Enterprise local to the service provider, do the following procedure.

Get the remote identity provider metadata for import to the instance of OpenSSO Enterprise local to the service provider.

The standard metadata is the same as the one used in Configure the Instance of OpenSSO Enterprise Local to the Identity Provider.
Import the standard metadata to the instance of OpenSSO Enterprise local to the service provider using ssoadm.
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 Enterprise at the service provider and the instance at the identity provider must be restarted.

Using the Secure Attribute Exchange Sample

OpenSSO Enterprise 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 SAML v2, are used. If there are no actual users on either the identity provider side or the service provider side, you need to use the following procedure to change the authentication framework to ignore user profiles for these two features to work correctly.

Login to OpenSSO Enterprise administration console as administrator.

By default, this is amadmin.
Click the name of the realm you are modifying.
Click the Authentication tab.
Click Advanced Properties.
Select the Ignore Profile radio button under User Profile.
Click Save.
Log out of the console.