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

{
  "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 IG 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>,
     "password": configuration expression<string> //deprecated
   }
}

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

"password": configuration expression<string>, required

This property is deprecated and is not considered secure. Use passwordSecretId instead. For more information, refer to the Deprecated section of the Release Notes.

The agent password.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the agent password. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default secrets object.

"realm": configuration expression<string>, optional

The AM realm in which the IG 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

See also 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 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>, 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

renewalDelay: configuration expression<duration>, optional

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

ForgeRock 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 IG 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 IG 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 IG closes it.

Default: unlimited

tls: ClientTlsOptions reference, optional

Use of a TlsOptions reference is deprecated; use ClientTlsOptions instead. For more information, refer to the Deprecated section of the Release Notes.

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 the ForgeRock 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, 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.

{
  "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 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, optional

(From AM 6.5.3.) Enable and configure periodic refresh of idle sessions. When this property is enabled, IG requests session refresh:

The first time IG 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 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.

{
  "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 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>, 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, 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>, 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

Identity Gateway 2023.11

AmService

Usage

Properties

More information