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 Sep 22, 2021

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 console, Amster or ssoadm:

  • Console: 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 console, Amster or ssoadm:

Web Agent

  • Console: 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 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [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: 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 console, Amster or ssoadm:

Web Agent

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Group 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: 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 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > Groups > [Group ID] > SSO > Cookie Name and enter the new session cookie name.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Group 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: 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 Guide

Deployment Configuration

Related Training

N/A

Related Issue Tracker IDs

N/A


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