Copyright © 2011-2013 ForgeRock AS
Publication date: December 13, 2013
Notes covering OpenAM prerequisites, fixes, known issues. OpenAM provides open source Authentication, Authorization, Entitlement and Federation software.
OpenAM 12.0.0-SNAPSHOT fixes a number of issues, and provides the following additional features.
This release uses the new OpenAM Core Token Service (CTS), with a more generalized token storage format for sessions, SAML Tokens, and OAuth Tokens. The LDAP schema have been extended for the CTS objects.
OpenAM now fully supports OAuth 2.0 and OpenID Connect 1.0 as well as the required building blocks such as WebFinger, and JWT and related emerging standards.
In addition to playing the role of OAuth 2.0 client and resource server, OpenAM can play the role of OAuth 2.0 authorization server. See Managing OAuth 2.0 Authorization for explanations, instructions, and examples.
OpenAM support for OpenID Connect 1.0 extends OAuth 2.0 capabilities so clients can verify claims about the identity of the end user, get profile information for the end user, and manage end user sessions. OpenAM plays the role of OpenID Provider. See Managing OpenID Connect 1.0 Authorization for details.
New, more modern RESTful web services are available for
authentication, identity management, profile management, session management,
Integrated Windows Authentication, and more. New endpoints are available
under the URI
/json where OpenAM is deployed, and are
demonstrated in the Developer Guide chapter on Using RESTful Web Services
OpenAM adaptive authentication capabilities now include the Device Print authentication module (OPENAM-1375). The Device Print module uses characteristics of a system, including installed fonts, screen resolution, timezone, and also geolocation to uniquely identify the system. The Device Print module includes all of the functionality associated with the HOTP authentication module.
OpenAM now supports Open Authentication (OATH, OPENAM-727). The module provides the user with a one-time password based either on a HMAC one-time password or a time-based one-time password. OATH lets you determine which type of one-time password is best for your users when they need to login with a password generating device. Devices can range from a smartphone to a dedicated device, such as YubiKey or any other OATH compliant device.
With OATH, OpenAM now supports YubiKey authentication. The YubiKey simplifies the process of logging in with a One Time Password token as it does not require the user to re-type long pass codes from a display device into the login field of the computer. The YubiKey is inserted in the USB-port of any computer and the OTP is generated and automatically entered with a simple touch of a button on the YubiKey, and without the need of any client software or drivers.
OpenAM now fully supports Internet Protocol version 6 (IPv6) in addition to IPv4.
OpenAM now fully supports Java 7 environments.
OpenAM Session failover has been modified to be simpler to deploy (OPENAM-625). OpenAM 10.0.1 and earlier required the use of Open Message Queue and Berkeley DB Java Edition, which increased the complexity and amount of time required to get session failover working. OpenAM now writes session data to the configuration data store instead. This implementation also can be used to make sessions persist across restart for single OpenAM servers. The current implementation requires that you use OpenDJ for the configuration data store.
OpenAM now includes a preview of the cloud Dashboard service, part of allowing user self-management of web based applications. (OPENAM-2019).
OpenAM now bundles OpenDJ 2.6.
The Persistent Cookie module has been added to support configuration of cookie lifetimes, based on requests and a maximum time.
IBM WebSphere 8 is now a supported platform. See Preparing IBM WebSphere in the Installation Guide for details on how to setup WebSphere 8.0 and 8.5 before deploying OpenAM.
The policy tree index has been updated so that resources first check the root level of a realm first. The tree will be created from this level, and any subsequent referrals will create another tree specific to the realm where the referral was retrieved. This conserves memory and reduces the amount of time required to load the tree. An intelligent indexing model now assists with quickly identifying relevant policy rules for the resource being authorized.
The zero page login has been modified so that administrators can disable the functionality. The zero page login process is the ability of the user to login using only GET parameters, which presents a possible security issue. Zero page login is now disabled by default (OPENAM-2354).
OpenAM now provides an account expiration post authentication plugin to set an account expiration date on successful login.
Remote clients that register notification URLs with OpenAM can now successfully deregister on shutdown (OPENAM-2766, OPENAM-2765), preventing OpenAM from trying to notify applications that are no longer running.
OpenAM now lets you configure the profile attribute name for email used by the password reset module (OPENAM-2604).
OpenAM now provides a mechanism for Identity Providers to use private
key passwords that differ from the password stored in OpenAM's
.keypass file (OPENAM-2306).
OpenAM Java Fedlet
SPACSUtils can now find the
metaAlias in either the URI or the query string
OpenAM now provides a mechanism to supply static values when setting up attribute mapping for a SAML 2.0 Identity Provider or Service Provider (OPENAM-2184).
OpenAM's LDAP authentication module now supports Samba 4 LDAP response codes (OPENAM-1826).
OpenAM's OATH authentication module's minimum password length is now configurable (OPENAM-1765).
The AMLoginModule now lets authentication modules retrieve the list of current session tokens for a user (OPENAM-1721).
OpenAM Console again includes a generic LDAP data store option (OPENAM-1656).
OpenAM's IDPAdapter now provides additional hooks for customization. This improvement introduces changes to the API that affect custom IDPAdapters (OPENAM-1623).
Legacy naming conventions have been changed to conform to the
current product name, OpenAM. This includes the OpenAM bootstrap file
is the new name for
$HOME/.openssocfg/. If you upgrade,
OpenAM still supports use of
does not rename the folder. For new OpenAM installs, OpenAM creates the
directory with the new name,
configuration time. Other files, such as the
file, and paths have been modified to ensure consistency with the naming
When running as a Service Provider, OpenAM no longer requires that you enable module-based authentication (OPENAM-1470).
OpenAM now has better support for using a reverse proxy for federation when DAS is also deployed (OPENAM-1454).
OpenAM now allows use of a read-only data store with a non-transient NameID during SAML 2.0 federation (OPENAM-1427).
The ssoadm command now includes a get-sub-cfg subcommand (OPENAM-1348).
OpenAM IDPs can now proxy all requests whether or not the SP allow the behavior (OPENAM-1266).
When working with Salesforce.com as an SP, OpenAM can now perform SP-initiated SSO, can use any arbitrary URL for the entityID/default endpoint, and automatically selects the last attribute from the first page as the default Federation ID (OPENAM-1232).
The REST authenticate command now has a parameter to specify the client IP address (OPENAM-1048).
OpenAM is now built with Maven. Maven artifacts continue to be uploaded to the ForgeRock Maven repository (OPENAM-739).
OpenAM's OATH module supports shared keys and counters (OPENAM-727).
You can now prevent OpenAM from caching subject evaluations for policy decisions (part of the fix for OPENAM-24).
In most cases you do not need to turn off caching, as OpenAM now clears cache when group membership changes. Before turning off caching in production, first test the setting to ensure that the performance impact is acceptable for your deployment.
To turn off caching, set Access Control >
Realm Name > Services > Policy Configuration >
Subjects Result Time to Live to 0. The equivalent
ssoadm property for the
The C SDK for OpenAM has been simplified. Nightly builds are all available as ZIP files, for Linux, Solaris x86, Solaris SPARC, and Windows operating systems, for both 32- and 64-bit varieties.
For C SDK product versions and support offerings, contact email@example.com.
This chapter covers software and hardware prerequisites for installing and running OpenAM software.
This release of OpenAM requires Java Development Kit 6 or Java Development Kit 7. ForgeRock recommends the most recent update of Java 6 or 7 to ensure you have the latest security fixes.
ForgeRock has tested this release of OpenAM primarily with Oracle Java SE JDK, and also tested OpenAM on WebSphere with IBM JDK.
OpenAM Java SDK requires Java Development Kit 6 or 7.
This release of OpenAM runs in the following web application containers.
Apache Tomcat 6, 7 (ForgeRock's preferred web container for OpenAM)
GlassFish v2, v3
IBM WebSphere 8.0, 8.5
JBoss Enterprise Application Platform 5, 6
JBoss Application Server 7
Jetty 7 (7.6.13 or later)
Jetty 8 (8.1.13 or later)
Oracle WebLogic Server 11g (10.3.5)
Oracle WebLogic Server 12c (12.1.2)
If running as a non-root user, the web application container must be able to write to its own home directory, where OpenAM stores configuration files.
This release of OpenAM works with the following CTS data stores.
Embedded (using ForgeRock OpenDJ for the data store)
External ForgeRock OpenDJ data store
The CTS is supported on OpenDJ versions 2.6.0 and later.
This release of OpenAM works with the following configuration data stores.
Embedded (using ForgeRock OpenDJ for the data store)
When using the embedded configuration store for CTS or configuration, you must deploy OpenAM on a local file system and not on an NFS-mounted file system.
External ForgeRock OpenDJ data store
ForgeRock recommends updating to the latest stable release.
External Oracle Unified Directory 11g or later
External Oracle Directory Server Enterprise Edition data store, version 6.3 or later
This release of OpenAM works with the following user profile data stores.
Microsoft Active Directory (tested by ForgeRock on Windows Server 2008 R2 and 2012)
IBM Tivoli Directory Server 6.3
OpenDS, version 2 or later
Oracle Directory Server Enterprise Edition, version 6.3 or later
OpenAM also works with other LDAPv3 compliant directory servers. Some features of OpenAM depend on features supported by your directory service, such as the following:
Extensible LDAP schema, required to extend the schema for OpenAM.
First, install OpenAM to use a fresh instance of OpenDJ, such as the
embedded OpenDJ server. After installation, study the custom schema
definitions from the OpenDJ file,
config/schema/99-user.ldif, to see what schema
definitions you must add to your directory. You might need to adapt the
schema definition format before adding the definitions to your
The persistent search request control
The Behera Internet-Draft Password Policy for LDAP Directories (in the context of the LDAP authentication module only)
If you plan to deploy with OpenLDAP or other LDAPv3 directory for user data, make sure you test your solution before you deploy to ensure all OpenAM features that you use work as expected.
ForgeRock has tested many browsers with OpenAM console and end user pages, including the following browsers.
Chrome and Chromium 16 and later
Firefox 3.6 and later
Internet Explorer 7 and later
Safari 5 and later
ForgeRock has tested this release of OpenAM on the following platforms.
Linux 2.6, 3.0
Microsoft Windows Server 2008 R2, 2012
Oracle Solaris 10, 11
You can deploy OpenAM on any hardware supported for the combination of software required. Deploying OpenAM requires a minimum of 1 GB free RAM over and above the RAM used by all other software on the system.
Minimum requirements are enough to start and to evaluate OpenAM. Recommended hardware resources depend on your specific deployment requirements. For more information, see the Administration Guide chapter on Tuning OpenAM.
ForgeRock has tested this release of OpenAM primarily on x86 and x64 based systems.
If you have a special request regarding support for a component or combination not listed here, contact ForgeRock at firstname.lastname@example.org.
This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.
When you create a new OpenAM custom configuration that uses an
external LDAP directory server for the configuration data store, you must
use a root suffix DN with at least two domain components, such as
The advanced server property used to set the HTTP header name,
has replaced the legacy OpenSSO property
Legacy naming conventions have been changed to conform to the current product name, OpenAM.
$HOME/.openamcfg/ is the new name for
$HOME/.openssocfg/. If you upgrade, OpenAM still
supports use of
$HOME/.openssocfg/, and does not
rename the folder. For new OpenAM installs, OpenAM creates the directory
with the new name,
$HOME/.openamcfg/, at configuration
Other files, such as the
openam.war file, and
paths have been modified to ensure consistency with the naming
OpenAM now ships with multiple .war files. You no longer have to build custom .war files for core server-only or distributed authentication UI installations for example.
In versions before OpenAM 10.1.0 the default root suffix DN for OpenAM
configuration and profile data was
The default root suffix is now
The fix for OPENAM-1630 changes SAML metadata signing in OpenAM to better conform with the SAML 2.0 standard.
Metadata for hosted entities is signed using the
metadataSigningKey configured for the realm, or
inherited from the global configuration for the server.
OpenAM now signs the
that contains child
When importing remote entity metadata with signatures, OpenAM does not modify the signatures, but instead returns them as they were when they were imported.
When OpenAM imports remote entity metadata that has no signature and
signed metadata is requested on export, OpenAM signs the metadata with
The default policy evaluation mode for new policy agent profiles is now self rather than subtree, in order to better scale for large numbers of policy rules.
Upgrade does not change existing policy agent profile configurations, however. If you want to adopt the new default setting for existing policy agents, you must change the setting manually.
To do so for Java EE policy agents, set
For web policy agents, set
You now specify rules for referrals in the same way as rules for policies.
For example, with previous releases a referral rule for
http://example.com/ matched everything underneath.
Now you would need three rules,
When used at the end of a rule
* matches one or more characters,
rather than zero or more characters.
When you upgrade OpenAM, the upgrade tool converts existing referral rules.
The following functionality is deprecated in OpenAM 12.0.0-SNAPSHOT, and is likely to be removed in a future release.
With the implementation of OAuth 2.0 in this release, OAuth 1.0 has been deprecated. OAuth 1.0 support was originally provided in OpenAM 9.
The Netscape LDAP API is to be removed from OpenAM, with OpenAM
using the OpenDJ LDAP SDK instead. This affects all classes in
OpenAM currently uses Sun Java System Application Framework (JATO). JATO is deprecated and is likely to be replaced in a future release.
With the implementation of the Persistent Cookie authentication module, the Core Authentication module persistent cookie options are deprecated and are likely to be removed in a future release.
Older REST services relying on the following end points are deprecated.
The following table shows how legacy and newer end points correspond.
|Deprecated URIs||Newer Evolving URIs|
|/identity/create, /identity/delete, /identity/read, /identity/search, /identity/update||/json/agents, /json/groups, /json/realms, /json/users|
Find examples in the Developer Guide chapter on Using RESTful Web Services in OpenAM.
Support for the older REST services is likely to be removed in a future release in favor of the newer REST services. Older REST services will be removed only after replacement REST services are introduced.
OpenAM Java SDK no longer supports JDK 5.
iplanet-am-auth-ldap-server-check property for
LDAP and Active Directory authentication modules has been removed and
replaced with a heartbeat mechanism configurable through the LDAP Connection
Heartbeat Interval (
and LDAP Connection Heartbeat Time Unit
openam-auth-ldap-heartbeat-interval) properties for the
Set these new properties as necessary when you have firewalls or load balancers that drop connections that remain idle for too long.
The advanced server property,
openam.session.destroy_all_sessions, has been replaced
by the built-in Global Session Service setting,
Javadoc for the client SDK is no longer delivered with the distribution, but instead is available online.
OpenAM issues are tracked at https://bugster.forgerock.org/jira/browse/OPENAM. This chapter covers the status of key issues and limitations at release 12.0.0-SNAPSHOT.
The following bugs were fixed in release 12.0.0-SNAPSHOT. For details, see the OpenAM issue tracker.
When session failover is configured to use external OpenDJ directory servers, OpenAM must access those directory servers through an LDAP load balancer that can fail over connections from OpenAM whenever a directory server goes offline. Otherwise, sessions could continue to persist after users logout of OpenAM.
Do not run different versions of OpenAM together in the same OpenAM site.
When deploying OpenAM components on Microsoft Windows in an IPv6 environment, you must use the Java 7 Development Kit on Windows (due to JDK-6230761, which is fixed only in Java 7).
The Database Repository type of data store is experimental and not supported for production use.
By default OpenAM does not enforce session quotas when running in Site
mode without session failover. To work around this behavior, set the server
You can set this property in OpenAM console under Configuration > Servers
and Sites > Servers > Server Name > Advanced.
The XUI is experimental and not supported for production use. The only
language locale available for the XUI at this time is US English, in the
On hosts with pure IPv6 networks, OpenAM configuration has been seen to fail while starting the embedded OpenDJ directory server (OPENAM-3008).
The following important known issues remained open at the time release 12.0.0-SNAPSHOT became available. For details and information on other issues, see the OpenAM issue tracker.
If you have questions regarding OpenAM which are not answered by the documentation, there is a mailing list which can be found at https://lists.forgerock.org/mailman/listinfo/openam where you are likely to find an answer.
If you have found issues or reproducible bugs within OpenAM 12.0.0-SNAPSHOT, report them in https://bugster.forgerock.org.
When requesting help with a problem, include the following information:
Description of the problem, including when the problem occurs and its impact on your operation
Description of the environment, including the following information:
Operating system and version
Web server or container and version
Any patches or other software that might be affecting the problem
Steps to reproduce the problem
Any relevant access and error logs, stack traces, or core dumps
You can purchase OpenAM support subscriptions and training courses from ForgeRock and from consulting partners around the world and in your area. To contact ForgeRock, send mail to email@example.com. To find a partner in your area, see http://forgerock.com/partners/find-a-partner/.