PingGateway 2024.11

AmService

Holds information about the configuration of an instance of AM. The AmService is available to PingGateway filters that communicate with that instance.

When PingGateway uses an AmService, PingGateway is positioned as the client of the service. By default, PingGateway is subscribed to Websocket notifications from AM, and the WebSocket connection can be secured by ClientTlsOptions.

Usage

{
  "name": string,
  "type": "AmService",
  "config": {
    "agent": {
      "username": configuration expression<string>,
      "passwordSecretId": configuration expression<secret-id>
    },
    "secretsProvider": SecretsProvider reference,
    "url": configuration expression<url>,
    "realm": configuration expression<string>,
    "amHandler": Handler reference,
    "notifications": {
      "enabled": configuration expression<boolean>,
      "initialConnectionAttempts": configuration expression<number>,
      "reconnectDelay": configuration expression<duration>,
      "renewalDelay": configuration expression<duration>,
      "heartbeatInterval": configuration expression<duration>,
      "connectionTimeout": configuration expression<duration>,
      "idleTimeout": configuration expression<duration>,
      "tls": ClientTlsOptions reference,
      "proxyOptions": ProxyOptions reference,
      "vertx": object
    },
    "sessionCache": {
      "enabled": configuration expression<boolean>,
      "executor": Executor service reference,
      "maximumSize": configuration expression<number>,
      "maximumTimeToCache": configuration expression<duration>,
      "onNotificationDisconnection": configuration expression<enumeration>
    },
    "sessionIdleRefresh": {
      "enabled": configuration expression<boolean>,
      "interval": configuration expression<duration>
    },
    "sessionProperties": [ configuration expression<string>, …​ ],
    "ssoTokenHeader": configuration expression<string>,
    "version": configuration expression<string>
  }
}

Properties

agent

"agent": object, required

An PingGateway agent profile. When the agent is authenticated, PingGateway can use the token for tasks, such as getting the user profile, making policy evaluations, and connecting to the AM notification endpoint.

"username": configuration expression<string>, required

Name of the AM agent profile.

"passwordSecretId": configuration expression<secret-id>, required

The secret ID of the AM agent password.

This secret ID must point to a GenericSecret.

secretsProvider

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for the agent password.

url

"url": configuration expression<url>, required

The URL of the AM service.

When AM is running locally, this value could be https://am.example.com/openam. When AM is running in PingOne Advanced Identity Cloud, this value could be https://myTenant.forgeblocks.com/am.

realm

"realm": configuration expression<string>, optional

The AM realm in which the PingGateway agent is created.

Default: / (top level realm).

amHandler

"amHandler": Handler reference, optional

The Handler to use for communicating with AM. In production, use a ClientHandler capable of making an HTTPS connection to AM.

AmService doesn’t use amHandler to subscribe to WebSocket notifications from AM. To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap and refer to it from the amHandler object and notifications.tls.

For auditing, use a ForgeRockClientHandler to send a Common Audit transaction ID when communicating with protected applications. Alternatively, configure this handler as a chain with a TransactionIdOutboundFilter:

"amHandler": {
  "type": "Chain",
  "config": {
    "handler": "MySecureClientHandler",
    "filters": [ "TransactionIdOutboundFilter" ]
  }
}

Default: ForgeRockClientHandler

notifications

"notifications": object, optional

Configure a WebSocket notification service to subscribe to Websocket notifications from AM.

To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap and refer to it from the amHandler object and notifications.tls. Alternatively, use proxyOptions to share a proxy configuration between the amHandler and the notification service.

Learn more in WebSocket notifications.

"enabled": configuration expression<boolean>, optional

A flag to enable WebSocket notifications. Set to false to disable WebSocket notifications.

Default: true

"initialConnectionAttempts": configuration expression<number>, optional

The maximum number of times PingGateway attempts to open a WebSocket connection before failing to deploy a route. For no limit, set this property to -1.

If the WebSocket connection fails after it has been opened and the route is deployed, PingGateway attempts to reconnect to it an unlimited number of times.

Default: 5

"reconnectDelay": configuration expression<duration>, optional

The time between attempts to reestablish a lost WebSocket connection.

When a WebSocket connection is lost, PingGateway waits for this delay and attempts to reestablish the connection. If subsequent attempts fail, PingGateway waits and tries again an unlimited number of times.

Default: 5 seconds

"renewalDelay": configuration expression<duration>, optional

The time before automatically renewing a WebSocket connection between PingGateway and AM. PingGateway renews connections transparently.

PingOne Advanced Identity Cloud closes WebSocket connections every 60 minutes. This property is set by default to prevent connection closure by automatically renewing connections every 50 minutes.

Set to 0 or unlimited to never automatically renew connections.

Default: 50 minutes

"heartbeatInterval": configuration expression<duration>, optional

The interval at which the AmService issues a heartbeat on WebSocket connections. When activity on the connection is low, the heartbeat prevents middleware or policies situated between PingGateway and AM from closing the connection for timeout.

Set to zero or unlimited to disable heartbeats.

Default: 1 minute

"connectionTimeout": configuration expression<duration>, optional

The time PingGateway waits to establish a Websocket connection to AM before it considers the attempt as failed.

Default: 60 seconds

"idleTimeout": configuration expression<duration>, optional

The time that a WebSocket connection to AM can be inactive before PingGateway closes it.

Default: unlimited

"tls": ClientTlsOptions reference, optional

Configure options for WebSocket connections to TLS-protected endpoints.

Define a ClientTlsOptions object inline or in the heap.

Default: Connections to TLS-protected endpoints aren’t configured.

"proxyOptions": ProxyOptions reference>, optional

A proxy server to which requests can be submitted. Use this property to relay requests to other parts of the network. For example, use it to submit requests from an internal network to the internet.

Provide the name of a ProxyOptions object defined in the heap or an inline configuration.

Default: A heap object named ProxyOptions.

"vertx": object, optional

Vert.x-specific configuration for WebSocket connections to AM. Vert.x values are evaluated as configuration expressions.

Use the Vert.x options described in VertxOptions.

sessionCache

"sessionCache": object, optional

In AM, if the realm includes a customized session property safelist, include AMCtxId in the list of properties. The customized session property safelist overrides the global session property safelist.

Enable and configure caching of session information from AM based on Caffeine.

When sessionCache is enabled, PingGateway can reuse session token information without repeatedly asking AM to verify the token. Each instance of AmService has an independent cache content. The cache isn’t shared with other AmService instances, either in the same or different routes and is not distributed among clustered PingGateway instances.

When sessionCache is disabled, PingGateway must ask AM to verify the token for each request.

PingGateway evicts session info entries from the cache for the following reasons:

  • AM cache timeout, based on whichever of the following events occur first:

    • maxSessionExpirationTime from SessionInfo

    • maxSessionTimeout from the AmService configuration

    When PingGateway evicts session info entries from the cache, the next time the token is presented, PingGateway must ask AM to verify the token.

  • If Websocket notifications are enabled, AM session revocation; for example, when a user logs out of AM.

    When Websocket notifications are enabled, PingGateway evicts a cached token almost as soon as it is revoked on AM, and in this way, stays synchronized with AM. Later requests to PingGateway that present the revoked token are rejected.

    When Websocket notifications are disabled, the token remains in the cache after it is revoked on AM. Later requests to PingGateway that present the revoked token are considered as valid and can cause incorrect authentication and authorization decisions until its natural eviction from the cache.

"enabled": configuration expression<boolean>, optional

Enable caching.

Default: false

"executor": Executor service reference, optional

An executor service to schedule the execution of tasks, such as the eviction of entries in the cache.

Default: ForkJoinPool.commonPool()

"maximumSize": configuration expression<number>, optional

The maximum number of entries the cache can contain.

Default: Unlimited/unbound

"maximumTimeToCache": configuration expression<duration>, optional

The maximum duration for which to cache session info. Set this duration to be less than the idle timeout of AM.

If maximumTimeToCache is longer than maxSessionExpirationTime from SessionInfo, maxSessionExpirationTime is used.

Default:

  • When sessionIdleRefresh is set, idle timeout of AM minus 30 seconds.

  • When sessionIdleRefresh is not set, maxSessionExpirationTime, from SessionInfo.

"onNotificationDisconnection": configuration expression<enumeration>, optional

The strategy to manage the cache when the WebSocket notification service is disconnected, and PingGateway receives no notifications for AM events. If the cache is not cleared it can become outdated, and PingGateway can allow requests on revoked sessions or tokens.

Cached entries that expire naturally while the notification service is disconnected are removed from the cache.

Use one of the following values:

  • NEVER_CLEAR

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that aren’t cached, but don’t update the cache with these requests.

    • When the notification service is reconnected:

      • Continue to use the existing cache.

      • Query AM for incoming requests that aren’t found in the cache, and update the cache with these requests.

  • CLEAR_ON_DISCONNECT

    • When the notification service is disconnected:

      • Clear the cache.

      • Deny access to all requests, but don’t update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that aren’t found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

  • CLEAR_ON_RECONNECT

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that aren’t cached, but don’t update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that aren’t found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

Default: CLEAR_ON_DISCONNECT

sessionIdleRefresh

"sessionIdleRefresh": object, optional

Enable and configure periodic refresh of idle sessions. When this property is enabled, PingGateway requests session refresh:

  • The first time PingGateway gets an SSO token from AM, irrespective of the age of the token.

  • When sessionIdleRefresh.interval has elapsed.

Use this property when AM is using CTS-based sessions. AM doesn’t monitor idle time for client-side sessions and so refresh requests are ignored.

When the SingleSignOnFilter is used for authentication with AM, AM can view a session as idle even though a user continues to interact with PingGateway. The user session eventually times out, and the user must reauthenticate.

When the SingleSignOnFilter filter is used with the PolicyEnforcementFilter, the session is refreshed each time PingGateway requests a policy decision from AM. The session is less likely to become idle, and this property isn’t required.

"enabled": configuration expression<boolean>, optional

Enable refresh of idle sessions.

Default: false

"interval": configuration expression<duration>, optional

Duration to wait after a session becomes idle before requesting a session refresh.

Set the refresh interval in line with the latest access time update frequency of AM. For example, if PingGateway requests a refresh every 60 seconds, but the update frequency of AM is 5 minutes, AM ignores most of the PingGateway requests.

Each session refresh must be reflected in the AM core token service. Setting the interval to a duration lower than one minute can adversely impact AM performance.

Default: 5 minutes

sessionProperties

"sessionProperties": array of configuration expression<strings>, optional

The list of user session properties to retrieve from AM by the SessionInfoFilter.

Default: All available session properties are retrieved from AM.

ssoTokenHeader

"ssoTokenHeader": configuration expression<string>, optional

The header name or cookie name where this AM server expects to find SSO tokens.

If a value for ssoTokenHeader is provided, PingGateway uses that value. Otherwise, PingGateway queries the AM /serverinfo/* endpoint for the header or cookie name.

Default: Empty. PingGateway queries AM for the cookie name.

version

"version": configuration expression<string>, optional

The version number of the AM server. PingGateway uses the AM version to establish endpoints for its interaction with AM.

The AM version is derived as follows, in order of precedence:

  • Discovered value: The AmService discovers the AM version.

    If "version" is configured with a different value, the AmService ignores the value of "version" and logs a warning.

  • Value in "version": AmService cannot discover the AM version, and "version" is configured.

  • Default value of AM 6: AmService cannot discover the AM version, and "version" is not configured.

If you use a feature that is supported only in a higher AM version than discovered or specified, PingGateway logs a message or throws an error.

Default: AM 6.

More information

org.forgerock.openig.tools.am.AmService