Frequently asked questions
- Q. What is the iPlanetDirectoryPro cookie?
- Q. How do I change the name of the default AM/OpenAM session cookie?
- Q. Can I use the same AM/OpenAM session cookie name in all environments?
- Q. What information is contained in the AM/OpenAM session cookie?
- Q. Can I set an expiration time for the AM/OpenAM session cookie?
- Q. Is there a maximum session size?
- Q. Is there a limit to the size of a custom attribute when using SSOToken#setProperty()?
- Q. What other cookies does AM/OpenAM create?
- Q. How can I configure cookies to improve security and reduce the threat of cookie hijacking?
- Q. How do I configure AM/OpenAM to use host-based cookies?
- Q. What does the cookie domain default to?
- Q. Why should I use the amlbcookie for load balancing?
- Q. How does the amlbcookie work in a failover scenario?
- Q. Why is the load balancer not using the amlbcookie in a SSL AM/OpenAM cluster?
- Q. Do I need different cookie names if I am using one instance of AM/OpenAM as an IdP and another instance as a SP?
- Q. Why does the HTTP header show the same cookie name and value being set for multiple domains?
- Q. Can I set a cookie on the top level domain?
- Q. How does AM/OpenAM use the JSESSIONID cookie?
Q. What is the iPlanetDirectoryPro cookie?
A. The iPlanetDirectoryPro cookie is the AM/OpenAM session cookie. This session cookie is created when a user successfully authenticates against AM/OpenAM 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.
The iPlanetDirectoryPro cookie is larger if you have client-based sessions since the cookie stores the session details. Client-based sessions are available in OpenAM 13 onwards. See How do I enable Client-based sessions in AM (All versions) and OpenAM 13.x? for further information.
Q. How do I change the name of the default AM/OpenAM session cookie?
A. See How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)? for further information.
Q. Can I use the same AM/OpenAM 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/OpenAM session cookie?
- Session ID - this part identifies the session on the server and is formatted as follows depending on your AM/OpenAM 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/OpenAM 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.
- 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:
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:
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).
Pre-AM 6 example
A CTS-based session token looks similar to this:
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/OpenAM session cookie?
A. Yes you can using the Persistent Cookie authentication module. See Authentication and Single Sign-On Guide › Persistent Cookie Module for further information.
In pre-OpenAM 13, you can set the following advanced server properties instead to specify an expiration time:
- Set openam.session.persist_am_cookie to true.
- Set com.iplanet.am.cookie.timeToLive to the cookie lifetime in seconds.
See OpenAM 12 Administration Guide › Defining Authentication Services › Authenticating To OpenAM 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/OpenAM 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.
Q. Is there a limit to the size of a custom attribute when using SSOToken#setProperty()?
You can add and remove session properties using the REST API: Authentication and Single Sign-On Guide › Obtaining Information About Sessions.
Q. What other cookies does AM/OpenAM create?
- 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/OpenAM 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.
- DProPCookie - this cookie is created by AM/OpenAM 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.
- AMDistAuthCookie - this cookie is created by the Distributed Authentication Service (DAS) if you are using DAS in AM/OpenAM. This cookie is used to track which DAUI server the user belongs to. DAS is deprecated in OpenAM 13.0.
Q. How can I configure cookies to improve security and reduce the threat of cookie hijacking?
- Change the default cookie names. See How do I change the session cookie name for AM/OpenAM and Policy Agents (All versions)? for further information.
- Use Secure cookies (providing you use SSL connections throughout) and/or HTTPOnly cookies. See Installation Guide › Securing Installations for further information. There is a a known issue with setting Secure cookies in OpenAM 13.5: OPENAM-9515 (XUI does not enable Secure cookie flags for SSO tracking cookie on 13.5.0). This is fixed in OpenAM 13.5.1.
- 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 policy agents to use CDSSO; for it to make sense, you also need to have all communications through SSL and disable the setting by which policy agents trust certificates by default. Therefore, you should balance the increase in complexity with the actual risk of hijacking. See Authentication and Single Sign-On Guide › Protecting Against Cookie Hijacking for further information.
Q. How do I configure AM/OpenAM to use host-based cookies?
A. Leave the Cookie Domains list blank; AM/OpenAM 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:
- AM 5 and later console: navigate to: Configure > Global Services > Platform > Cookie Domains.
- OpenAM 13.5 console: navigate to: Configure > Global Services > System > Platform > Cookie Domains.
- Pre-OpenAM 13.5 console: navigate to: Configuration > System > 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.
You must restart the web application container in which AM/OpenAM runs to apply these configuration changes.
See Reference › Configuration Reference › Platform for further information.
There is a known issue with using host-based cookies: OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service). This is fixed in OpenAM 12.0.3 and 13.5. See OpenAM 12.0.0, 12.0.1, 12.0.2 and 13.0 login fails with User name/password combination is invalid error if you use host-based cookies for further information and resolution.
Q. What does the cookie domain default to?
A. As of OpenAM 13.5, 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).
In a OpenAM 13.0 and earlier, the cookie domain was set to the domain part of the FQDN.
Q. Why should I use the amlbcookie for load balancing?
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/OpenAM 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.
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 Release Notes › 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: Authentication and Single Sign-On Guide › Choosing Where to Store Sessions.
Q. How does the amlbcookie work in a failover scenario?
A. Session failover has been replaced in AM 5 with the concept of session high availability; this is enabled by default for all AM deployments. See AM 5 Release Notes › What's New › Cloud for further information.
If the load balancer has been configured to use the amlbcookie for routing (standard setup), session failovers (SFO) are handled per the following example in pre-AM 5 (assuming SFO is enabled):
If a session originates on AM1 and AM1 goes down, the load balancer routes the next request to AM2; AM2 gets the existing session from the CTS (if enabled) and the session is created on AM2. When AM1 is restored, the session should return to AM1 since the amlbcookie points to AM1.
It is important to be aware that AM/OpenAM does not do the routing and you do not need to make any manual changes to the amlbcookie to handle SFO.
Q. Why is the load balancer not using the amlbcookie in a SSL AM/OpenAM cluster?
A. If the load balancer simply passes all requests straight through to AM/OpenAM (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/OpenAM or use a new SSL connection (HTTPS) between the load balancer and AM/OpenAM.
Q. Do I need different cookie names if I am using one instance of AM/OpenAM 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/OpenAM. 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/OpenAM servers.
See How do I change the session cookie name for AM/OpenAM and Policy 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/OpenAM 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/OpenAM runs. See Reference › Advanced Properties for further information.
This property must be set to false if you use Wildfly as the AM/OpenAM web container with multiple cookie domains as discussed in Installation Guide › Handling Multiple Cookie Domains When Using Wildfly.
Q. Can I set a cookie on the top level domain?
Q. How does AM/OpenAM use the JSESSIONID cookie?
AM/OpenAM ignores this cookie and instead creates its own session cookie; this session cookie is called iPlanetDirectoryPro by default.