Autonomous Session Management

AM 5 servers manage sessions autonomously—they provide session access and management independently of one another. The concept of a home server—the server to which a user originally authenticated—is no longer applicable. Most user requests can be satisfied by any server in a cluster.

Two architectural changes in AM 5 enable autonomous session management:

Note that SAML single logout still requires crosstalk between AM servers.

Session High Availability Enabled by Default

Session high availability, formerly referred to as session failover, is now enabled by default for all AM deployments. No configuration is required during installation to enable session high availability, and it cannot be disabled.

All configuration settings related to session high availability have been removed.

CTS Session Affinity Capability

AM can now connect to multiple master directory server instances, with each instance acting as the master for a subset of CTS tokens. In this architecture, CTS tokens are described as having an affinity for a given directory server instance.

Versions prior to this release required the CTS token store to be deployed in an active/passive architecture, which limits AM's connection to the CTS token store to a single master instance with failover instances. In this release, the CTS token store can still be deployed in an active/passive architecture.

For more information about CTS token affinity, see "General Recommendations for CTS Configuration" in the Installation Guide.

Amster Command-line Interface Tool

Amster is a command-line interface built upon the AM REST interface. Use Amster in DevOps processes, such as continuous integration, command-line installations, and scripted cloud deployments.

For more information, see the Amster documentation.

Heartbeat Monitoring to External Configuration Store

AM now provides a heartbeat interval of ten seconds (default) to the configuration store. You can override the default settings by setting the JVM startup properties:

For more information, see "Setting the Configuration Store Heartbeat" in the Installation Guide.

Bootstrap AM from Environment Variables

AM can now be bootstrapped from environment variables or Java properties, overriding the boot.json file created during installation. See "Overriding Startup Settings" in the Installation Guide for more information.

Previous releases could only be bootstrapped from the bootstrap file.

Directory Services 5

AM now includes an embedded version of the latest Directory Services product (5), which you can use as the embedded data store, configuration store, token store, UMA resource set store, and UMA history store.

You should be aware of the changes to the LDAP command-line tools for ${dj.product.name} 4.0. For information, see Important Changes to Existing Functionality.

New Splunk Audit Event Handler

AM can now log audit events to a Splunk platform. For more information, see "Implementing Splunk Audit Event Handlers" in the Setup and Maintenance Guide.

New Stateless/OpenID Connect Encryption Modes

AM now provides additional encryption algorithms and encryption methods for stateless sessions and OpenID Connect ID tokens. This release also supports new compression features for stateless sessions.

Added OAuth 2.0 Proof-of-Possession Support

AM now supports use the proof-of-possession support when using OAuth 2.0 access tokens to ensure that the presenter of a bearer token was issued the access token originally.

AM supports proof-of-possession keys for both stateful and stateless OAuth 2.0 tokens.

For more information, see "Using OAuth 2.0 JSON Web Token Proof-of-Possession" in the OAuth 2.0 Guide.

AES Wrap Encryption Support

AM now supports the Advanced Encryption Standard (AES) Key Wrap algorithm (RFC3394), implementing the Password-Based Key Derivation Function 2 (PBKDF2) (RFC2898). Administrators can choose the key size hash algorithms, such as SHA1, SHA256, SHA384, or SHA512.

For more information, see "Preparing AES Key Wrap Encryption" in the Installation Guide.

OAuth 2.0 Token Endpoint Authentication Signing Algorithm Added

The new property Token Endpoint Authentication Signing Algorithm has been added to the OAuth 2.0 / OpenID Connect client to specify the JWS algorithm that must be used for signing JWTs used to authenticate the client at the Token Endpoint.

For more information, see "OAuth 2.0 and OpenID Connect 1.0 Client Settings" in the OpenID Connect 1.0 Guide.

OAuth 2.0 Mix-Up Mitigation Support

Added Support for Signing and Encryption of Responses on the UserInfo OIDC Endpoint

AM 5 now supports signing and encrypting UserInfo responses as per the OIDC spec.

Properties have been added to the OAuth 2.0 / OpenID Connect client for signing and encrypting the contents of the UserInfo response.

For more information, see the OIDC spec.

For more information, see "OAuth 2.0 and OpenID Connect 1.0 Client Settings" in the OpenID Connect 1.0 Guide.

Reorganization

AM now has reorganized documentation. Concise, topic-based guides replace the larger guides available for previous releases.

Administrator tasks, developer tasks, and reference information now appear in a single guide per topic. For example, the OAuth 2.0 Guide contains information about working with OAuth 2.0 that was formerly spread across the OpenAM Administration Guide, the OpenAM Developer's Guide, and the OpenAM Reference.

LDAPv3Repos LDAP Servers are Now Stored as Comma-Separated Ordered Lists

For multiple data stores behind a load balancer deployment, AM now stores its servers as a comma-separated list, rather than orderedlist.

For example, given a site configuration, ID 02, with two servers, IDs 01 and 03. In previous releases (prior to AM ${am.software.version} and earlier), AM would store the servers as an orderedlist:

$./ldapsearch -p 51389 -D "cn=Directory Manager" -w cangetin -b "ou=services,dc=openam,dc=forgerock,dc=org" "objectclass=*"  > backup.ldif
$ grep "sun-idrepo-ldapv3-config-ldap-server" backup.ldif
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=xxx.example.com:1389|01|02
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=zzz.example.com:1389|01|02
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=xxx.example.com:1389|03|02
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=localhost:51389
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=zzz.example.com:1389|03|02

Now, AM stores its multi-server configuration as a comma-separated ordered list:

$./ldapsearch -p 51389 -D "cn=Directory Manager" -w cangetin -b "ou=services,dc=openam,dc=forgerock,dc=org" "objectclass=*"  > backup.ldif
$ grep "sun-idrepo-ldapv3-config-ldap-server" backup.ldif
sunKeyValue: sun-idrepo-ldapv3-config-ldap-server=[0]=xxx.example.com:1389|01|02,xxx.example.com:1389|03|02,localhost:51389,zzz.example.com:1389|01|02,zzz.example.com:1389|03|02

Do Not Enable org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH in Production

It is strongly recommended not to use the forward slash character in policy names. Users running AM servers on Tomcat and JBoss web containers will not be able to manipulate policies with the forward slash character in their names without setting the ‑Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true argument in the CATALINA_OPTS environment variable before starting the AM web container.

It is also strongly recommended not to enable the ALLOW_ENCODED_SLASH=true setting while running AM in production. Using this option introduces a security risk. See Apache Tomcat 6.x Vulnerabilities and the related CVE for more information.

If you have policy names with forward slashes after migration to AM 5.x, rename the policies so that they do not have forward slashes. Perform the following steps if you use Tomcat or JBoss as your AM web container:

Methods for Specifying Realms in REST and XUI URLs Changed

The methods for specifying the realm to target when using the REST API or making requests to the XUI have been altered.

Realm paths must be absolute and include the top-level realm, and DNS aliases and realms specified in the query string are no longer concatenated if used together – the query string overrides the DNS alias.

For information on specifying realms in XUI URLs, see "Specifying the Realm in the Login URL" in the Authentication and Single Sign-On Guide.

For information on specifying realms in REST API URLs, see "Specifying Realms in REST API Calls" in the Authentication and Single Sign-On Guide.

Upgraded Instances Will Use XUI User Interface

This version only supports the XUI user interface. Upgrading an instance will force use of the XUI, even if the upgraded instance had disabled it.

The option to disable the XUI has also been removed in this release.

For more information, see UI Customization Guide.

Stateless Post-Authentication Plugins

Releases prior to AM 5 implemented the Keep Authentication Module Objects for Logout Processing option in the Core Authentication module. When this option was enabled, OpenAM maintained state information in server memory throughout a session's duration for post authentication plugin module instances. When logout was triggered, OpenAM invoked the same post authentication plugin module instance with state information intact. Therefore, developers could access module state stored at login when users logged out.

In AM 5.0.0, post authentication plugin modules can not hold state as module state is never maintained in an OpenAM server's memory. Post authentication plugins that relied on module state being maintained in OpenAM's memory between login and logout must be rewritten. You can store any information that you want to save between login and logout in a session property. OpenAM stores session properties in the CTS token store after login, and retrieves them from the token store as part of the logout process.

The Keep Authentication Module Objects for Logout Processing option in the Core Authentication module has been removed from AM 5.0.0.

Two Default Post-Authentication Plugin Classes Renamed

The following default post authentication plugin classes have been renamed:

Upgrading to AM 5.0.0 automatically converts these two post authentication plugin class names if they are defined in authentication chain properties and in Core Authentication module properties. If you have specified the old class names anywhere else in OpenAM, you must update to the new class names manually.

Server Memory Configuration Changes

In previous releases of OpenAM, stateful sessions were always stored in OpenAM server memory. They were also optionally written to the CTS token store when OpenAM was configured for session failover.

In AM 5.0.0, the CTS token store is now the authoritative source for stateful sessions. Sessions can also be cached in AM server memory for performance.

The server property com.iplanet.am.session.maxSessions, which formerly specified the maximum number of sessions that could be held concurrently in AM server memory (including RADIUS client sessions), has been removed from AM 5.0.0. The maximum number of sessions that can be stored in the CTS token store is unconstrained.

You can use either or both of the following two new properties if needed:

CTS Reaper Cache

When an AM server modifies a token in the CTS store, it also takes the responsibility to delete it when it expires. To reduce the number of relatively slow queries to the CTS store to determine which tokens have expired, each AM server maintains a local cache of which tokens to delete, and when.

The new org.forgerock.services.cts.reaper.cache.size advanced property controls the size of the cache.

For more information, see "CTS Tuning Considerations" in the Installation Guide.

As part of these CTS tuning changes, the following properties have been removed from OpenAM:

Entity Tag Virtual Attribute

To tune the CTS data store for a slight boost in throughput, you can disable the default virtual attributes, except for the Entity Tag virtual attribute, which is required.

Bootstrap File Change

The name and format of the file used to bootstrap OpenAM has been changed. The JSON file, boot.json, replaces the bootstrap file.

Federation Navigation Link Replaced

The Federation link in the AM console's top navigation bar has been removed.

Some CTS OIDs Now Use the Custom Float2dp Data Type

The following CTS OIDs now use the new, custom Float2dp data type:

The Float2dp data type is a floating point number with the value d-2 in the DISPLAY-HINT clause. SNMP clients that handle the DISPLAY-HINT clause will correctly display the value as a floating point number with two decimal places. Other types of clients that do not handle the DISPLAY-HINT clause will incorrectly display the value as an integer that is one hundred times larger than the correct value.

All other CTS OIDs use the Counter64 data type, a standard data type returned by SNMP OIDs.

For more information, see "Core Token Service (CTS) Object Identifiers" in the Installation Guide.

.NET Fedlet Documentation Moved

The .NET Fedlet documentation is now a ForgeRock Knowledge Base article available to ForgeRock customers.

Sessions Navigation Link Replaced

The Sessions link in the AM console's top navigation bar has been removed.

A new XUI Sessions page is available in Realms > Realm Name > Sessions, and its functionality has changed as follows:

Change for OAuth 2.0 Mix-Up Mitigation

For the OAuth 2.0 authentication module, a new property openam-auth-oauth-mix-up-mitigation-enabled has been added, which lets the OAuth 2.0 for Mix-Up Mitigation feature to protect the deployment for identity provider (IdP) Mix-Up attacks during an OAuth 2.0 authorization code flow. This property will run additional verification steps when receiving the authorization code from the authorization server.

On the AM console, the field Name of OpenID Connect ID Token Issuer has been changed to: Token Issuer. The authorization code response can contain an issuer value (iss) that is validated by the client. When the module is an OAuth2-only module (that is, OIDC is not used), the issuer value needs to be explicitly set in the Token Issuer property, so that the validation can succeed.

Push Authentication Level Attribute for Push Authentication Module Renamed

The authentication level attribute, forgerock-am-auth-push-auth-level, for the push authentication module has been renamed to forgerock-am-auth-authenticatorpush-auth-level.

XUI Authentication Changes

The following XUI authentication changes were made in this release:

Support for HttpOnly

AM supports an HttpOnly flag that mitigates against cross-site scripting (XSS) vulnerabilities.

For more information, see "Configuring HttpOnly" in the Authentication and Single Sign-On Guide.

REST "sessionresource" Endpoint Changed

Starting with this release, the sessionresource endpoint no longer supports the queryId=server and queryId=list options.

The queryId=all option has also changed. The number of returned records is limited by the token store maximum page size. For example, a Directory Services 5 store has a a limit of 4000 records by default. Queries that would return more records than the limit will return no records, and an error.

You should use version 2 of the endpoint, which supports fine-grained querying to limit the number of session records returned from the token store.

The "Idtokeninfo endpoint requires client authentication" Option Now Applies to All Signing Algorithms

Starting with this release, if the "Idtokeninfo endpoint requires client authentication" option is enabled, all requests to the /oauth2/idtokeninfo endpoint must be authenticated, not just those that use HMAC-based signing.

For more information, see "OAuth2 Provider" in the OpenID Connect 1.0 Guide.

Support for External OpenDJ 2.6 Data Stores Reduced

OpenDJ 3.0 or later is now required for external configuration, UMA, and CTS data stores.

For more information, see "Data Store Requirements".

Realm Aliases Deprecated

The use of realm aliases is deprecated in this release.

DNS aliases remain unaffected.

For information on aliases, see "Setting Up Realms" in the Setup and Maintenance Guide.

Classic Logging Service Deprecated

The classic logging service is deprecated in this release.

For information on the replacement audit logging service, see "Introducing the Audit Logging Service" in the Setup and Maintenance Guide.

User-Managed Access v1.0 and v1.0.1 Deprecated

Support for UMA 1.0 and UMA 1.0.1 will be removed in a future version of AM. Features and functionality will be upgraded to support upcoming UMA standards.

For more information on deprecation, see "Release Levels and Interface Stability".

The ssoadm.jsp Page Is Deprecated

Deprecated REST APIs

The following table lists deprecated REST APIs and their newer equivalents:

HTTP Client Get() and Post() Scripting Methods Deprecated

The HTTP client methods get() and post() used when making HTTP calls from within scripts are deprecated. Use the send() method in their place.

For more information, see "Accessing HTTP Services" in the Development Guide.

JDK 7 Support Deprecated

Support for Oracle JDK 7 and IBM SDK 7 will be removed in the next 5.5 release of AM.

When upgrading to the current release, also move to JDK 8 in order to be prepared for pending removal of support for JDK 7.

OAuth2Saml2GrantSPAdapter Adapter Class Deprecated

The org.forgerock.openam.oauth2.saml2.core.OAuth2Saml2GrantSPAdapter adapter class used in service provider configurations to POST assertions to OAuth 2.0 authorization services will be removed in a future version of AM.

The ssoadm, ampassword, configurator.jar and upgrade.jar Tools Are Deprecated

Amster is replacing the ssoadm command and the configurator.jar, upgrade.jar, and ampassword tools, which will be removed in a future release of AM.

For more information about Amster, see the Amster documentation.

Client SDK Deprecated

The client SDK will be removed and replaced in a future version of AM.

The Classic JATO-Based UI Is Deprecated

The classic JATO-based UI is deprecated for the end-user pages and replaced in OpenAM with the JavaScript-based XUI as a replacement. The classic UI for end user pages is likely to be removed in a future release.

Listing Tokens With the /frrest/oauth2/token/?_queryId Method is Deprecated

Improved _queryFilter support will be added to replace the _queryId method.

The Device Print Service Is Deprecated

For information on replacement device identification features, see "Device ID (Match) Authentication Module" in the Authentication and Single Sign-On Guide.

OpenAM Logging and User Self Service Are Deprecated

The OpenAM Logging, User Self Service, and Password Reset Services are deprecated. The User Self Service has been renamed to Legacy User Self Service.

Deprecated REST APIs

The following table lists deprecated REST APIs and their newer equivalents:

Server Configuration Properties Removed

The following server configuration properties have been removed from OpenAM:

Session Service Secondary Configuration Settings Removed

With the removal of crosstalk between OpenAM servers, the settings in Session Service secondary configuration are no longer needed. As a result, the ability to add a secondary configuration instance to the global Session Service has been removed from OpenAM.

Session Trimming Setting Removed

With the removal of the session purge delay from OpenAM, there is no longer a need to trim sessions being held for purge delay. Therefore, the Session Service's session trimming property is also being removed from OpenAM.

Keep Authentication Module Objects For Logout Processing Option Removed

This option, formerly a property of the Core Authentication Service, is no longer available in OpenAM.

Specifying Session Listeners On All Removed

Schema attribute iplanet-am-session-add-session-listener-on-all-sessions has been removed. The AddSessionListenerOnAllSessions is a PLL call that allows you to specify a URL to be notified when changes occur, such as logout. It was found that this setting only applied to sessions that the current server was aware of and would not persist after a server restart.

Existing user stores may still have the schema attribute. Leaving the attribute in the user stores does not cause any issues. If you want to update your directory schema, you can remove this schema attribute.

For example, if you are using a Directory Services 5 data store, you can update the schema attribute as follows:

$ ldapsearch -p 1389 -b cn=schema -s base "(&)" \+ | \
 grep 2.16.840.1.113730.3.1.1070
 attributeTypes: ( 2.16.840.1.113730.3.1.1070 \
  NAME 'iplanet-am-session-add-session-listener-on-all-sessions' DESC 'an example' \
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications \
  X-SCHEMA-FILE '99-user.ldif' )

$ ldapmodify -p 1389 -D "cn=Directory Manager" -w password
 dn: cn=schema
 changetype: modify
 delete: attributeTypes
 attributeTypes: ( 2.16.840.1.113730.3.1.1070 NAME \
 'iplanet-am-session-add-session-listener-on-all-sessions' DESC 'An example' \
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications \
 X-SCHEMA-FILE '99-user.ldif' )
 Processing MODIFY request for cn=schema
  MODIFY operation successful for DN cn=schema

For more information, see AME-11448.

ssoadm Policy Commands Removed

The following policy commands have been removed from the ssoadm command:

For more information, see the OpenAM Reference section ssoadm — configure OpenAM core services in the Reference.

Safari for Windows No Longer Supported as Client Browser

For more information about supported clients, see "Supported Clients".

Liberty ID-FF Global Configuration Removed

Support for Liberty Identity Framework was deprecated in a previous version of AM.

OPENAM-2346: RFE: OAuth2 Resouce Owner Password Grant should support service and module auth parameters

OPENAM-2632: RFE: The identity/authorize REST API should be able to consume an OAuth2 access token

OPENAM-5114: User should be able to rename or clone an existing Application containing policies without first deleting the policies

OPENAM-5802: Import of policies should import application and resource type information as well

OPENAM-5969: Allowing RequesterID chain when using SAML2 Idp Proxy

OPENAM-6360: Send notifications for sessions even when the authoritative server is down

OPENAM-8078: Develop a REST endpoint that returns all sessions for a user

OPENAM-8210: Enhance CTS to persist tokens across multiple OpenDJ instances rather than a single primary OpenDJ instance by some form of sharding

OPENAM-8560: CTS should use replace rather than delete/add for single valued attributes

OPENAM-8581: JSON REST authenticate should return 401 for session timed out error

OPENAM-8627: Provide support for more XML signatures types in .NET fedlet

OPENAM-8772: Soap STS application token should retry if an operation failed

OPENAM-8790: Better error message when resource owner auth failed with grant_type=password

OPENAM-8836: Realm alias in XUI Admin Console should be reflected in fqdnMap

OPENAM-8983: introspect endpoint shouldn't be limited to the same client as token

OPENAM-9234: Add health check for the SOAP STS

OPENAM-9366: Install.log doesn't contain timestamps, which block performance issue investigation

OPENAM-9454: Allow the .NET Fedlet to be serialized and stored in session state

OPENAM-9460: Include SOAP STS WAR in OpenAM Distribution Zip

OPENAM-9536: Reduce size of stateless sessions

OPENAM-9555: Persistent Cookie should set username in shared state

OPENAM-10144: Add introspection endpoint in .well_known discovery

OPENAM-10207: Authorize sending both HTTP Basic Auth credentials and client_id if client secret is not defined

OPENAM-10316: Remove error from Maven build on openam-ui-ria for Windows

OPENAM-10388: Allow message from auth module to be returned when resource owner auth failed with grant_type=password

OPENAM-10429: oauth2/authorize consent page (authorize.json) should take locale headers into account

OPENAM-10444: FMSessionProvider should adhere to setCookieToAllDomains setting

OPENAM-10570: Add support for the SAML2_CONFIG component in FedletConfigurationImpl

OPENAM-820: AMSetupServlet only checks for product bootstrap validity on initial load

OPENAM-1194: Unable to get AuthnRequest error in multiserver setup

OPENAM-4040: SSO failure between SPs in separate CoTs with same hosted IDP

OPENAM-5984: The XUI is unhappy when the CORS filter is enabled

OPENAM-7836: User Self Service forgottenPassword endpoint throws HTTP 500

OPENAM-8336: XUI+REST authentication with chains must have sticky load balancing

OPENAM-8396: Extend depth of the heartbeat used between OpenAM<>LDAP to check a baseDN beyond the root DSE

OPENAM-8831: Accessing policy editor through a subrealm DNS alias displays the policies for that subrealm independently of the realm selected

OPENAM-8862: ServiceProvider (SP) meta data import succeeds with incorrect encryption key size

OPENAM-8886: "OpenID Connect default acr claim" is not implemented

OPENAM-8977: Force the user to set the security questions

OPENAM-9112: Audit logging outputs errors in debug log under high load

OPENAM-9447: OAuth2 client has different default values for clean installation and upgraded AM from 13.0.0 to 13.5

OPENAM-9756: RFE: Allow pagination on Identity endpoints

OPENAM-9798: CTS Query element order should be optimised

OPENAM-9808: Forgot Username self-service can return "username" that might not be the same as login "username"

OPENAM-9938: REST API to delete all tokens of a user

OPENAM-9980: add package com.iplanet.security to public API

OPENAM-10088: Make the set of characters used to create code in OAuth2 Device flow configurable

OPENAM-10394: RFE: Include goto URL in verification email sent during User Registration / Forgot Password flow

OPENAM-10446: Need more Audit logging for OAuth2/OIDC/UMA request/response fields

OPENAM-10467: RFC7662: oauth2/introspect OpenAM returns token_type not as Bearer

OPENAM-10478: kids used by AM for signing are not accessible to developers implementing a remote JWKs URI for AM

OPENAM-10481: Default JWKS_URI of an OpenID provider doesn't allow signing key rotation

OPENAM-10562: Audit log 'Configuration' entries are not written when using external configuration store

OPENAM-10578: Stateless access token doesn't contain the grant type

OPENAM-10585: The "claims" Request Parameter from the openid standard isn't functional

OPENAM-10613: Provide support for using multiple attributes from the assertion when looking up the user in the auto federation case

OPENAM-10624: Support validation of arbitrary scheme goto URLs

OPENAM-10717: Encryption algorithms and encryptions methods don't all work out of the box

OPENAM-10735: Amster script does not work on Solaris SPARC 10

OPENAM-10816: Amster - SAML2 Entity fails to import

OPENAM-10869: SAML2 Authentication module return "Unable to link local user to remote user" ambiguous.

OPENAM-10921: Provide ability to retrieve OAuth2 consent dates