PingAM release notes

Changes in AM 7.1.x

Critical changes in AM 7.1

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

By default, AM 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.

One-time passwords stored in transient state

One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient state, instead of in the shared state.

Modify any custom authentication nodes or scripts used by the Scripted Decision node to retrieve the one-time passwords from the transient state after upgrading.

Changes to OAuth 2.0 and OIDC script bindings

The format for the following script bindings changed for this release:

requestUri

Old format: String

New format: String with query parameters; for example, http://openam.example.com:8080/openam/oauth2/authorize?test=test

requestParams

Old format: String

New format: Each parameter is returned as an array; for example, grant_type:[authorization_code]

Important changes in AM 7.1.x

AM 7.1.3
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.

Base URL X-Forwarded-* headers

Previously, if you set the Base URL source to X-Forwarded-* headers and no X-Forwarded-Proto header was provided, the generated URL would have a protocol of null, for example null://host, which would result in a broken URL.

From this release, if no X-Forwarded-Proto header is provided, a fallback scheme is used, based on the URI of the request.

  • You can now specify a port in the Base URL, using the X-Forwarded-Port header.

  • If multiple X-Forwarded-Host headers are specified, the outermost proxy host is used.

AM 7.1.2
Java agent property name changes

The Java agent property names have changed in the AM admin UI. The new names reflect the names now used in the Java agent documentation.

Summary of new names
Old Name New Name

Accept SSO Tokens

Enable SSO Token Acceptance

Agent Configuration Change Notification

Enable Notifications of Agent Configuration Change

Agent Filter Mode

Agent Filter Mode Map

Allow Custom Login Mode

Enable Custom Login Mode

AM Conditional Login URL

OAuth Login URL List

AM Conditional Logout URL

Conditional Logout URL List

AM Login URL

AM Login URL List

Application Logout URI

Logout URI Map

Attribute Cookie Encode

Enable Attribute Encoding

Authentication Fail Reason Url

Authentication Fail URL

CDSSO Domain List

JWT Cookie Domain List

CDSSO Redirect URI

Authentication Redirect URI

Continuous Security Cookies

Continuous Security Cookie Map

Continuous Security Headers

Continuous Security Header Map

Convert SSO Tokens into OpenID Connect JWTs

Convert SSO Tokens Into OIDC JWTs

Cookies Reset Domain Map

Reset Cookie Domain Map

Cookies Reset Name List

Reset Cookie List

Cookies Reset Path Map

Reset Cookie Path Map

Custom Conditional Login URL

Legacy Login URL List

Custom Response Header

Custom Response Header Map

Encode Cookies

Enable Encoded Cookies

Exchanged SSO Token Cache Size

Max Entries in SSO Exchange Cache

Exchanged SSO Token Cache Time to Live

Exchanged SSO Token Cache TTL

Expired Session Cache Max Records

Max Entries in Expired Session Cache

FQDN Check

Enable FQDN Checking

FQDN Default

Default FQDN

HTTP 302 Redirect Not Enforced List

HTTP 302 Redirect Not-Enforced List

HTTP 302 Redirect Replacement HTTP Code

HTTP 302 Redirect Replacement HTTP Status Code

HTTP 302 Redirects Enabled

Enable HTTP 302 Redirects

Http Only

Enable HTTP Only Cookies

Invert Not Enforced IPs

Invert Not-Enforced IPs

Invert Not Enforced URIs

Invert Not-Enforced URIs

JWT Cache Size

Max Entries in JWT Cache

Legacy User Agent Support Enable

Enable Legacy Support Handlers

Load Balancer Cookie Enabled

Enable Load Balancer Cookies

Login Form URI

Login Form URI List

Logout Entry URI

Logout Entry URI Map

Logout Introspect Enabled

Enable Logout Introspection

Logout Request Parameter

Logout Request Parameter Map

Missing PDP entry URI

Missing POST Data Preservation Entry URI Map

Not Enforced Client IP List

Not-Enforced Client IP List

Not Enforced Favicon

Not-Enforced Favicon

Not Enforced IP Cache Flag

Enable Not-Enforced IP Cache

Not Enforced IP Cache Size

Max Entries in Not-Enforced IP Cache

Not Enforced URIs Cache Enabled

Enable Not-Enforced URIs Cache

Not Enforced URIs Cache Size

Max Entries in Not-Enforced URI Cache

Not Enforced URIs

Not-Enforced URIs

PDP Cache TTL in Minutes

POST Data Preservation Cache TTL

PDP Maximum Cache Size

POST Data Preservation Cache Size

PDP Maximum Number of Cache Entries

Max Entries in POST Data Preservation Cache

PDP Stickysession key-value

POST Data Preservation Sticky Session Key Value

PDP Stickysession mode

POST Data Preservation Sticky Session Mode

Perform Policy Evaluation in User Authenticated Realm

Enable Policy Evaluation in User Authentication Realm

Policy Cache Per User

Max Entries in Policy Cache per Session

Policy Cache Size

Max Sessions in Policy Cache

Policy Evaluation Realm

Policy Evaluation Realm Map

Policy Set

Policy Set Map

Port Check Enable

Enable Port Checking

Port Check File

Port Check Filename

Port Check Setting

Port Check Protocol Map

Possible XSS code elements

XSS Code Element List

Post Data Preservation enabled

Enable POST Data Preservation

Pre-Authenticated Cookie Max Age

Max Age of Pre-Authentication Cookie

Pre-Authenticated Cookie Name

Pre-Authentication Cookie Name

Profile Attribute Mapping

Profile Attribute Map

Regular Expression Remove Query Parameters

Regex Remove Query Parameters List for Policy Evaluation

Remove Query Parameters

Remove Query Parameters List for Policy Evaluation

Resource Access Denied URI

Access Denied URI Map

Response Attribute Mapping

Response Attribute Map

Restrict To Realm

Restrict to Realm Map

Retain Query Parameters

Query Parameter List for Policy Evaluation

Rotate Local Audit Log

Enable Local Audit Log Rotation

Samesite Cookie Attributes Excluded User Agents Pattern List

Exclude Agents From Samesite Cookie Attributes

Session Attribute Mapping

Session Attribute Map

URL Policy Env GET Parameters

GET Parameter List for URL Policy Env

URL Policy Env jsession Parameters

JSession Parameter List for URL Policy Env

URL Policy Env POST Parameters

POST Parameter List for URL Policy Env

User Principal Flag

Enable User Principal Flag

User Token Name

User Session Name

XSS detection redirect URI

XSS Redirect URI Map
AM 7.1.1
Connections made by the CTS

OPENAM-13855 corrected an issue where the CTS was creating too many connections to DS. This fix might imply that the number of connections created is now different in your deployment, corrected to be the expected number of connections. Monitor your environments to ensure that this corrected number of connections is sufficient, and increase it if necessary.

Delegated admin can now query user profile attributes

Admin privileges have been changed to let a delegated admin read user profile attributes. For example, this request returns the OAuth 2.0 applications that have been authorized by the demo user:

curl --request GET \
'http://openam.example.com:8443/openam/json/users/demo/oauth2/applications?_queryFilter=true'
OAuth 2.0 token introspection

The OAuth2 token introspection response is now compliant with RFC 7662 and returns a username rather than a user_id.

The expires_in value returned from OAuth 2.0 endpoints

AM 7.1.1 changes the way the /oauth2/introspect and the /oauth2/tokeninfo endpoints return the value of the expires_in object.

The expires_in object specifies the time, in seconds, that a token is valid for. For example, 3600 seconds. This value is set at token creation time, and it depends on the configuration of the OAuth2 Provider Service.

When providing a token introspection or token information response, earlier versions of AM returned the value of the expires_in object as it was stored in the token. This means that any call to the endpoints while the token is valid returned the same value for the expires_in object.

AM 7.1.1 calculates the amount of seconds the token is still valid for and returns this value in the expires_in object. Therefore, repeated calls to the endpoints return different values for the object.

However, the actual value of the expires_in object in the token does not change. Inspecting the token without using AM will show the value set at token creation time.

The expires_in object is not always present in the endpoint response:

Introspection endpoint

AM only returns the expires_in object for client-based tokens issued to a client configured in the same realm as the resource owner’s.

Token information endpoint

AM does not return the expires_in object for client-based tokens issued to a client configured in a different realm than the resource owner’s.
The OIDC /oauth2/userinfo endpoint return values

AM 7.1.1 changes when the aud and iss objects are returned in the JWT response of the OIDC /oauth2/userinfo endpoint.

Earlier versions of AM returned the iss object when the user information response was a signed, encrypted, or a signed and encrypted JWT. The aud object was never returned.

AM 7.1.1 now returns both the aud and iss objects when response is a signed, or a signed and encrypted JWT, according to the OpenID Connect Core 1.0 incorporating errata set 1 specification.

The iss object is no longer returned when the response is an encrypted JWT.

AM 7.1
AM-SESSION-DESTROYED no longer logged

In previous AM releases, session timeout triggered two events. This could cause AM to send two logout tokens on a timeout, if an OAuth 2.0 client was registered for back-channel logout notifications on the session.

With this change, a session is still destroyed on timeout but this is done as part of the timeout event, and the AM-SESSION-DESTROYED activity is not logged.

SAML v2.0 IdP discovery service redirection URLs

The IdP discovery service now includes a mandatory field to configure valid redirection URLs; for example, the URLs of the SPs configured in the CoT to which the discovery service belongs.

After upgrading to AM 7.1, you must:

  • Redeploy the IdP discovery application and reconfigure it to include the valid redirection URLs.

  • Configure the valid redirection URLs in the Validation Service of each of the IdPs, in the Top Level Realm.

For more information, refer to:

  • Deploying the IdP Discovery Service

  • To Configure the Validation Service

Example remote consent service and secret stores

The remote consent service example has been migrated to use AM’s secret store functionality.

As part of this change, the signing and encryption fields have been removed in the global and realm service configurations. The following secret IDs have been created in their place:

For details, refer to The Remote Consent Service.

If you configured the remote consent service example before upgrading, the upgrade process will migrate any secret configuration available to global or realm secret stores.

sub claim in access and ID tokens

The subject claim of access tokens and ID tokens has changed formats to ensure that it is locally unique, as required by the OpenID Connect specification. The new Backchannel logout tokens also use the new format.

The subject claim is in the format (type!subject), where:

  • subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

  • type can be one of the following:

    • age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.

    • usr. Specifies that the subject is a user/identity.

      For example, (usr!demo), or (age!myOAuth2Client).

Clients that use the sub claim to determine the identity about which the token asserts information are impacted by this change.

To make transitioning to the new format easier, AM 7.1 also includes the following:

  • A new advanced server property, org.forgerock.security.oauth2.enforce.sub.claim.uniqueness.

    This property controls whether AM should create tokens using the new sub claim format or not, and it is disabled after an upgrade to AM 7.1, and enabled in new installations.

    Tokens using the old sub format will still be accepted after the property is enabled. However, earlier versions of AM cannot read tokens with the new format.

  • A new claim: subname.

    The value of the subname claim matches the value of the sub claim used in versions of AM earlier than 7.1. It also matches the value of the sub claim if you disable the org.forgerock.security.oauth2.enforce.sub.claim.uniqueness property.

    An example of the value of the subname claim is demo, or myOauth2Client.

    AM adds the subname claim to access and logout tokens regardless of the configuration of the new advanced server property. The claim is also available to ID tokens, but it is not included in the OIDC Claims Script. Therefore, AM does not add it to ID tokens by default.

Before you enable the advanced server property, make sure that your clients can use the new sub claim format, or a combination of the sub and the subname claims.

Maximum size of decompressed JWTs enforced

A number of AM features accept JWTs to receive information. Some examples are:

  • The Remote Consent service, when it receives consent responses.

  • The OAuth 2.0/OpenID Connect authorization service, when:

    • OpenID Connect clients send request parameters as an encrypted JWT instead of as HTTP parameters.

    • OpenID Connect clients register dynamically using software statements.

  • The Authentication service, when configured to issue client-based sessions.

These JWTs that AM receives can be signed and/or encrypted. Sometimes, if they are fairly large, they can also be compressed so that requests reach AM faster. Decompressing a JWT makes it expand in size. By default, AM 7.1 rejects any JWT that expands to more than 32 KiB (32768 bytes). Before upgrade, ensure that the decompressed JWTs your clients send to AM are smaller than 32 KiB before compression.

If they are not, change the default value to a larger number after upgrade. For information about changing the 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 7.1 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.

Web and Java agent profiles

  • Web agents

    Added properties

    AM Load Balancer Cookie Enabled (com.forgerock.agents.config.add.amlbcookie)

    Renamed properties

    The Agent Profile ID Whitelist property is now Agent Profile ID Allow List.

  • Java agents

    Added properties

    • Load Balancer Cookie Enabled (org.forgerock.agents.load.balancer.cookies.enabled)

    • Load Balancer Cookie Name (org.forgerock.agents.load.balancer.cookie.name)

    • Client IP Validation Mode (org.forgerock.agents.original.ip.check.mode.map)

    • Client IP Validation Address Range (org.forgerock.agents.acceptable.ip.address.map)

    • Perform Policy Evaluation in User Authenticated Realm (org.forgerock.agents.user.realm.overrides.policy.evaluation.realm.enabled)

    • Accept SSO Tokens (org.forgerock.agents.accept.sso.tokens.enabled)

    • SSO Cookie Domain List (org.forgerock.agents.ipdp.cookie.domain.list)

    • Expired Session Cache Timeout (org.forgerock.agents.sso.expired.session.cache.ttl.minutes)

    • Expired Session Cache Max Records (org.forgerock.agents.expired.session.cache.size)

    • HTTP 302 Redirects Enabled (org.forgerock.agents.302.redirects.enabled)

    • HTTP 302 Redirect Replacement HTTP Code (org.forgerock.agents.302.redirect.http.status.code)

    • HTTP 302 Redirect Content Type (org.forgerock.agents.302.redirect.http.content.type)

    • HTTP 302 Redirect Data (org.forgerock.agents.302.redirect.http.data)

    • HTTP 302 Redirect Not Enforced List (org.forgerock.agents.302.redirect.ner.list)

    • HTTP 302 Redirect Invert Not Enforced List (org.forgerock.agents.302.redirect.invert.enabled)

    Renamed properties

    The CDSSO Secure Enable property is now Transmit Cookies Securely.

    Removed properties

    • Secure Cookies (org.forgerock.agents.jwt.cookie.secure.enabled)

    • Session Logout Notification (org.forgerock.agents.session.change.notifications.enabled)

    • Debug Logfile Directory (com.iplanet.services.debug.directory)

    • Audit Logfile Path (org.forgerock.agents.local.audit.file.path)

    • Service Resolver Class Name (org.forgerock.agents.service.resolver.class.name)

OpenID Connect Discovery endpoint disabled by default

The /.well-known/webfinger OpenID Connect discovery endpoint is now disabled by default, and can only be enabled by realm.

To enable the endpoint for a realm, configure the OAuth2 Provider service on the realm and next, enable the new OIDC Provider Discovery switch. Enabling the endpoint for the realm allows searches for users within that realm only.

After upgrading to AM 7.1, the endpoint will be enabled on realms that had the OAuth2 Provider service configured. Disable the endpoint on those realms that are not using OpenID Connect discovery.

For details, refer to OpenID Connect Discovery.

OAuth 2.0 and OpenID Connect clients

AM 7.1 returns an error if the administrator tries to save a client configuration containing an unsupported signing or encryption algorithm.

For example, upon saving the configuration, AM will return an error if there is a typo on an algorithm, or a symmetric signing or encryption algorithm is configured on a public client: these algorithms are derived from the client’s secret, which public clients do not have.

Clients registering dynamically must also send supported algorithms as part of their configuration, or AM will reject the registration request.

Different features support different algorithms. Refer to the documentation or to the UI for more information.

The following are examples of the errors:

  • Unknown encryption algorithm configured for User info encrypted response algorithm

  • Symmetric encryption algorithm configured for ID Token Encryption Algorithm is not allowed for a public client

The error messages are also logged at ERROR level, and identify the client ID to which the error relates.

One-time passwords stored in transient state

One-time passwords created by the HOTP Generator node are now stored in the authentication tree’s transient state, instead of in the shared state.

Modify any custom authentication nodes or scripts used by the Scripted Decision node to retrieve the one-time passwords from the transient state after upgrading to AM 7.1.

For details, refer to Storing Values in a Tree’s Node States.

Changes to the TreeContext class

AM 7.1 introduces the following changes to the TreeContext class:

  • New method added to preserve the secureState for internal nodes contained in a Page node: public TreeContext copyWithCallbacksAndState(JsonValue sharedState, JsonValue transientState, JsonValue secureState, List<? extends Callback> callbacks)

  • New method added to provide nodes with access to secureState: public TreeContext copyWithCallbacks(List<? extends Callback> callbacks)