Notes covering new features, fixes and known issues in ForgeRock® Access Management. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

Preface

Read these release notes before you install ForgeRock Access Management or update your existing installation.

The information contained in these release notes cover prerequisites for installation, known issues and improvements to the software, changes and deprecated functionality, and other important information.

About ForgeRock Identity Platform™ Software

ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.

The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:

  • ForgeRock Access Management (AM)

  • ForgeRock Identity Management (IDM)

  • ForgeRock Directory Services (DS)

  • ForgeRock Identity Gateway (IG)

Chapter 1. What's New

This chapter covers the new features and improvements done in the current release of ForgeRock Access Management.

1.1. New Features

Access Management 5.5.1

ForgeRock Access Management is a maintenance release that includes a new endpoint version and one fix.

  • New /sessions Endpoint Version

    The /sessions endpoint has a new API version, v3.0, which stores the session token ID in the POST body as a JSON object.

    New endpoint versions may modify the endpoint's default API version. To avoid version conflicts between application calls and REST endpoint APIs, consider specifying the protocol and resource version required by the application in the Accept-API-Version header when making requests to REST endpoints. For more information, see Section 1.3.3, "Review REST API Versions Before Upgrading" in the Upgrade Guide.

    For more information about the /sessions v3.0 endpoint, see AM's API explorer.

Access Management 5.5

ForgeRock Access Management 5.5 is a major release that introduces new features, functional enhancements, and fixes.

  • Authorization
    • Transactional Authorization

      AM 5.5 includes a new transaction-based policy condition. Access to a resource or API can now require interactive user confirmation, for example responding to a push notification in the ForgeRock Authenticator app or confirmation of a one-time password sent by email.

      Each transactional authorization provides a single access to the protected resource, protecting against replay attacks.

      If you use transactional authorization alongside policy agents, they must be at least version 5.

      For more information, see Chapter 3, "Implementing Transactional Authorization" in the Authorization Guide.

  • Authentication
    • Fine-Grained Authentication

      Earlier versions of AM provided authentication chains to configure different authentication modules together. AM 5.5 adds the concept of authentication trees, which provide fine-grained authentication by allowing multiple paths and decision points throughout the authentication flow.

      For more information, see Section 1.4, "About Authentication Trees" in the Authentication and Single Sign-On Guide.

    • New Social Authentication Modules

      AM 5.5 includes new authentication modules for authenticating Instagram, VKontakte, and WeChat users.

      New generic OAuth 2.0 and OpenID Connect 1.0 authentication modules are also included.

      For more information, see Section 2.2.26, "Social Authentication Modules" in the Authentication and Single Sign-On Guide.

    • New IDM User Self Registration Service

      You can configure IDM as a provisioning service in AM. This allows IDM to complete user registration after authenticating to AM using a social identity provider authentication module.

      For more information, see Section 2.4, "Configuring User Registration" in the User Self Service Guide.

  • OAuth 2.0 Applications
    • OAuth 2.0 Dynamic Client Registration Support

      AM 5.5 adds support for the OAuth 2.0 Dynamic Client Registration Protocol, which allows OAuth 2.0 client applications to register dynamically with AM as an authorization server.

      AM supports open registration, registration with an access token, and registration including a secure software statement issued by a software publisher. For details and examples, see Procedure 2.6, "To Configure AM for OAuth 2.0 Dynamic Client Registration" in the OAuth 2.0 Guide.

    • OAuth 2.0 Remote Consent Service Support

      AM 5.5 adds AM support for remote OAuth 2.0 consent services, which allow the consent-gathering part of an OAuth 2.0 flow to be handed off to a separate service.

      The remote consent service renders the consent page, gathers the result, signs and encrypts the result, and returns it to the authorization server.

      For details and examples, see Section 1.1.6, "OAuth 2.0 Remote Consent Service" in the OAuth 2.0 Guide.

  • Privacy and Consent
    • User Managed Access (UMA) 2.0

      AM 5.5 supports the architecturally-simplified UMA 2.0 protocol, which provides the following capabilities:

      • Enhanced user control over their data

      • Support for UMA 2.0 grant for OAuth2 authorization flow

      • Support for UMA 2.0 federated authorization

      UMA 1.0.x is no longer supported.

      For more information, see Chapter 1, "Introducing UMA 2.0" in the User-Managed Access (UMA) 2.0 Guide.

  • General

1.2. Major Improvements

Access Management 5.5
  • Merged Debug Log Messages to Standard Output

    AM now reads a Java system property to determine whether to write debug messages to files in the debug directory or to standard output.

    For details, see Section 9.2.2, "Debug Logging to a Single File or to Standard Output" in the Setup and Maintenance Guide.

  • Reduced Metadata for Stateless OAuth 2.0 Tokens

    AM now stores less metadata in the CTS when the server uses stateless OAuth 2.0 tokens. This improvement does not render any existing OAuth 2.0 tokens invalid.

    When you upgrade an AM server, the upgrade process enables stateless grant token upgrade compatibility mode. This mode allows the CTS to store both former and current formats of Stateless OAuth 2.0 token metadata. The mode enables you to benefit from the improvement when performing a rolling, zero-downtime upgrade of an AM cluster.

    After successfully upgrading all servers in the cluster, disable this mode on each AM server in one of the following ways:

    • In the AM console, under Configure > Global Services > OAuth2 Provider, disable stateless grant token upgrade compatibility mode, and save the change.

    • Set the global OAuth2 Provider service property, statelessGrantTokenUpgradeCompatibilityMode, to false.

  • Improved Cross-Domain Single Sign-On Capabilities

    Starting with Policy Agent 5, CDSSO capabilities have been enhanced:

    • CDSSO now provides SSO capabilities for AM and policy agents in a single DNS domain and cross-domains, which simplifies SSO configuration. For more information, see Section 1.10, "About Single Sign-On" in the Authentication and Single Sign-On Guide.

    • CDSSO now supports stateless sessions, with the following caveats:

      • Stateless sessions do not support restricted tokens. Therefore, policy agents 5 configured in a stateless realm are not protected against cookie hijacking. ForgeRock recommends using policy agents with stateful sessions.

      • To ensure the stateless session cookie size does not surpass the browser supported size, Policy Agent 5 does not support both signing and encrypting the stateless session cookie.

      For more information, see Section 1.10.1, "Cross-Domain SSO" in the Authentication and Single Sign-On Guide and Section 6.1.3, "Configuring Stateless Session Cookie Security" in the Authentication and Single Sign-On Guide.

    CDSSO capabilities for policy agents earlier than version 5 are still supported, but have been renamed to classic CDSSO. For more information, see Section 7.3, "Implementing Classic Single Domain and Cross-Domain SSO" in the Authentication and Single Sign-On Guide.

  • Authentication Level and OAuth 2.0 Access Tokens

    Before a resource owner grants consent to an OAuth 2.0 client, the resource owner authenticates with AM. Upon successful authentication AM assigns an authentication level as described in Section 1.5, "About Authentication Levels" in the Authentication and Single Sign-On Guide.

    AM now associates the authentication level with the access tokens that it issues to the OAuth 2.0 client. When a client introspects the access token, AM returns the authentication level as the value of an auth_level claim in the response. An example claim is shown in the /oauth2/introspect example in Section 3.1, "OAuth 2.0 Client and Resource Server Endpoints" in the OAuth 2.0 Guide.

    This claim is added automatically, with no configuration required to enable it. It is available for all OAuth 2.0 flows, except the client credential flow.

1.3. Security Advisories

ForgeRock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated as well as the timeline for the issuance of security advisories and patches.

For more information on ForgeRock's security advisory policy, click the following link: http://www.forgerock.com/services/security-policy/

Chapter 2. Before You Install

This chapter covers software and hardware prerequisites for installing and running ForgeRock Access Management server software.

ForgeRock supports customers using the versions specified here. Other versions and alternative environments might work as well. When opening a support ticket for an issue, however, make sure you can also reproduce the problem on a combination covered here.

2.1. Files to Download

Access Management software is available at https://backstage.forgerock.com. For a description of the files available for download, see Table 2.1, "Access Management Software".

Table 2.1. Access Management Software
FileDescription

AM-5.5.1.zip

Cross-platform distribution including all software components.

For a list of the files in the .zip archive, see Section 1.3.1, "Obtaining Software" in the Installation Guide.

AM-5.5.1.war

Deployable web application archive file.

SSOAdminTools-5.1.1.1.zip

The .zip file that contains tools to manage AM from the command line.

SSOConfiguratorTools-5.1.1.1.zip

The .zip file that contains tools to configure AM from the command line.


2.2. Operating System Requirements

ForgeRock supports customers using ForgeRock Access Management server software on the following operating system versions:

Table 2.2. Supported Operating Systems
Operating SystemVersion
Red Hat Enterprise Linux, Centos, Amazon Linux6, 7
Amazon LinuxAmazon Linux AMI 2017.03
SuSE11
Ubuntu14.04 LTS, 16.04 LTS
Solaris x6410, 11
Solaris Sparc10, 11
Windows Server2012, 2012 R2, 2016

2.3. Java Requirements

Table 2.3. JDK Requirements
VendorVersion
Oracle JDK8
IBM SDK, Java Technology Edition (Websphere only)8
OpenJDK8

2.4. Web Application Container Requirements

Table 2.4. Web Containers
Web ContainerVersion
Apache Tomcat

7, 8, 8.5

Oracle WebLogic Server

12c

JBoss Enterprise Application Platform

7.0

WildFly AS

9, 10, 10.1

IBM WebSphere

8.5.5.8+


The web application container must be able to write to its own home directory, where AM stores configuration files.

2.5. Data Store Requirements

This section lists supported data stores.

As described in Section 10.1.3, "Generic LDAPv3 Configuration Properties" in the Setup and Maintenance Guide, you can configure AM to use LDAPv3-compliant directory servers as user data stores. If you have a special request to deploy AM with a user data store not mentioned in the following table, contact info@forgerock.com.

Table 2.5. Supported Data Stores
Data StoreVersionCTS DatastoreConfig DatastoreUser DatastoreUMA Datastore
Embedded Directory Services5.5
External Directory Services/OpenDJ3.0, 3.5, 5, 5.5
Oracle Unified Directory11g R2    
Oracle Directory Server Enterprise Edition11g
Microsoft Active Directory2012, 2012 R2, 2016    
IBM Tivoli Directory Server6.3    

2.6. Supported Clients

The following table summarizes supported clients and their minimum required versions:

Table 2.6. Supported Clients
Client Platform Native Apps [a] Chrome 33+ Internet Explorer 9+ [b] Edge 0.1+Firefox 28+Safari 6.2+Mobile Safari
Windows 7 or later   
Mac OS X 10.8 or later     
Ubuntu 12.04 LTS or later      
iOS 7 or later     
Android 4.3 or later      

[a] Native Apps is a placeholder to indicate AM is not just a browser-based technology product. An example of a native app would be something written to use our REST APIs, such as the sample OAuth 2.0 Token Demo app.

[b] Internet Explorer 9 is the minimum required for end users. For the administration console, Internet Explorer 11 is required.


2.7. Supported Upgrade Paths

The following table contains information about the supported upgrade paths to AM 5.5:

Table 2.7. Upgrade Paths
VersionUpgrade Supported?
OpenAM 9.0.x
OpenAM 9.5.x
OpenAM 10.0.x
OpenAM 11.0.x
OpenAM 12.0.x
OpenAM 13.x.x
Access Management 5.x [a]

Caution

[a] Access Management is incompatible with SSO session tokens from OpenAM.

Storage and processing of SSO tokens changed in AM 5, meaning both stateful and stateless SSO sessions created in earlier versions of OpenAM are not supported.

After upgrading from an earlier version, any existing SSO tokens created by that version will become invalid, and users will need to reauthenticate.

In mixed version deployments, earlier versions of OpenAM will not be able to read or process SSO session tokens created by AM 5 or later.

This incompatibility only affects SSO session tokens. OAuth 2.0 and OpenID Connect 1.0 tokens are interoperable between versions.

If your pre-AM 5 deployment relies on long-lived SSO session tokens, and re-authenticating your users will be problematic, raise a ForgeRock Support issue for more information and assistance regarding upgrading to AM 5 or later.


Note

Upgrading between Enterprise and OEM versions is not supported.

For more information, see Checking your product versions are supported in the ForgeRock Knowledge Base.

2.8. Special Requests

If you have a special request regarding support for a combination not listed here, contact ForgeRock at info@forgerock.com.

Chapter 3. Installing or Upgrading

This chapter covers installing and upgrading AM 5.5 software.

Before you install AM or upgrade your existing installation, read these release notes. Then, install or upgrade AM.

  • If you are installing AM for the first time, see the Installation Guide.

  • If you have already installed AM, see the Upgrade Guide.

    Do not perform an upgrade by deploying the new version and then importing an existing configuration by running the ssoadm import-svc-config command. Importing an outdated configuration can result in a corrupted installation.

Chapter 4. Changes and Deprecated Functionality

This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.

4.1. Important Changes to Existing Functionality

This section lists changes done to existing functionality, services, endpoints, and others in the current release of AM.

Caution

Access Management is incompatible with SSO session tokens from OpenAM.

Storage and processing of SSO tokens changed in AM 5, meaning both stateful and stateless SSO sessions created in earlier versions of OpenAM are not supported.

After upgrading from an earlier version, any existing SSO tokens created by that version will become invalid, and users will need to reauthenticate.

In mixed version deployments, earlier versions of OpenAM will not be able to read or process SSO session tokens created by AM 5 or later.

This incompatibility only affects SSO session tokens. OAuth 2.0 and OpenID Connect 1.0 tokens are interoperable between versions.

If your pre-AM 5 deployment relies on long-lived SSO session tokens, and re-authenticating your users will be problematic, raise a ForgeRock Support issue for more information and assistance regarding upgrading to AM 5 or later.

Access Management 5.5
  • Removed Support for UMA 1.0

    AM no longer supports UMA 1.0 and now supports UMA 2.0.

  • Simplified Deployment of Custom Authentication Modules

    AM 5.5 no longer requires registration of custom modules using the ssoadm command. Instead, it uses a service loader to register custom modules' service schemas.

    Make the following changes when deploying a custom authentication module in AM 5.5:

    • Include a class in the custom authentication module's .jar file that invokes the service loader to register the custom module's service schema.

      For an example class, see the SampleAuthPlugin.java file in the custom authentication module sample.

    • Include the META-INF/services/org.forgerock.openam.plugins.AmPlugin resource file in the custom authentication module's .jar file. This resource file holds the fully qualified name of the class that registers the custom implementation.

      For an example resource file, see the org.forgerock.openam.plugins.AmPlugin file in the custom authentication module sample.

    • Update the script or Maven pom.xml file that you use when you build the custom authentication module. Note that the build dependencies have changed since version 5.0 of AM, so you will probably need to change your script or pom.xml file. For an example of a pom.xml file that you can use to build a custom authentication module with a service loader, see the custom authentication module sample.

    • After you have changed your build script or Maven pom.xml file, rebuild the custom authentication module.

    • Do not register custom modules referred to in the SampleAuthPlugin.java and AmPlugin files with the ssoadm command, as was required in earlier versions of AM.

    For detailed information about the custom authentication module sample, see Section 10.1, "Creating a Custom Authentication Module" in the Authentication and Single Sign-On Guide.

  • Limited Support for the Identity Membership Environment Condition in Policies

    Java EE Policy Agent 5 and Web Policy Agent 5 do not support policies configured with the Identity Membership(AMIdentityMembership) environment condition. Instead, configure the equivalent User & Group (Identity) subject condition.

  • Change to Client Credentials for Dynamic OpenID Connect Registration

    When you register an OpenID Connect client dynamically, AM generates client_id and client_secret values. AM now ignores any values provided in the client metadata for these properties.

  • Removed JWT as OAuth 2.0 Grant Type

    JWT is no longer an authorization grant bearer type for OAuth 2.0. For more information, see Section 1.1.7, "JWT Bearer Profile" in the OAuth 2.0 Guide.

  • Changes in the OpenID Connect Client Registration Endpoint

    Due to the implementation of the OAuth2 Dynamic Client Registration specification (RFC7591), the OpenID Connect (OIDC) client registration endpoint (/oauth2/connect/register) has seen the following changes:

    • Using the scopes parameters in the payload is deprecated in favor of the scope parameter.

    • The /oauth2/connect/register endpoint is deprecated in favor of the /oauth2/register endpoint.

      The /oauth2/register endpoint does not default to include the openid scope. Therefore, when registering OpenID Connect clients using REST or the AM console, you must specify the openid scope.

      The deprecated /oauth2/connect/register endpoint included the openid scope by default.

    • If the client_id and the client_secret values are specified in the registration request payload, AM ignores them and uses server-generated values in their place.

      Previously, these fields could be provided by the client in the registration request payload.

  • Removed Microsoft Live Social Authentication Wizard

    The wizard for configuring Microsoft Live as a social authentication providers has been removed in AM 5.5.

    To configure Microsoft Live as a social authentication provider, manually configure the following:

    • The OAuth 2.0 Provider service

    • The Social Authentication Implementation service

    • An OAuth 2.0 social authentication module

    • An authentication chain containing the module

    For more information on configuring these components, see Chapter 3, "Implementing Social Authentication" in the Authentication and Single Sign-On Guide.

4.2. Deprecated Functionality

Functionality listed under this section has been deprecated and will be removed in a future release of AM.

Access Management 5.5.1
  • No features have been deprecated in this release.

Access Management 5.5
  • OAuth 2.0 / OpenID Connect Authentication Module Deprecated

    The combined OAuth 2.0 / OpenID Connect authentication module is deprecated in this release.

    AM 5.5 provides replacement individual authentication modules. See Section 2.2.26, "Social Authentication Modules" in the Authentication and Single Sign-On Guide.

  • amverifyarchive Tool Deprecated

    The amverifyarchive tool will be removed in a future release of ForgeRock Access Management.

  • /oauth2/connect/register Endpoint Deprecated

    The /oauth2/connect/register endpoint has been deprecated. Use the /oauth2/register endpoint instead.

  • Use of Realm Paths to Specify Realm in REST Requests is Deprecated

    Using a realm path in the URL of a REST request as follows is now deprecated:

    $ curl 'https://openam.example.com:8443/openam/json/subrealmA/subrealmB/users/demo'

    This method for specifying realms is deprecated and will be removed in a future version.

    You must instead prefix each realm in the tree hierarchy with the realms keyword, and explicitly include the root realm, as follows:

    $ curl 'https://openam.example.com:8443/openam/json/realms/root/realms/subrealmA/realms/subrealmB/users/demo'

    Important

    This change applies to the following REST endpoint paths:

    • /json/*

    • /oauth2/*

    • /uma/*

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

4.3. Removed Functionality

Functionality listed under this section has been removed from AM.

Access Management 5.5.1
  • No features have been removed in this release.

Access Management 5.5
  • Removal of JWT as Authorization Grant Bearer Type

    AM has removed support for the JWT authorization grant bearer type as specified in Section 2.1 of RFC 7523, Using JWTs as Authorization Grants.

    AM continues to support Section 2.2, Using JWTs for Client Authentication, of RFC 7523. For more information, see Section 1.1.7, "JWT Bearer Profile" in the OAuth 2.0 Guide.

  • Removal of Crosstalk-related Properties

    The following system configuration properties have been removed from AM:

    • com.iplanet.am.session.failover.cluster.stateCheck.period

    • com.iplanet.am.session.failover.cluster.stateCheck.timeout

  • Removal of UrlAccessAgent

    The UrlAccessAgent user has been removed from AM and Amster.

  • Removal of AM SDK

    The AM SDK has been removed. This includes the Java com.iplanet.am.sdk package, which has been deprecated since Sun Java System Access Manager 7.1. The client detection service has also been removed.

    When you upgrade AM software, the following settings are removed:

    • Settings for running in coexistence mode with Sun Access Manager

    • com.iplanet.am.domaincomponent property settings

    • com.iplanet.am.sdk.ldap.debugFileName property settings

    • com.iplanet.am.sdk.userEntryProcessingImpl property settings

    • com.sun.identity.amsdk.cache.enabled property settings

  • Removed Client SDK Software

    Deprecated client SDK examples and libraries have been removed.

    Client applications can use the AM REST APIs instead, as documented in Chapter 2, "Developing with the REST API" in the Development Guide.

  • Removed Support for JDK 7

    AM 5.5 supports JDK 8 only. For more information, see Section 2.3, "Java Requirements".

  • Removed Support for Several Data Store Versions

    AM 5.5 does not support the following data store versions:

    • OpenDJ 2.6.x

    • Oracle Unified Directory 11g

    For more information, see Section 2.5, "Data Store Requirements".

  • Removed Support for Amazon Linux 2016.09

    AM now supports Amazon Linux AMI 2017.03. For more information, see Section 2.2, "Operating System Requirements".

  • Removed the ssoadm.jsp Page

    The deprecated ssoadm.jsp page has been removed.

  • Removed the Default Policy Agent, UrlAccessAgent

    The default policy agent, UrlAccessAgent, has been removed. Therefore, you need only to provide the amAdmin user password during AM installation.

    The --PolicyAgentPwd option has also been removed from the ssoadm command.

Chapter 5. Fixes, Limitations, and Known Issues

This chapter covers the status of key issues and limitations at release 5.5.

5.1. Key Fixes

Access Management 5.5.1
  • OPENAM-11988: HTTP 500 when validating SSO tokens if API version is omitted in AM 5.5

Access Management 5.5
  • OPENAM-11834: Passwords being set to empty strings in tabbed forms in XUI

  • OPENAM-11646: Cookie values wrapped in double quotes

  • OPENAM-11632: CDCServlet does not work with realm

  • OPENAM-11610: WindowSSO module broken in AM 5.1.1 after upgrade

  • OPENAM-11526: Realm Authentication chain post authentication classes PAP not triggered on chains with multiple modules

  • OPENAM-11391: Requesting 'OAuth2.0/OIDC' auth module a second time results in display of AM's "Authentication Failed" page

  • OPENAM-11300: OIDC request parameter is failing when message level is enabled

  • OPENAM-11280: authentication with noSession=true fails if post authentication plugin class is present

  • OPENAM-11218: OpenAM throws service error for Application Module

  • OPENAM-11217: SAML2 Authentication module is not invoking custom SP Adapter class implementing a preSingleSignOnRequest() method

  • OPENAM-11196: Incorrect debug logging level used in FMEncProvider.getEncryptionKey

  • OPENAM-11154: Memory leak in SMSEventListenerManager#subNodeChanges

  • OPENAM-11115: Push authentication should use alias attributes to find identities

  • OPENAM-11101: Social Auth links do not contain the goto url

  • OPENAM-11070: Need OAuth2 authentication to work in Android with implied consent

  • OPENAM-11057: Global User Self Service UI does not display values

  • OPENAM-11015: ForceAuth session upgrade does not work

  • OPENAM-10971: FR-OATH auth module can not be used in auth chain if the username in sharedstate map does not 'match' the search attribute of the data store

  • OPENAM-10970: logout response binding should be selected based on the capabilities of the SP

  • OPENAM-10965: Stateless OAuth2 can't verify access and refresh token

  • OPENAM-10931: IdentitySubject not adding isMember() result to cache after entry has changed.

  • OPENAM-10782: endSession with an id_token generated from a refresh_token request does not destroy the session

  • OPENAM-10756: setSucessModuleNames in AMLoginModule calls AuthModule's getPrincipal multiple times

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

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

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

  • OPENAM-10332: Quota constraints exceeded - Interim Fix

  • OPENAM-10129: OAuth2 Device flow - user code verification is case insensitive

  • OPENAM-10103: output from re-indexing action during initial configuration is lost

  • OPENAM-10102: insufficient progress information during configuration

  • OPENAM-10013: HOTP session upgrade not possible in XUI if the wrong code is entered first time

  • OPENAM-9979: Authentication chain post authentication classes are not used if realm level PAP setting exists

  • OPENAM-9885: Oauth2 load: Tomcat keeps logging "WARNING: Addition of the standard header "Pragma" is discouraged as a future version of the Restlet API will directly support it"

  • OPENAM-9156: 'Not Found' error in UI when opening a custom auth module created with ssoadm with the name the same as type

  • OPENAM-8771: "Unknown Error: Please contact your administrator", shown with FacebookSocialAuthentication option "Prompt for password setting and activation code" (org-forgerock-auth-oauth-prompt-password-flag)

  • OPENAM-8270: Using client_credentials Grant type with openid scope returns User must be authenticated to issue ID tokens

  • OPENAM-8063: Merge Debug Files feature does not work correctly

  • OPENAM-7781: persistent cookie auth module does not allow to change cookie name by default

  • OPENAM-7437: Finish button of Identity Provider wizard doesn't work

  • OPENAM-5864: Quota constraints exceeded in multi-instance with LB and CTS enabled

  • OPENAM-5153: Auth modules should call setAuthLevel after successful login

  • OPENAM-5152: AMAuthLevelManager miscalculates auth level

  • OPENAM-3679: IDP Finder fails to validate relaystate

  • OPENAM-1325: OpenAM fails to setup when deployed under the root uri ( '/' )

5.2. Limitations

The following limitations and workarounds apply to AM 5.5:

  • Server Error When OAuth 2.0 or OpenID Connect Clients Request Access Tokens

    OAuth 2.0 or OpenID Connect client using HMAC for signing JSON web tokens may encounter the following issues:

    • REST calls requesting access tokens return server_error

    • There are errors in AM's logs resembling the following:

      ERROR: Failed to update JwkStore for jwks URI https://openam.example.com:8443/am/oauth2/customers/connect/jwk_uri
      org.forgerock.json.jose.exceptions.FailedToLoadJWKException: Unable to load the JWK location over HTTP
      at org.forgerock.json.jose.jwk.JWKSetParser.gatherHttpContents(JWKSetParser.java:84)
      at org.forgerock.json.jose.jwk.JWKSetParser.jwkSet(JWKSetParser.java:96)
      at org.forgerock.json.jose.jwk.store.JwksStore.reloadJwks(JwksStore.java:85)
      

    To work around this issue, navigate to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > Signing and Encryption and perform one of the following steps:

    • Leave the Json Web Key URI field blank, removing the default value. HMAC signing does not require a JWK URI.

    • Ensure the URL specified in the Json Web Key URI field is resolvable.

  • Using the Documented CORS Filter With IDM Integration Causes Errors

    When configuring IDM to delegate authentication to AM, as described in the IDM Samples Guide, you must configure AM with a cross-origin resource sharing (CORS) filter.

    However, when you use a CORS filter based on the org.forgerock.openam.cors.CORSFilter filter class, Unexpected End of JSON Input errors occur.

    To work around the problem, configure AM's web.xml file as described in Section 1.2.5, "Enabling CORS Support" in the Installation Guide, but use a CORS filter specific to the AM web container instead of using a filter based on the org.forgerock.openam.cors.CORSFilter filter class. For example, for Apache Tomcat, use a filter based on the org.apache.catalina.filters.CorsFilter filter class:

    • Add a filter clause similar to the following to the web.xml file, making sure to specify the correct URLs for your deployment in the cors.allowed.origins parameter:

      <filter>
          <filter-name>CORSFilter</filter-name>
          <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
          <init-param>
              <param-name>cors.allowed.headers</param-name>
              <param-value>Content-Type,X-OpenIDM-OAuth-Login,X-OpenIDM-DataStoreToken,X-Requested-With,Cache-Control,Accept-Language,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,X-OpenAM-Username,X-OpenAM-Password,iPlanetDirectoryPro</param-value>
          </init-param>
          <init-param>
              <param-name>cors.allowed.methods</param-name>
              <param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>
          </init-param>
          <init-param>
              <param-name>cors.allowed.origins</param-name>
              <param-value>https://openam.example.com:8443,https://openidm.example.com:8443</param-value>
          </init-param>
          <init-param>
              <param-name>cors.exposed.headers</param-name>
              <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials,Set-Cookie</param-value>
          </init-param>
          <init-param>
              <param-name>cors.preflight.maxage</param-name>
              <param-value>10</param-value>
          </init-param>
          <init-param>
              <param-name>cors.support.credentials</param-name>
              <param-value>true</param-value>
          </init-param>
      </filter>
      
    • Add the following filter-mapping clause to the web.xml file:

      <filter-mapping>
          <filter-name>CORSFilter</filter-name>
          <url-pattern>/json/*</url-pattern>
      </filter-mapping>
      
  • JCEKS Keystore Support for User Self-Services

    In OpenAM 13.0.0, the user self-service feature is stateless, which means that the end-user is tracked and replayed by an encrypted and signed JWT token on each AM instance. It also generates key pairs and caches its keys locally on the server instance.

    In a multi-instance deployment behind a load balancer, one server instance with the user self-services enabled will not be able to decrypt the JWT token from the other instance due to the encryption keys being stored locally to its server.

    OpenAM 13.5.0 and later solve this issue by providing a JCEKS keystore that supports asymmetric keys for encryption and symmetric keys for signing. Users who have installed OpenAM 13.0.0 and enabled the user self-service feature will need to run additional steps to configure a JCEKS keystore to get the user self-service feature operating after an upgrade.

    For specific instructions to configure the JCEKS keystore, see Section 5.2, "Configuring Keystores" in the Setup and Maintenance Guide.

    Note

    This procedure is not necessary for the following users:

    • Users upgrading from versions prior to OpenAM 13.0.0 are not impacted.

    • Users who upgrade from OpenAM 13.0.0 and do not enable the user self-services feature are not impacted.

    • Users who do a clean install of OpenAM 13.5.0 or later are not impacted.

  • Cached JavaScript Files from OpenAM 12.0.0 May Cause Redirect to undefined:8080

    If you configure an OpenAM 12.0.0 instance with long-lived cache times for the /XUI/index.html file, you may experience unexpected redirects to undefined:8080 after upgrading.

    To work around this issue, in your chosen web container, or proxy server, reconfigure the cache time for the /XUI/index.html file to be short-lived, for example, 5 minutes. Allow enough time that cached files with the long-lived cache time will have expired before upgrading.

    Note

    This issue does not affect upgrades from OpenAM 12.0.1 or later. OpenAM 12.0.1 and later set a short-lived cache-control header on UI files to work around the problem of having stale files cached locally.

  • RADIUS Service Only Supports Commons Audit Logging. The new RADIUS service only supports the new Commons Audit Logging, available in this release. The RADIUS service cannot use the older Logging Service, available in releases prior to OpenAM 13.0.0.

  • Administration Console Access Requires the RealmAdmin privilege

    In this version of AM, administrators can use the AM console as follows:

    • Delegated administrators with the RealmAdmin privilege can access full AM console functionality within the realms they can administer. In addition, delegated administrators in the Top Level Realm who have this privilege can access AM's global configuration.

    • Administrators with lesser privileges, such as the PolicyAdmin privilege, can not access the AM administration console.

    • The top-level administrator, such as amadmin, has access to full AM console functionality in all realms and can access AM's global configuration.

  • OAuth2 Scopes Behavior Affected by Upgrade

    After an upgrade from OpenAM 12.0.x, OAuth v2.0 scope behavior uses a deprecated implementation class, org.forgerock.openam.oauth2.provider.impl.ScopeImpl.

    The workaround is to manually update the OAuth v2.0 providers to use the org.forgerock.openam.oauth2.OpenAMScopeValidator.

    For background information, see OPENAM-6319.

  • Supported ID Token Algorithms and Methods not Updated After Upgrade

    AM 5 added additional algorithms and methods for encrypting ID tokens. Performing an upgrade from OpenAM 13.5 does not add these new values to the affected properties.

    After upgrade, navigate to Realm Name > Services > OAuth2 Provider > OpenID Connect, and manually update the ID Token Encryption Algorithms supported and ID Token Encryption Methods supported properties.

    For more information on the available algorithms and methods, see Section 2.8, "Encrypting OpenID Connect ID Tokens" in the OpenID Connect 1.0 Guide.

  • Different AM Version Within a Site

    Do not run different versions of AM together in the same AM site.

  • Avoid use of Special Characters in Policy or Application Creation

    Do not use special characters within policy, application or referral names (for example, "my+referral") using the Policy Editor or REST endpoints as AM returns a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), command (,), less than (<), equals (=), greater than (>), backslash (\), and null (\u0000). (OPENAM-5262)

  • XACML Policy Import and Export

    AM can only import XACML 3.0 files that were either created by an AM instance, or that have had minor manual modifications, due to the reuse of some XACML 3.0 parameters for non-standard information.

  • Custom Profile Attributes Are Not Visible in the User Profile Only With the XUI

    Custom profile attributes do not appear in the user profile when users log in to AM using the XUI.

5.3. Known Issues

The following important known issues remained open at the time release 5.5 became available. For details and information on other issues, see the issue tracker.

Access Management 5.5
  • OPENAM-11980: Social OIDC wizards do not work when provisioning accounts locally

  • OPENAM-11956: SAML2 RelayState values are seen as invalid if they are not a URL which appears to go against the spec

  • OPENAM-11937: Federation UI does not allow empty NameIDMappingService

  • OPENAM-11925: CORSFIlter causings failures after moving to 5.x from 13.5.x

  • OPENAM-11921: Incorrect NameId Format offered for SAML2 auth module in console

  • OPENAM-11746: Syslog data is not fully RFC compliant

  • OPENAM-11741: NPE in admin console when accessing parts with old UI

  • OPENAM-11737: http.response.headers not populating in audit logs

  • OPENAM-11194: Goto url not used in the presence of a valid session or after a redirect callback

  • OPENAM-9931: Global Session Service - two fields with the exact same name

  • OPENAM-9012: LDAP connection heartbeat settings should be also added to policy configuration

  • OPENAM-4713: Can't use Common Tasks wizards when logged in as a delegated administrator

Chapter 6. Documentation Updates

The following table tracks changes to the documentation set following the release of AM 5.5:

Table 6.1. Documentation Change Log
DateDescription
2017-10-31

Added information about the need to update the script or Maven pom.xml file used to build a custom authentication module when the module uses a service loader. See Section 4.1, "Important Changes to Existing Functionality".

2017-10-27

Initial release of Access Management 5.5.1

2017-10-23

Initial release of Access Management 5.5.


Appendix A. Release Levels and Interface Stability

This appendix includes ForgeRock definitions for product release levels and interface stability.

A.1. ForgeRock Product Release Levels

ForgeRock defines Major, Minor, and Maintenance product release levels. The release level is reflected in the version number. The release level tells you what sort of compatibility changes to expect.

Table A.1. Release Level Definitions
Release LabelVersion NumbersCharacteristics

Major

Version: x[.0.0] (trailing 0s are optional)

  • Bring major new features, minor features, and bug fixes

  • Can include changes even to Stable interfaces

  • Can remove previously Deprecated functionality, and in rare cases remove Evolving functionality that has not been explicitly Deprecated

  • Include changes present in previous Minor and Maintenance releases

Minor

Version: x.y[.0] (trailing 0s are optional)

  • Bring minor features, and bug fixes

  • Can include backwards-compatible changes to Stable interfaces in the same Major release, and incompatible changes to Evolving interfaces

  • Can remove previously Deprecated functionality

  • Include changes present in previous Minor and Maintenance releases

Maintenance

Version: x.y.z

  • Bring bug fixes

  • Are intended to be fully compatible with previous versions from the same Minor release


A.2. ForgeRock Product Interface Stability

ForgeRock products support many protocols, APIs, GUIs, and command-line interfaces. Some of these interfaces are standard and very stable. Others offer new functionality that is continuing to evolve.

ForgeRock acknowledges that you invest in these interfaces, and therefore must know when and how ForgeRock expects them to change. For that reason, ForgeRock defines interface stability labels and uses these definitions in ForgeRock products.

Table A.2. Interface Stability Definitions
Stability LabelDefinition

Stable

This documented interface is expected to undergo backwards-compatible changes only for major releases. Changes may be announced at least one minor release before they take effect.

Evolving

This documented interface is continuing to evolve and so is expected to change, potentially in backwards-incompatible ways even in a minor release. Changes are documented at the time of product release.

While new protocols and APIs are still in the process of standardization, they are Evolving. This applies for example to recent Internet-Draft implementations, and also to newly developed functionality.

Deprecated

This interface is deprecated and likely to be removed in a future release. For previously stable interfaces, the change was likely announced in a previous release. Deprecated interfaces will be removed from ForgeRock products.

Removed

This interface was deprecated in a previous release and has now been removed from the product.

Internal/Undocumented

Internal and undocumented interfaces can change without notice. If you depend on one of these interfaces, contact ForgeRock support or email info@forgerock.com to discuss your needs.


Appendix B. Getting Support

For more information or resources about AM and ForgeRock Support, see the following sections:

B.1. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

B.2. Using the ForgeRock.org Site

The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

B.3. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, classes through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Read a different version of :