Sun OpenSSO Enterprise 8.0 Administration Guide

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:

All communications between WS-Federation components must be made over SSL.

ADFS does not perform an HTTP POST of a WS-Federation RequestSecurityTokenResponse (RSTR) to a non-HTTPS URL.
The ADFS environment can rely on DNS.
All servers must be time-synchronized. This is essential to proper token validation.
Token signing certificates must be created and imported for both ADFS and OpenSSO Enterprise endpoints. This process is automated in ADFS, but requires the use of the keytool command for OpenSSO Enterprise.
You have set up ADFS based on the instructions contained in theMicrosoft Active Directory Federation Services (ADFS) Step-by-Step Guide.

Make sure that Single Sign-On is configured for the ADFS from adfsaccount to adfsweb through the adfsresource.
You have created a new user in the adatum.com Active Directory domain. The login name must be the same as the UID you created in OpenSSO. To do so, go to Start>Administrative Tools>Active Directory Users and Computers. Right click Users and click on New>User.

Proceed to the following sections to see the configuration steps.

To Configure OpenSSO Enterprise as a Service Provider

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

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

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

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

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

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>

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>

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).

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

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.

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.

To Configure OpenSSO Enterprise as an Identity Provider

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

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.

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.

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

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

Copy cert.der to the adfsresource machine.

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.

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.

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

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>

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).

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

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.

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

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.