PingAM release notes

Changes in AM 6.5.x

AM 6.5.5

Access to the API Explorer

For security reasons, access to the /api endpoint, and thus, to the API Explorer, is now disabled by default. For instructions on enabling the API Explorer, see "Introducing the API Explorer" in the Development Guide.

OAuth 2.0 introspection changes

HTTP GET requests are now disallowed on the /oauth2/introspect endpoint by default. Using token as a query parameter on this endpoint is also disallowed. To change this behavior to suit existing clients, use the org.forgerock.openam.introspect.token.query.param.allowed advanced server property.

AM 6.5.4

Chain authentication forceAuth flag

In the chain authentication settings for new and upgraded AM installations, the ForceAuth flag is enabled by default. This default setting will be incompatible with future AM versions, and may cause insecure behavior in some configurations.

If you are using authentication trees, or if you don’t require ForceAuth to be enabled, then manually set ForceAuth to false now. In the AM admin UI, go to Configure > Server Defaults > Advanced. For details, refer to Authentication Parameters.

Splunk audit handler configuration

An authorization token in this configuration was stored in plain text in previous versions. Now the token is encrypted when saved. For additional security, re-import and then re-export your Splunk configuration.

Decompressed JWTs

By default, AM rejects any JWT that expands to more than 32 KiB (32768 bytes) when decompressed. For information about changing this default value, refer to Controlling the Maximum Size of Compressed JWTs.

Maximum request body size

Application servers can usually mitigate against DoS attacks that POST large amounts of form data, but AM endpoints may receive large amounts of POST data in different ways, such as in JSON, JWT, or JWK formats.

By default, AM 6.5.4 rejects incoming requests with a body larger than 1 MB (1048576 bytes) in size, and returns an HTTP 413 error response.

For information about changing the default value, refer to Limiting the Size of the Request Body.

OAuth 2.0 and OpenID Connect clients

This change affects AM when acting as an OAuth 2.0 or OpenID Connect client.

If a redirection URI uses a scheme, host, or port that differs from that of AM, add it to the Validation Service to ensure that it is pre-approved.

Otherwise, AM rejects the URI, and redirection fails. For details, refer to Configuring Success and Failure Redirection URLs.

Retry Limit Decision node

The new Save Retry Limit to User option in this node is disabled by default after upgrade. For security reasons, it is strongly recommended that you enable this option after upgrade. Enabling the option requires an update to the identity store schema.

AM 6.5.3

OIDC ID token encryption

In AM 6.5.3, the OAuth 2.0 idTokenEncryptionAlgorithm setting determines how an OIDC ID token gets encrypted.

In 6.0.0 and earlier versions, the com.forgerock.openam.oauth2provider.idTokenSignedResponseAlg value in the OAuth 2.0 client administration endpoint determines how the OIDC ID token gets encrypted.

When you upgrade from version 6.0 or earlier to version 6.5.3 or later, entering an unsupported value for idTokenEncryptionAlgorithm may result in errors. For a list of supported values, refer to ID Token Encryption Algorithms supported.

goto and gotoOnFail query parameter redirection

Redirection URLs for authentication services, agents, and SAML v.2.0 must be configured in the Validation Service if they are not in the same scheme, FQDN, and port as AM, or are not relative to AM’s URL.

/json/authenticate endpoint

When a client makes a call to the /json/authenticate endpoint appending a valid SSO token, AM now returns an empty tokenId field when HttpOnly cookies are enabled. For example:

{
    "tokenId":"",
    "successUrl":"/openam/console",
    "realm":"/"
}

SAML v2.0 assertion consumer service

SAML v2.0 assertion consumer service URLs must exactly match the SP’s scheme, FQDN, and port.

SAML v2.0 RelayState redirection

To redirect to a domain outside of AM’s deployment domain, you must add it to the Relay State URL List whitelisting property of the SP or IDP.

AM 6.5.0.2 and AM 6.5.1

OAuth 2.0 refresh tokens

AM only issues refresh tokens to clients that have the refresh token grant type configured in their client profile.

After an upgrade to 6.5 or later using the UI or the openam-upgrade-tool .jar file, existing OAuth 2.0 clients are configured to use all grant flows, including the Refresh Token Grant flow.

To configure the refresh token grant type manually, refer to To Configure AM to Issue Refresh Tokens.

AM 6.5.0

Recovery codes

Recovery codes are encrypted, and existing codes are no longer displayed to the user. For details, refer to Upgrading Device Recovery Codes.

Secret stores

AM 6.5 introduced secret stores for OAuth 2.0 and the persistent cookie module. The upgrade process only creates the secret store files on the AM instance where you ran the upgrade process. For details, refer to Configuring Secret Stores After Upgrade.

External configuration stores

DS 6.5 introduced setup profiles, which pre-configure instances for different usages, such as CTS or configuration data. The default base DN for a DS configuration store instance (ou=am-config) is different to the default used by previous versions of AM (dc=openam,dc=forgerock,dc=org).

Do not run multiple instances of AM where the configuration store base DNs do not match. Use the same configuration store base DNs when configuring external DS 6.5+ instances that will be used simultaneously alongside existing DS 6 or earlier configuration store instances.

For more information, refer to Preparing Configuration Stores.

Amster

The Amster-config-upgrader utility was removed in this release. Upgrade AM following the procedures in the Upgrade Guide, then export the configuration from the upgraded instance or site using Amster. For more information, see the following Knowledge Base article.