--- title: UserProfileFilter description: Queries AM to retrieve the profile attributes of an user identified by their username. component: pinggateway version: 7.2 page_id: pinggateway:reference:UserProfileFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/UserProfileFilter.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/UserProfileFilter.html section_ids: UserProfileFilter-usage: Usage UserProfileFilter-properties: Properties UserProfileFilter-example: Example UserProfileFilter-moreinfo: More information --- # 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 IG filters and handlers, in the context [UserProfileContext](RequestsResponsesContexts.html#UserProfileContext). ## Usage ```json { "name": string, "type": "UserProfileFilter", "config": { "username": runtime expression, "userProfileService": UserProfileService reference, "amService": AmService reference, //deprecated "ssoToken": runtime expression, //deprecated "profileAttributes": array of runtime expressions //deprecated } } ``` ## Properties * `"username"`: *runtime expression<[string](preface.html#definition-string)>, required* The username of an AM subject. This filter retrieves profile attributes for the subject. * `"userProfileService"`: *UserProfileService [reference](preface.html#definition-reference), required* The service to retrieve profile attributes from AM, for the subject identified by `username`. ```json "userProfileService": { "type": "UserProfileService", "config": { "amService": AmService reference, "cache": object, "profileAttributes": [ configuration expression, ... ], "realm": configuration expression } } ``` * `"amService"`: *AmService [reference](preface.html#definition-reference), required* The AmService heap object to use for the following properties: * `agent`, 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. * `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 IG 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](preface.html#definition-object), optional* Caching of AM user profiles, based on *Caffeine*. For more information, see the GitHub entry, [Caffeine](https://github.com/ben-manes/caffeine). When caching is enabled, IG can reuse cached profile attributes without repeatedly querying AM. When caching is disabled, IG must query AM for each request, to retrieve the required user profile attributes. Default: No cache. ```json "cache": { "enabled": configuration expression, "executor": Executor reference, "maximumSize": configuration expression, "maximumTimeToCache": configuration expression, } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-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](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)>, required* The maximum duration for which to cache user profiles. The duration cannot be `zero`. * `profileAttributes`: *array of configuration expression<[strings](preface.html#definition-string)>, 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 ForgeRock Directory Services. 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](preface.html#definition-string)>, optional* The AM realm where the subject is authenticated. Default: The realm declared for `amService`. * `"ssoToken"`: *runtime expressions\, optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use `username` instead. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | Location of the AM SSO token. For example, with `${request.headers['mySsoToken'].values[0]}` the SSO token is the first value of the `mySsoToken` header in the request. If an SSO token is not available in the request, an error is returned. Default: `${request.cookies['AmService-ssoTokenHeader'][0].value}`, where `AmService-ssoTokenHeader` is the name of the header or cookie where the AmService expects to find SSO tokens. * `"amService"`: *AmService [reference](preface.html#definition-reference), optional* | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use the `userProfileService` subproperty `amService` instead. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | The AmService heap object to use. * `"profileAttributes"`: *array of runtime expressions\, optional* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use the `userProfileService` subproperty `profileAttributes` instead. For more information, refer to [Deprecation](../release-notes/deprecated-functionality.html). | List of field names in AM to retrieve. When this property is not configured, all available fields are returned. When this property is configured, the specified fields and the following fields are returned: `username`, `_id`, and `_rev`. Field names are defined by the underlying repository in AM. For example, when AM is installed with the default configuration, the repository is ForgeRock Directory Server. 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()}`. Default: All available fields are returned. ## Example For examples that use the UserProfileFilter, see [Get user profile information from AM](../gateway-guide/profile-am.html). ## More information [org.forgerock.openig.openam.UserProfileFilter](../_attachments/apidocs/org/forgerock/openig/openam/UserProfileFilter.html) [org.forgerock.openig.tools.userprofile.UserProfileService](../_attachments/apidocs/org/forgerock/openig/tools/userprofile/UserProfileService.html) [org.forgerock.openig.openam.UserProfileContext](../_attachments/apidocs/org/forgerock/openig/openam/UserProfileContext.html) [UserProfileContext](RequestsResponsesContexts.html#UserProfileContext) AM's [Authorization guide](https://docs.pingidentity.com/pingam/7.2/authorization-guide/)