How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I change the session cookie name for AM and Agents (All versions)?

Last updated Jan 11, 2023

The purpose of this article is to provide information on changing the name of the AM session cookie and also updating the Agent session cookies to match. The session cookie is called iPlanetDirectoryPro by default but you should change it for security reasons.


1 reader recommends this article

Overview

Once you have changed the AM session cookie name, you must also update the session cookie name in your agent profiles to match the new session cookie name. You can change the agent cookies, default agent cookies or the agent group cookies to achieve this.

This article contains information on changing the following session cookie names:

REST calls

Once you have changed the AM session cookie name, you must also update any REST calls to use the new cookie name in the header. For example, if your new cookie is called exampleCookie, you would change the following header in your REST calls from:

-H "iPlanetDirectoryPro: AQIC5..."

To:

-H "exampleCookie: AQIC5..."

Renaming the AM session cookie

You can change the name of this cookie using either the AM admin UI, Amster or ssoadm:

  • AM admin UI: navigate to: Configure > Server Defaults > Security > Cookie > Cookie Name and enter the new session cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: DefaultSecurityProperties
    • Property: com.iplanet.am.cookie.name
  • ssoadm: enter the following command: $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]replacing [adminID], [passwordfile] and [cookiename] with appropriate values.
Note

You must restart the web application container in which AM runs to apply these configuration changes.

Renaming the agent session cookie in AM

You can change the name of this cookie using either the AM admin UI, Amster or ssoadm:

Web Agent

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents
    • Property: cookieName
  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cookie.name=[cookiename]replacing [realmname], [agentname], [adminID], [passwordfile] and [cookiename] with appropriate values.

Java Agent

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > SSO > Cookie Name and enter the new session cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: J2eeAgents
    • Property: amCookieName
  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]replacing [realmname], [agentname], [adminID], [passwordfile] and [cookiename] with appropriate values.
Note

You must restart the web application container in which AM runs to apply these configuration changes.

Renaming the default agent session cookie in AM

You can change the name of this cookie using ssoadm:

Web Agent

Enter the following command:

$ ./ssoadm set-attr-defs -s AgentService -t Organization -u [adminID] -f [passwordfile] -c WebAgent -a com.sun.identity.agents.config.cookie.name=[cookiename]

replacing [adminID], [passwordfile] and [cookiename] with appropriate values.

Java Agent

Enter the following command:

$ ./ssoadm set-attr-defs -s AgentService -t Organization -u [adminID] -f [passwordfile] -c J2EEAgent -a com.iplanet.am.cookie.name=[cookiename]

replacing [adminID], [passwordfile] and [cookiename] with appropriate values.

Note

You must restart the web application container in which AM runs to apply these configuration changes.

Renaming the agent group session cookie in AM

You can change the name of this cookie using either the AM admin UI, Amster or ssoadm:

Web Agent

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Web > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgentGroups
    • Property: cookieName
  • ssoadm: enter the following command: $ ./ssoadm update-agent-grp -e [realmname] -b [agentgroupname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.cookie.name=[cookiename]replacing [realmname], [agentgroupname], [adminID], [passwordfile] and [cookiename] with appropriate values.

Java Agent

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Java > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2EEAgentGroups
    • Property: amCookieName
  • ssoadm: enter the following command: $ ./ssoadm update-agent-grp -e [realmname] -b [agentgroupname] -u [adminID] -f [passwordfile] -a com.iplanet.am.cookie.name=[cookiename]replacing [realmname], [agentgroupname], [adminID], [passwordfile] and [cookiename] with appropriate values.
Note

You must restart the web application container in which AM runs to apply these configuration changes.

See Also

Security

Deployment Configuration

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.