---
title: User Mapping Mode
description: Specifies where to obtain the user ID
component: java-agents
version: 2024.11
page_id: java-agents:properties-reference:org.forgerock.agents.user.mapping.mode
canonical_url: https://docs.pingidentity.com/java-agents/2026/properties-reference/org.forgerock.agents.user.mapping.mode.html
llms_txt: https://docs.pingidentity.com/java-agents/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
superseded_by: https://docs.pingidentity.com/java-agents/2026/properties-reference/org.forgerock.agents.user.mapping.mode.html
---

# User Mapping Mode

Specifies where to obtain the user ID

|                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Property name            | `org.forgerock.agents.user.mapping.mode`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Aliases                  | `org.forgerock.agents.user.mapping.mode`   Introduced in Java Agent 5.6`com.sun.identity.agents.config.user.mapping.mode`   Introduced in Java Agent 5.0   [Recognized](preface.html#how_am_manages_multiple_aliases) from AM 6                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Function                 | User mapping                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Supported settings       | * USER_ID

  If "Enable User Principal Flag" (org.forgerock.agents.userid.mapping.mode.use.dn.enabled) is `true`, the user ID is set from the User Principal. Otherwise, the user ID is set from the user's session property nominated by "User Session Name" (org.forgerock.agents.userid.mapping.mode.use.session.property.name).

* PROFILE_ATTRIBUTE

  The user ID is set to the value of a named profile attribute specified by "User Attribute Name" (org.forgerock.agents.user.mapping.mode.attribute.name).

* HTTP_HEADER

  The user ID is set to the value of the HTTP header specified by the "User Attribute Name" (org.forgerock.agents.user.mapping.mode.attribute.name).

* SESSION_PROPERTY

  The user ID is set to the value of the session property specified by the "User Attribute Name" (org.forgerock.agents.user.mapping.mode.attribute.name). |
| Default                  | `USER_ID`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Bootstrap property       | No                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Required property        | No                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Restart required         | No                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Local configuration file | `AgentConfig.properties`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| AM console               | Tab: `Global`Title: `User Mapping Mode`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |