--- title: AmService description: Holds information about the configuration of an instance of AM. The AmService is available to IG filters that communicate with that instance. component: pinggateway version: 7.2 page_id: pinggateway:reference:AmService canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/AmService.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-02T16:30:54Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/AmService.html section_ids: AmService-usage: Usage AmService-properties: Properties AmService-moreinfo: More information --- # AmService Holds information about the configuration of an instance of AM. The AmService is available to IG filters that communicate with that instance. When IG uses an AmService, IG is positioned as the client of the service. By default, IG is subscribed to Websocket notifications from AM, and the WebSocket connection can be secured by ClientTlsOptions. ## Usage ```json { "name": string, "type": "AmService", "config": { "agent": object, "secretsProvider": SecretsProvider reference, "notifications": object, "realm": configuration expression, "amHandler": Handler reference, "sessionCache": object, "sessionIdleRefresh": object, "sessionProperties": [ configuration expression, ... ], "ssoTokenHeader": configuration expression, "url": configuration expression, "version": configuration expression } } ``` ## Properties * `"agent"`: *[object](preface.html#definition-object), required* The credentials of the IG agent in AM. 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. * `"username"`: *configuration expression<[string](preface.html#definition-string)>, required* Agent name. * `"passwordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The secret ID of the agent password. * `"password"`: *configuration expression<[string](preface.html#definition-string)>, required* | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated and is not considered secure. Use `passwordSecretId` instead. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | The agent password. * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The SecretsProvider object to query for the agent password. For more information, see [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, see [Default secrets object](secrets.html#default-secrets-object). * `"realm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The AM realm in which the IG agent is created. Default: `/` (top level realm). * `"amHandler"`: *Handler [reference](preface.html#definition-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: ```json "amHandler": { "type": "Chain", "config": { "handler": "MySecureClientHandler", "filters": [ "TransactionIdOutboundFilter" ] } } ``` Default: `ForgeRockClientHandler` See also [Handlers](Handlers.html) and [ClientHandler](Handlers.html#ClientHandler). * `"notifications"`: *[object](preface.html#definition-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, see [WebSocket Notifications](../maintenance-guide/tuning.html#amservice-websocket). ```json { "notifications": { "enabled": configuration expression, "initialConnectionAttempts": configuration expression, "reconnectDelay": configuration expression, "tls": ClientTlsOptions reference, "proxyOptions": ProxyOptions reference, } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to enable WebSocket notifications. Set to `false` to disable WebSocket notifications. Default: `true` * `"initialConnectionAttempts"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of times IG 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, IG attempts to reconnect to it an unlimited number of times. Default: `5` * `reconnectDelay`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The time between attempts to re-establish a lost WebSocket connection. When a WebSocket connection is lost, IG waits for this delay and then attempts to re-establish the connection. If subsequent attempts fail, IG waits and tries again an unlimited number of times. Default: `5 seconds` * `heartbeatInterval`: *configuration expression<[duration](preface.html#definition-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 IG and AM from closing the connection for timeout. Set to zero or unlimited to disable heartbeats. Default: `1 minute` * `tls`: *ClientTlsOptions [reference](preface.html#definition-reference), optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Use of a TlsOptions reference is deprecated; use ClientTlsOptions instead. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | Configure options for WebSocket connections to TLS-protected endpoints. Define a [ClientTlsOptions](MiscellaneousConfigurationObjects.html#ClientTlsOptions) object inline or in the heap. Default: Connections to TLS-protected endpoints are not configured. * `"proxyOptions"`: *ProxyOptions [reference](preface.html#definition-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](ProxyOptions.html) object defined in the heap, or an inline configuration. Default: A heap object named `ProxyOptions`. * `"url"`: *configuration expression<[url](preface.html#definition-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 the Advanced Identity Cloud, this value could be `https://myTenant.forgeblocks.com/am`. * `"sessionCache"`: *[object](preface.html#definition-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](https://github.com/ben-manes/caffeine). When `sessionCache` is enabled, IG 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 IG instances. When `sessionCache` is disabled, IG must ask AM to verify the token for each request. IG 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 IG evicts session info entries from the cache, the next time the token is presented, IG 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, IG evicts a cached token almost as soon as it is revoked on AM, and in this way stays synchronized with AM. Subsequent requests to IG 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 IG that present the revoked token are considered as valid, and can cause incorrect authentication and authorization decisions until its natural eviction from the cache. ```json { "sessionCache": { "enabled": configuration expression, "executor": Executor service reference, "maximumSize": configuration expression, "maximumTimeToCache": configuration expression, "onNotificationDisconnection": configuration expression } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Enable caching. Default: `false` * `executor`: *Executor service [reference](preface.html#definition-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](preface.html#definition-number)>, optional* The maximum number of entries the cache can contain. Default: Unlimited/unbound. * `maximumTimeToCache`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-enumeration)>, optional* The strategy to manage the cache when the WebSocket notification service is disconnected, and IG receives no notifications for AM events. If the cache is not cleared it can become outdated, and IG 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](preface.html#definition-object), optional* *(From AM 6.5.3.)* Enable and configure periodic refresh of idle sessions. 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, after a time, AM can view the session as idle even though the user continues to interact with IG. 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 IG requests a policy decision from AM. The session is less likely to become idle, and this property less required. ```json { "sessionIdleRefresh": { "enabled": configuration expression, "interval": configuration expression } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Enable refresh of idle sessions. Default: `false` * `interval`: *configuration expression<[duration](preface.html#definition-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 IG requests a refresh every 60 seconds, but the update frequency of AM is 5 minutes, AM ignores most of the IG 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](preface.html#definition-string)>, optional* The list of user session properties to retrieve from AM by the [SessionInfoFilter](Filters.html#SessionInfoFilter). Default: All available session properties are retrieved from AM. * `"ssoTokenHeader"`: *configuration expression<[string](preface.html#definition-string)>, optional* The header name or cookie name where this AM server expects to find SSO tokens. If a value for `ssoTokenHeader` is provided, IG uses that value. Otherwise, IG queries the AM `/serverinfo/*` endpoint for the header or cookie name. Default: Empty. IG queries AM for the cookie name. * `"version"`: *configuration expression<[string](preface.html#definition-string)>, optional* The version number of the AM server. IG 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. For example, if `sessionIdleRefresh` is enabled but the AM version is below the required AM 6.5.3, an error like the following is logged: ``` sessionIdleRefresh is only supported with AM version 6.5.3 and above, the configured AM version is 6 ``` Default: AM 6. ## More information [org.forgerock.openig.tools.am.AmService](../_attachments/apidocs/org/forgerock/openig/tools/am/AmService.html)