Getting Started With OpenSSO Express Build 7

If you have not previously installed OpenSSO Enterprise, here are the basic steps to follow:

1. If necessary, install, configure, and start one of the Web Containers Supported For OpenSSO Enterprise 8.0.
2. Download and unzip the file opensso_express_20090410.zip from one of the following sites:
   • OpenSSO project: https://opensso.dev.java.net/public/use/index.html
   • Sun: http://www.sun.com/software/products/opensso_enterprise
3. Deploy the opensso.war file to the web container, using the web container administration console or deployment command. Or, if supported by the web container, simply copy the WAR file to the container's autodeploy directory.
4. Configure OpenSSO Enterprise using either the GUI Configurator or the command-line Configurator.
   To launch the GUI Configurator, enter the following URL in your browser: protocol://host.domain:port/deploy_uri. For example: [https://openssohost.example.com:8080/opensso|http://openssohost.example.com:8080/opensso]
5. Perform any additional configuration using the either Administration Console or the new ssoadm command-line utility.
6. To download a version 3.0 policy agent, see https://opensso.dev.java.net/public/use/index.html.

Hardware and Software Requirements For OpenSSO Express Build 7

OpenSSO Express Build 7 supports all web containers supported in Sun OpenSSO Enterprise 8.0.  Additionally, the following web containers are now supported: in Express Build 7:

• IBM WebSphere Application Server 7.0
  See Deploying IBM WebSphere Application Server 7.0 as the OpenSSO Web Container for more information.
• Oracle WebLogic Server 10g Release 3 (10.3)
• GlassFish Prelude 3

All other hardware and software requirements are identical to the hardware and software requirements documented in the Sun OpenSSO Enterprise 8 Release Notes.

OpenSSO Enterprise 8.0 Documentation

The OpenSSO Enterprise 8.0 documentation is available on the following site:

OpenSSO Enterprise 8.0 Documentation Center

Check this site periodically to view the most recent documentation.

What's New in OpenSSO Express Build 7

OpenSSO Express Build 7 includes features such as access management, federation management, and web services security that are found in earlier releases of Sun OpenSSO. OpenSSO Enterprise also includes the new features described in this section.

Using OpenDS as a User Data Store

You can use OpenDS to store user profiles, authentication data, and policies. For more information see Using OpenDS as a User Data Store.

Integrating Google Apps with OpenSSO

If you have a Premier Edition Google Apps account, you can enable access to Google web applications such as Gmail, Google Calendar, Google Docs, and Google Video, to name just a few, to users in your enterpise domain. For more information, see Integrating Google Apps with OpenSSO.

Simplified OpenSSO WAR File Creation

The ability to create a specialized WAR file was present in OpenSSO Enterprise 8.0. In OpenSSO Express Build 7,the process has been simplified using the createwar.sh/createwar.bat script. For more information, see Creating a Specialized OpenSSO WAR.

Enabling XML Signing and Encprytion in a Fedlet

See Enabling XML Signing and Encryption in a Fedlet.

Using the Centralized SAML2 Error Conditions Page

OpenSSO Express Build 7 provides a single page where you can view all SAML2 error conditions.  This is useful when you are troubleshooting SAML2 configuration.  For more information, see Centralized SAMLv2 Error Processing.

About SAE Data Encryption Support

OpenSSO Express Build 7 supports Secure Attributes Exchange (SAE) data encryption.  SAE is also known as Virtual Federation.  For more information, see Encrypting Data in a Secure Attribute Exchange.

Support for New Web Container Versions

OpenSSO Express Build 7 supports all web containers supported in OpenSSO Enterprise 8.0.  Additionally, the following web containers are also supported:

• IBM WebSphere Application Server 7.0
  See Deploying IBM WebSphere Application Server 7.0 as the OpenSSO Web Container for more information.
• Oracle WebLogic Server 10g Release 3 (10.3)
• GlassFish Prelude 3

New Policy Agent Features

For the new features in version 3.0 policy agents, see one of these guides:

• Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents
  or
• Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents

Enchancements to OpenSSO 8.0 Functionality

• 4112: New property prevents unnecessary service polling requests from policy agents
• 4322: New script simplifies creation of OpenSSO specialized WAR files
• 2680: exportmetadata.jsp supports signing of exported metadata
• 3468: Fedlet supports XML signing and decryption of encrypted elements
• 3749: SP entity identifier (SPEntityID) is available to all authentication modules on IDP
• 4572: Centralized page shows all SAML2 error conditions
• 4574: SAE API can encrypt data being passed through the gateway
• 4087: CRL and OSCP checking support JSS-based logic
• 4251: Redirect callback support is added for Distributed Authentication Server UI
• 4371: CDCServlet removes the JavaScript enabled dependency for user's browser
• 3913: Policy agents send token other than the IP address in cookie hijacking mode
• 4247: New property allows policy agent sessions to time out
• 4008: New authentication module added for WSS user name token password digest
• 4394: Web services provider (WSP) caches user token nonce
• 4192: Policy Agent configuration key and value pair information now displayed together on one page
• 4286: After upgrading from JES4, in co-existence mode, amadmin authenticates to configuration data store

4112: New property prevents unnecessary service polling requests from policy agents

The new com.iplanet.am.client.appssotoken.refreshtime property prevents policy agents in polling mode from sending unnecessary session service requests to the OpenSSO server. The default value is 3 minutes. Previously, these session service requests could cause unnecessary traffic between the agent and the OpenSSO server as well as create an extra load on OpenSSO server.

4322: New script simplifies creation of OpenSSO specialized WAR files

The new createwar script simplifies the creation of specialized OpenSSO WAR files, including a Console only WAR, Distributed Authentication server UI WAR, OpenSSO server only WAR, and an IDP Discovery WAR. For more information, see Creating a Specialized OpenSSO WAR.

2680: exportmetadata.jsp supports signing of exported metadata

exportmetadata.jsp, the JavaServer Page used for exporting SAMLv2 metadata, now supports signing of the exported metadata.

3468: Fedlet supports XML signing and decryption of encrypted elements

The OpenSSO Fedlet now supports XML signing and decryption of encrypted Assertion, NameID, and Attribute elements.
See Enabling XML Signing and Encryption in a Fedlet.

3749: SP entity identifier (SPEntityID) is available to all authentication modules on IDP

A service provider's (SP) entity identifier (SPEntityID) is now readily available to all authentication modules on the identity provider (IDP) side, allowing the identity provider to take specific action depending on the service provider's requesting authentication.

4572: Centralized page shows all SAML2 error conditions

See Centralized SAMLv2 Error Processing

4574: SAE API can encrypt data being passed through the gateway

The Secure Attribute Exchange API can now be used to encrypt the data being passed through the gateway. See Encrypting Data in a Secure Attribute Exchange

4087: CRL and OSCP checking support JSS-based logic

Certificate Revocation List (CRL) and Online Certificate Status Protocol (OCSP) checking now support the Network Security Services for Java (JSS) library, enabling FIPS mode on the web container Sun Java Web Server 7.0 release update 3 or later.

4251: Redirect callback support is added for Distributed Authentication Server UI

Redirect callback support (RedirectCallback), which is used to redirect users to an external website as part of the authentication process, now works when the login is through a Distributed Authentication Server UI.

4371: CDCServlet removes the JavaScript enabled dependency for user's browser

If cross-domain single sign-on (CDSSO) is enabled for a policy agent, the CDCServlet can now redirect assertions (CDCRedirectServlet) for the agent, even if JavaScript is disabled for the user's browser.

3913: Policy agents send token other than the IP address in cookie hijacking mode

Previously, in cookie hijacking mode, policy agents sent the IP address of the server where they were installed to the OpenSSO server. Now, the policy agent first sends the application SSO token. If the agent cannot obtain the application SSO token, the agent then sends the IP address to the OpenSSO server.

If strict DN checking is required for a deployment, OpenSSO server includes the new
iplanet-am-session-dnrestrictiononly property.

The default value is false. If this property is set to true, the OpenSSO server performs strict DN checking. If the agent sends an IP address, the OpenSSO server considers the IP address to be an error.

To set iplanet-am-session-dnrestrictiononly for strict DN checking:

1. Add the property with a value of true using either the OpenSSO Admin Console or the ssoadm utility.
2. Restart the OpenSSO server web container for the DN checking to take effect.

4247: New property allows policy agent sessions to time out

The new com.iplanet.am.session.agentsessionidletime property sets the maximum idle timeout in minutes for policy agent sessions. The minimum value is 30 minutes. A value greater than 0 and less than 30 will be reset to 30.
The default is 0, which means that the policy agent sessions never time out.

To set com.iplanet.am.session.agentsessionidletime:

1. Add the property with the maximum idle timeout value using either the OpenSSO Admin Console or the ssoadm utility.
2. Restart the OpenSSO server web container for the idle timeout value to take effect.

4008: New authentication module added for WSS user name token password digest

OpenSSO Epress Build 7 includes a new authentication module for the UserNameToken profile. This new module enables authentication between a web services client (WSC) and a web services provider (WSP), and handles both UserNameToken password digest and UserNameToken-Plain text password tokens. After you configure web services security (WSS) in the OpenSSO Admin Console, create an authentication chain as wssauthchain with the required authentication module as WSSAuthModule.

4394: Web services provider (WSP) caches user token nonce

A WSP now caches the user token nonce to prevent replay attacks for validating the name token profiles. The WSP uses the in-memory cache that stores the cache indexed by the timestamp. The WSP also includes an interface for the persistent store of the state of the cache for failover situation.

4192: Policy Agent configuration key and value pair information now displayed together on one page

In the OpenSSO administration console, go to Realms > Agents > Edit Agent, and then click Dump. A new page opens with configuration key and value pair information displayed.

4286: After upgrading from JES4, in co-existence mode, amadmin authenticates to configuration data store

A security fix (Issue 3924) prevents amadmin from logging in to any authentication module other than the DataStore and Application authentication modules.
This new fix (Issue 4286) removes this restriction, but at the same time forces any internal user such as amadmin  to authenticate to the configuration data store first before the user can authenticate to any authentication module. This enables the user to log in as amadmin to any authentication module only if the user can successfully authenticate to configuration store first.

Known Issues Fixed in This Release

The following were identified in OpenSSO Enterprise 8.0 as known issues.  These issues are resolved in OpenSSO Express Build 7.

Web Container and Server Issues

• 4077: OpenSSO Enterprise configuration on WebLogic Server requires newldapjdk.jar
• 4099: ID-WSF sample with JDK 1.4 WAR returned exception
• 4094: Multi-server setup fails whenamadminpassword and directory manager password for configuration data store are not the same
• 4055: Error occurred after adding an advanced property in console
• 3858: Out of memory exceptions occur under heavy load with JDK 1.5 and 1.6 SunPKCS11 provider
• 3837: Configuration fails on Oracle Application Server 10g
• 2222: Password reset and account lockout services report notification errors

Data Store Issues

• 4102: TTL for service management configuration is not working
• 4085: OpenSSO Enterprise is unable to store the CRL in the LDAP directory
• 3827: Replication configuration hangs on second Glassfish instance
• 3350, 2867:LDAP Follows Referralshould be disabled for Active Directory Data Store

Authentication Issues

• 4103: Windows Desktop SSO authentication module returns "No Configuration Found" error
• 4100: Certificate authentication with CRL checking fails
• 4054:amadmin authentication fails with URL org parameter
• 1781:amadmin login fails for non Data Store authentication This fix is integrated with Issue 4286 below.
• 4286 : After upgrading from JES4, in co-existence mode, amadmin can authenticate to configuration data store

  Policy Issues

• 3952: Server samples are missing the policy samples link
• 3949: OCSP checking needs permission added to server.policy file
• 3796: Creation of Fedlet in console failed in a console only deployment
• 2381: Access Manager Roles policy subject is supported only with Access Manager repository data store

Session Issues

• 3910:setup.bat of ssoSessionTools.zip fails to install tools
• 2827: Configuring a site does not add the second server to the site

Command-Line Utilities Issues

• 4079:ssoadm import-svc-cfg command fails when using Directory Server as the configuration data store
• 3955: Unable to execute the ssoadm command
• 2905:jss4.jar entry is missing in the ssoadm classpath

Client SDK Issues

• 4081: SMS cache is disabled by default on the Client SDK
• 4080: Client SDK Configurator puts the wrong shared secret in theAMConfig.propertiesfile

Federation and SAML Issues

• 3923: Creating an entity (IDP or SP) in Console Common Tasks page fails on Oracle Application Server
• 3065: Same context ID is used for all users in ID-FF log records
• 2661:logout.jspdid not compile on WebSphere Application Server 6.1
• 1977: SAMLv2 sampleconfigure.jspfiles fail on WebSphere Application Server 6.1

Web Services Security (WSS) Issues

• 4057: Dynamic web service provider configuration with endpoint does not take effect

Upgrade, Compatibility, and Coexistence Issues

• 4108: Incorrect encryption key used after configuring OpenSSO Enterprise against existing schema (DIT)
• 3962: Incorrect Console URL returned after authentication for non-admin user
• 3961:amadmincannot log in to OpenSSO Console in coexistence mode
• 2348: Document Distributed Authentication UI server support
• 830: ID-FF schema metadata is not backward compatible

Policy Agents Issue

• 3581: Policy evaluation with DNS condition fails for version 3.0 policy agents

Internationalization Issues

• 4090: Non-English entitlements are garbled
• 4051: Multi-byte trusted partner name is garbled in Console
• 3976: Online Help "Tips on Searching" shows 404 error in non-English locale
• 3766:encode.jspandampassword -ediffer with multi-byte (non-ASCII) character

Localization Issues

• 4017: In Spanish locale, "2.2 Agents" is translated only as Agentes in Console
• 3994: In Spanish locale, cannot access Certificate for Configuration > Authentication
• 3971: In Chinese (zh_CN) locale, online help is in English
• 3802: Problems in the French part of copyright notice

Known Issues in This Release

• 6827245: Error message is displayed after SAML2 single sign-on
• 4805: WindowsDesktopSSO authentication module does not work on IBM WebSphere Application Server
• 4844: Fedlet single sign-on fails using IBM WebSphere Application Server 7.0
• 4727: Session backup performance degrades
• 4727: Using two Session Failover configurations can lead to performance problems

6827245: Error message is displayed after SAML2 single sign-on

After performing SAML2 single sign-on, you may see this error message displayed:

ERROR: Can't get property: SAML2IDPSessionIndex

This may occur at the  Identity Provider when the user session idle time expires after performing single sign-on.

Although this message displays as designed, the error condition does not cause any actual problem in your deployment.  You can disregard this message.

4805: WindowsDesktopSSO authentication module does not work on IBM WebSphere Application Server

The IBM JDK uses a different Kerberos module name, causing the WindowsDesktopSSO authentication module to fail.

To remedy this problem:

1. Add the following property to the amConfig.propterties file:
   com.sun.identity.authentication.module.WindowsDesktopSSO.Krb5LoginModule=com.ibm.security.auth.module.Krb5LoginModule
2. Restart WebSphere Application Server.

4844: Fedlet single sign-on fails using IBM WebSphere Application Server 7.0

The OpenSSO Fedlet may fail if deployed on  IBM WebSphere 7.0.

As a workaround, add the following JARs to the fedlet WEB-INF/lib directory:

• xalan.jar
• xercesImpl.jar

You can obtain the JARs from the OpenSSO website https://opensso.dev.java.net/public/use/index.html#source. Download and extract opensso-sun-extlib.zip.

4727: Session backup performance degrades

The problem occurs when the Message Queue broker list in amsfo.conf is not identical to the Message Queue broker list in the session failover configuration.  To view the session failover configuration, in the OpenSSO administration console, go to Configuration > Global > Session> Secondary Configuration Instance > Database URL.

For example, if the Database URL entry is
mq1.example.com:7777,mq2.example.com:7777,
but in the amsfo.conf file, the CLUSTER_LIST property is set at
mq2.example.com:7777,mq1.example.com:7777,
the hosts are not listed in the same order.  Both Message Queue brokers will be active and session backup performance will degrade.

Be sure that the hosts are listed in the same order.  In this example, the Database URL and the CLUSTER_LIST property should be set at
mq1.example.com:7777,mq2.example.com:7777.

4727 : Using two Session Failover configurations can lead to performance problems

A typical deployment of Session Failover component consists of two dedicated machines, each hosting a Message Queue and a Berkeley database for storing user sessions. Each user session will be replicated to the Berkley databases. This dual-host setup is for redundancy reasons and not for load-sharing.  Each additional Session Failover component host offers a gain in additional data redundancy, but no gain in processing capacity. In fact, the extra data replication overhead reduces the overall Session Failover component processing capacity.

Due to a limitation in the Message Queue implementation,  a dual-host deployment can support a substantially lower maximum throughput than a single-host Session Failover deployment. This is due to Message Queue-to-Message Queue communication overhead. When OpenSSO generates requests faster than Session Failover component can process, messages overflow and are rejected by the Session Failover component.  This leads to stale and missing sessions stored in the Session Failover component. If the expected load is high, the best practice is to configure one of the following:

• A single Session Failover component host only
  This requires a single Session Failover host component. Configure one Session Failover host in OpenSSO console.

• Two Session Failover component hosts in active-standby mode (instead of active-active mode)
  This requires two Session Failover component hosts as documented in the product guides. But only the Session Failover component on one host will be started. The Session Failover component on the other host will be stopped and kept as a standby. When the first host is stopped or fails, the Session Failover component on the second host will be started manually or by a script.

The advantage of the having two Session Failover component hosts in active-standby mode is that if the first host goes out of service, there is always a second host ready to replace it. Using a single Session Failover component host, having out-of-service hardware could result in the system running in a non-Session Failover mode for a  long time.

The impact of both workarounds is that if the only active Session Failover component stops or fails, then the stored sessions are lost until future user activities trigger new session updates. If an OpenSSO server also stops or fails during this period of time before sessions are fully restored, user sessions on that OpenSSO server cannot be restored from the Session Failover component. Users will be re-authenticated. For these reasons, do not to restart OpenSSO servers immediately after a Session Failover component restart or failover.

Deprecation Notifications and Announcements

• The LDAP JDK file ldapjdk.jar is not included in OpenSSO beginning with OpenSSO Express Build 7.
• The Service Management Service (SMS) APIs (com.sun.identity.sm package) and SMS model will not be included in a future OpenSSO Enterprise release.
• The Unix authentication module and the Unix authentication helper (amunixd) will not be included in a future OpenSSO Enterprise release.
• The Sun Java System Access Manager 7.1 Release Notes stated that the Access Manager com.iplanet.am.sdk package, commonly known as the Access Manager SDK (AMSDK), and all related APIs and
  XML templates will not be included in a future OpenSSO Enterprise release. Migration options are not available now and are not expected to be available in the future. Sun Identity Manager provides user provisioning solutions that you can use instead of the AMSDK. For more information about Identity Manager, see http://www.sun.com/software/products/identity_mgr/index.jsp.

How to Report Problems and Provide Feedback

If you have questions or issues with OpenSSO Enterprise, contact Sun Support Resources (SunSolve) at http://sunsolve.sun.com/.

This site has links to the Knowledge Base, Online Support Center, and Product Tracker, as well as to maintenance programs and support contact numbers.

If you are requesting help for a problem, please include the following information:

• Description of the problem, including when the problem occurs and its impact on your operation
• Machine type, operating system version, web container and version, JDK version, and OpenSSO Enterprise version, including any patches or other software that might be affecting the problem
• Steps to reproduce the problem
• Any error logs or core dumps

Additional Sun Resources

You can find additional useful information and resources at the following locations:

• Sun Services: http://www.sun.com/service/consulting/
• Sun Software Products: http://wwws.sun.com/software/
• Sun Support Resources http://sunsolve.sun.com/
• Sun Developer Network (SDN): http://developers.sun.com/
• Sun Developer Services: http://www.sun.com/developers/support/