PingGateway 2024.9

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": object,
    "secretsProvider": SecretsProvider reference,
    "notifications": object,
    "realm": configuration expression<string>,
    "amHandler": Handler reference,
    "sessionCache": object,
    "sessionIdleRefresh": object,
    "sessionProperties": [ configuration expression<string>, ... ],
    "ssoTokenHeader": configuration expression<string>,
    "url": configuration expression<url>,
    "version": configuration expression<string>
  }
}

Properties

"agent": object, required

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

{
  "AmService": {
     "username": configuration expression<string>,
     "passwordSecretId": configuration expression<secret-id>
   }
}
"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 reference, required

The SecretsProvider to query for the agent password.

"realm": configuration expression<string>, optional

The AM realm in which the PingGateway agent is created.

Default: / (top level realm).

"amHandler": Handler reference, optional

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

AmService does not 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 the notifications subproperty tls .

To facilitate auditing, configure this handler with a ForgeRockClientHandler, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.

Alternatively, configure this handler as a chain containing a TransactionIdOutboundFilter, as in the following configuration:

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

Default: ForgeRockClientHandler

Refer to Handlers and ClientHandler.

"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 the notifications subproperty tls. Alternatively, use proxyOptions to share a proxy configuration between the amHandler and the notification service.

For information, refer to WebSocket notifications.

{
  "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
  }
}
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 re-establish a lost WebSocket connection.

When a WebSocket connection is lost, PingGateway waits for this delay and then attempts to re-establish 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 are not 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.

"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.

"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. For more information, see the GitHub entry, 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 is not 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 the 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. Subsequent 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. Subsequent 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.

{
  "sessionCache": {
    "enabled": configuration expression<boolean>,
    "executor": Executor service reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>,
    "onNotificationDisconnection": configuration expression<enumeration>
  }
}
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. Consider setting 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 are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Continue to use the existing cache.

      • Query AM for incoming requests that are not 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 do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not 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 are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not 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": 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 does not 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 re-authenticate.

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 less required.

{
  "sessionIdleRefresh": {
    "enabled": configuration expression<boolean>,
    "interval": configuration expression<duration>
  }
}
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.

Consider setting 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": 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": 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": 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: AmService discovers the AM version. If version is configured with a different value, AmService ignores the value of version and issues 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 specifed, a message can be logged or an error thrown.

Default: AM 6.

More information

org.forgerock.openig.tools.am.AmService