AmService

An AmService holds information about the configuration of an instance of AM. It is available to IG filters that communicate with that instance.

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<uri string>,
     "version": configuration expression<string>
   }
}

Properties

"agent": 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>, required

Agent name.

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

The secret ID of the agent password.

For information about supported formats for secret-id, see secret-id.

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

Tip

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

"notifications": object, optional

Configure WebSocket notification service.

For information about WebSocket notifications, see "WebSocket Notifications". 

{
  "notifications": {
     "enabled": boolean,
     "reconnectDelay": object,
     "tls": ClientTlsOptions reference
  }
}
enabled: boolean, optional

Enable or disable WebSocket notifications. Set to false to disable WebSocket notifications.

Default: true

reconnectDelay: 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

For information about supported formats for duration, see duration.

tls: ClientTlsOptions reference, optional

Configure options for WebSocket connections to TLS-protected endpoints. Define a ClientTlsOptions object inline or in the heap.

For more information, see "ClientTlsOptions".

Default: Connections to TLS-protected endpoints not configured.

"url": configuration expression<uri string>, required

The URL of the AM service. When AM is running locally, this value could be https://openam.example.com/openam. When AM is running in the ForgeRock Identity Cloud, this value could be https://myTenant.forgeblocks.com/am.

"sessionCache": object, optional

Supported in AM 5.5 when the user manually whitelists the AMCtxId session property, and in AM 6 and later versions without additional configuration in AM.

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

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 string>, 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.

For information about supported formats for duration, see duration.

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. Use this property when AM is using CTS-based sessions. AM does not monitor idle time for client-based 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. 

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

Important

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<string>, optional

Supported with AM 6 and later versions.

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 this property to establish the endpoints for its interaction with AM.

If you use a feature that is supported only in a higher AM version than specifed, a message can be logged or an error thrown. For example, if sessionIdleRefresh is enabled but version is lower than 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 5.0

Configure this property with the correct version number for your AM server.

Default: AM 5.0.

Example

For examples where AmService is used, see the example routes at the end of "OAuth2ResourceServerFilter", "PolicyEnforcementFilter", "SingleSignOnFilter", "TokenTransformationFilter", and "UserProfileFilter".

Read a different version of :