FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: Cookies in AM

Last updated Nov 24, 2021

The purpose of this FAQ is to provide answers to commonly asked questions regarding cookies in AM, including the session cookie (iPlanetDirectoryPro).


6 readers recommend this article

Frequently asked questions

Q. What is the iPlanetDirectoryPro cookie?

A. The iPlanetDirectoryPro cookie is the AM session cookie. This session cookie is created when a user successfully authenticates against AM and stores the session token ID (also referred to as the session ID or SSOTokenID). This session cookie is held as a domain cookie, that is, it applies to one domain only and it facilitates Single Sign On (SSO) within that domain. You can only authenticate across domains if you have set up Cross Domain Single Sign On (CDSSO).

iPlanetDirectoryPro is the default name for this session cookie, although it is recommended that you change it for security reasons.

Note

The iPlanetDirectoryPro cookie is larger if you have client-based sessions since the cookie stores the session details. See Choosing Where to Store Sessions for further information.

Q. How do I change the name of the default AM session cookie?

A. See How do I change the session cookie name for AM and Agents (All versions)? for further information.

Q. Can I use the same AM session cookie name in all environments?

A. No, you should have a unique session cookie name per environment (for example, the session cookie should be named differently in your production and development environments). This improves security, but is also necessary to avoid issues that can occur when swapping between environments that use the same cookie name.

Additionally, it is recommended that the amlbcookie is also named uniquely per environment.

Q. What information is contained in the AM session cookie?

A. The AM session cookie stores the session token, which consists of the following two parts, separated by a full stop (.):

  • Session ID - this part identifies the session on the server and is formatted as follows depending on your AM version:
    • AM 5.5 and later - the session ID is a non-encrypted base64-encoded secure random value. The generated ID has 160-bits of entropy generated using SecureRandom. 160-bits is used to maintain entropy and ensure that session identifiers are unpredictable and collision resistant. See OPENAM-11044 (Stop encrypting the session id prefix) for further information.
    • Pre-AM 5.5 - the session ID is a SHA1-PRNG generated secure hash. Typically, this is in C66Encode format, although it can use percent encoding.
  • Session key - this part is a base64-encoded value that identifies the following depending on your AM version; this value can be useful when debugging:
    • AM 6 and later: the site where the server resides, the storage key used during session failover, the session type and the server instance where the session resides, where the session type can be:
      • CTS, JWT or IN_MEMORY for authentication sessions.
      • CTS or STATELESS for authentication sessions, where STATELESS is the same as JWT.
    • Pre-AM 6: the site where the server resides, the storage key used during session failover and the server instance where the session resides.

If you use client-based sessions, the cookie contains an additional section after these two parts. This section contains the session details stored as a JSON Web Token (JWT). If you have signing but no encryption (default), you can inspect this, for example using https://jwt.davetonge.co.uk

AM 6 and later example

A CTS-based session token looks similar to this:

PxhscnV7x_Cg3z5B_7QyCXPQA3w.*AAJTSQACMDIAAlNLABxEYndjOHNhOUlwSTNJdGMrZE0waEx1VXJ3UU09AAR0eXBlAANDVFMAAlMxAAIwMQ..*

where the session key is: *AAJTSQACMDIAAlNLABxEYndjOHNhOUlwSTNJdGMrZE0waEx1VXJ3UU09AAR0eXBlAANDVFMAAlMxAAIwMQ..*

If you decode this using a base64 decoder (for example, www.base64decode.org), you end up with: SI02SKDbwc8sa9IpI3Itc+dM0hLuUrwQM=typeCTSS101 where:

  • SInn is the site identifier (in this case 02). If the server instance does not belong to a site, the SInn element is the server instance and the S1nn element only shows S1.
  • SKnumber is the storage key.
  • type is the session type (in this case CTS).
  • S1nn is the server instance (in this case 01).

AM 5.x example

A CTS-based session token looks similar to this:

AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*

where the session key is: *AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.*

If you decode this using a base64 decoder (for example, www.base64decode.org), you end up with: SI02SK1939912025267718974S101 where:

  • SInn is the site identifier (in this case 02). If the server instance does not belong to a site, the SInn element is the server instance and the S1nn element is excluded.
  • SKnumber is the storage key.
  • S1nn is the server instance (in this case 01).

Q. Can I set an expiration time for the AM session cookie?

A. Yes you can using the Persistent Cookie authentication module. See Persistent Cookie Module for further information.

Q. Is there a maximum session size?

A. No there isn't if you have CTS-based sessions, but the size of each session object affects the performance of the AM server, including how much JVM heap it uses, so it is recommended that you keep session sizes as small as possible.

If you have client-based sessions, the session is stored in the cookie. This means there is a limitation on the size of session since most browsers will prevent a cookie being larger than 4096 bytes. You should avoid adding too many session properties to keep the session size manageable. See Configuring Client-Based Sessions and Client-Based Session Security and Agents for further information.

Q. Is there a limit to the size of a custom attribute when using SSOToken#setProperty()?

A. No, but the size of attribute affects the session size, so big attributes result in big sessions, which again affects performance of the AM server or the size of cookie.

Note

You can add and remove session properties using the REST API: Obtaining Information About Sessions Using REST.

Q. What other cookies does AM create?

A. AM also creates the following cookies:

  • AMAuthCookie - this cookie is created when the user displays the login page and corresponds to the invalid session that is created at this time. This cookie is used to track users who are in the process of authenticating; it is not used once the user has authenticated and automatically expires after three minutes (by default).
  • amlbcookie - this cookie is created by AM when a load balancer is in use and is used to implement sticky load balancing. This cookie identifies the server that holds the user’s session information, which is then used by the load balancer to redirect the user’s requests to that server. This cookie is sometimes referred to as the sticky cookie.
  • OAUTH_REQUEST_ATTRIBUTES - this cookie is created by AM when a POST request is made to the OAuth2 /authorize endpoint (AM 7 and later). This cookie stores the POST data needed to authenticate in case you are redirected for authentication and is deleted upon successful authorization.
  • DProPCookie - this cookie is created by AM alongside the session cookie if you are using persistent cookies. This cookie is encrypted and stores information needed to re-create a session if a user does not have a valid session cookie but does have a valid persistent cookie.

Q. How can I configure cookies to improve security and reduce the threat of cookie hijacking?

A. There are a number of things you can do to improve security, including:

  • Change the default cookie names. See How do I change the session cookie name for AM and Agents (All versions)? for further information.
  • Use Secure cookies (providing you use SSL connections throughout) and/or HTTPOnly cookies. See Security Guide for further information.
  • Use restricted tokens (host-based cookies). Using restricted tokens means you will have a different value for each application so that a token can only be used for a specific application; this reduces the risk from cookie hijacking because if an application is hijacked, the hijacker will only have access to that one application. However, implementing restricted tokens comes with an increase in complexity as you need to set up agents to use CDSSO; for it to make sense, you also need to have all communications through SSL and disable the setting by which agents trust certificates by default. Therefore, you should balance the increase in complexity with the actual risk of hijacking. See Enabling Restricted Tokens for CDSSO Session Cookies for further information.

Q. How do I configure AM to use host-based cookies?

A. Leave the Cookie Domains list blank; AM will then use the FQDN of the server as the cookie domain, meaning that a host cookie is set rather than a domain cookie. You can remove cookie domains using either the console or ssoadm:

  • Console: navigate to: Configure > Global Services > Platform > Cookie Domains.
  • ssoadm: enter the following command: $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=replacing [adminID], [passwordfile] and [primarydomain] with appropriate values.
Note

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

See Platform for further information.

Q. What does the cookie domain default to?

A. The cookie domain defaults to the full FQDN to avoid invalid cookie domains in scenarios where it is difficult to determine what the cookie domain should be (for example, on a site such as eu-west-1.compute.amazonaws.com). This is mentioned in: OPENAM-9363 (Can not log in when reverse proxy in front of OpenAM) and OPENAM-9378 (OpenAM 13.5 now defaults to using FQDN as cookie domain).

Q. Why should I use the amlbcookie for load balancing?

A. Using the amlbcookie ensures the user always ends up accessing the server that is authoritative for their session.

Without the amlbcookie, even if you do have another method of stickiness (such as IP based or other cookie mechanism), there is much less guarantee that the user will return to the server they originally authenticated on. This is especially true if your sessions last for a moderate amount of time and the other stickiness mechanism has expired in between the user accessing the server; it is possible your users could end up stuck to a non-authoritative server.

If the user hits a non-authoritative AM server, that server will need to cross-talk to the authoritative server. Therefore the cost of not using the amlbcookie for load balancing is increased load on CPU, network and memory.

Note

If you have CTS-based sessions, sticky load balancing is a requirement for all module-based authentication scenarios as noted in the following known issues: OPENAM-12675 (One-step authentication in a cluster requires sticky load balancing) and OPENAM-8336 (XUI+REST authentication with chains must have sticky load balancing). You can overcome this limitation by upgrading to AM 6 or later, and implementing authentication trees. See AM 6 New Features (Distributed Login) for further information.

If you have client-based sessions, you do not need to configure the load balancer for session stickiness as discussed in: Choosing Where to Store Sessions.

Q. Why is the load balancer not using the amlbcookie in a SSL AM cluster?

A. If the load balancer simply passes all requests straight through to AM (that is, TCP load balancing is occurring), the load balancer is unable to inspect the encrypted HTTP traffic and therefore does not use the amlbcookie. You can mitigate this by terminating SSL at the load balancer (or before) and then either pass the request as HTTP to AM or use a new SSL connection (HTTPS) between the load balancer and AM.

Q. Do I need different cookie names if I am using one instance of AM as an IdP and another instance as a SP?

A. If the domain names are the same for the IdP server and the SP server, you do need different cookie names to differentiate the cookies created by AM. You should change the session cookie name and the amlbcookie cookie name (if you have a load balancer in use) for one of the AM servers.

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

Q. Why does the HTTP header show the same cookie name and value being set for multiple domains?

A. AM does not set cookie domains based on the incoming HTTP host request header (this would not even be possible if there was a reverse proxy or load balancer in front that did not preserve the header) so it sets them all. The browser just ignores any cookies that don't match the current domain to ensure the correct one is used.

If you do not require this behavior, you can use host-based cookies instead or you can set the advanced server property: com.sun.identity.authentication.setCookieToAllDomains to false and restart the web application container in which AM runs. See Advanced Properties for further information.

Note

This property must be set to false if you use Wildfly as the AM web container with multiple cookie domains as discussed in Configuring the Cookie Domain.

This is a known Wildfly limitation: UNDERTOW-488 (Adding the same cookie more than once fails).

Q. Can I set a cookie on the top level domain?

A. No, you should not set cookies on the top level domain; most browsers will block such cookies anyway as they pose a security risk.

Q. How does AM use the JSESSIONID cookie?

A. AM does not use the JSESSIONID cookie at all. The JESSIONID cookie is set by the web container (for example, Apache Tomcat™) and is used by the web container to manage sessions.

AM ignores this cookie and instead creates its own session cookie; this session cookie is called iPlanetDirectoryPro by default.

See Also

Cookies in AM

About HTTP Cookies

Security Guide

Platform

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


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