PingGateway 2024.9

UserProfileFilter

Queries AM to retrieve the profile attributes of an user identified by their username.

Only profile attributes that are enabled in AM can be returned by the query. The roles field is not returned.

The data is made available to downstream PingGateway filters and handlers, in the context UserProfileContext.

Usage

{
  "name": string,
  "type": "UserProfileFilter",
  "config": {
    "username": runtime expression<string>,
    "userProfileService": UserProfileService reference
  }
}

Properties

"username": runtime expression<string>, required

The username of an AM subject. This filter retrieves profile attributes for the subject.

"userProfileService": UserProfileService reference, required

The service to retrieve profile attributes from AM, for the subject identified by username.

"userProfileService": {
  "type": "UserProfileService",
  "config": {
    "amService": AmService reference,
    "cache": object,
    "profileAttributes": [ configuration expression<string>, ... ],
    "realm": configuration expression<string>
  }
}
"amService": AmService reference, required

The AmService heap object to use for the following properties:

  • agent, the credentials of the PingGateway 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.

    • url: URL of the AM server where the user is authenticated.

    • amHandler: Handler to use when communicating with AM to fetch the requested user’s profile.

  • realm: Realm of the PingGateway agent in AM.

  • version: The version of the AM server.

    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.

"cache": object, optional

Caching of AM user profiles, based on Caffeine. For more information, see the GitHub entry, Caffeine.

When caching is enabled, PingGateway can reuse cached profile attributes without repeatedly querying AM. When caching is disabled, PingGateway must query AM for each request, to retrieve the required user profile attributes.

Default: No cache.

"cache": {
    "enabled": configuration expression<boolean>,
    "executor": Executor reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>,
}
enabled: configuration expression<boolean>,optional

Enable or disable caching of user profiles. When false, the cache is disabled but the cache configuration is maintained.

Default: true when cache is configured

executor: Executor 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>, required

The maximum duration for which to cache user profiles.

The duration cannot be zero.

profileAttributes: array of configuration expression<strings>, optional

List of one or more fields to return and store in UserProfileContext.

Field names are defined by the underlying repository in AM. When AM is installed with the default configuration, the repository is PingDS.

The following convenience accessors are provided for commonly used fields:

  • cn: Retrieved through ${contexts.userProfile.commonName}

  • dn: Retrieved through ${contexts.userProfile.distinguishedName}

  • realm: Retrieved through ${contexts.userProfile.realm}

  • username: Retrieved through ${contexts.userProfile.username}

All other available fields can be retrieved through ${contexts.userProfile.rawInfo} and ${contexts.userProfile.asJsonValue()}.

When profileAttributes is configured, the specified fields and the following fields are returned: username, _id, and _rev.

Default: All available fields are returned.

"realm": configuration expression<string>, optional

The AM realm where the subject is authenticated.

Default: The realm declared for amService.

Example

For examples that use the UserProfileFilter, see Pass profile data downstream.

Copyright © 2010-2024 ForgeRock, all rights reserved.