Cookies in AM/OpenAM

This book provides information on cookies in AM/OpenAM.


FAQ: Cookies in AM/OpenAM

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

Frequently asked questions

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.

Caution

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. 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?

A. The AM/OpenAM 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/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.

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).

Pre-AM 6 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/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()?

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/OpenAM server or the size of cookie. 

Note

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?

A. AM/OpenAM 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/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?

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

Note

You cannot use HttpOnly cookies in OpenAM 13.5.x and earlier if you are using the XUI interface since XUI makes REST calls through JavaScript®. HttpOnly cookies are meant to be transmitted only over HTTP and HTTPS, and not through non-HTTP methods, such as JavaScript functions. This is documented in RFC 6265. AM 5 introduces support for HttpOnly cookies as detailed in AM 5 Release Notes › Important Changes to Existing Functionality

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.
Note

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.

Note

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?

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/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.

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 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.

Pre-AM 5

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.

Note

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?

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/OpenAM use the JSESSIONID cookie?

A. AM/OpenAM 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/OpenAM ignores this cookie and instead creates its own session cookie; this session cookie is called iPlanetDirectoryPro by default.

See Also

Cookies in AM/OpenAM

Authentication and Single Sign-On Guide › About HTTP Cookies

Installation Guide › Securing Installations 

Reference › Configuration Reference › Platform

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-11044 (Stop encrypting the session id prefix)

OPENAM-9515 (XUI does not enable Secure cookie flags for SSO tracking cookie on 13.5.0)

OPENAM-9378 (OpenAM 13.5 now defaults to using FQDN as cookie domain)

OPENAM-9363 (Can not log in when reverse proxy in front of OpenAM)

OPENAM-8336 (XUI+REST authentication with chains must have sticky load balancing).

OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service)


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

The purpose of this article is to provide information on changing the name of the AM/OpenAM 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.

Overview

Once you have changed the AM/OpenAM session cookie name, you must also update the session cookie name in your policy 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/OpenAM 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/OpenAM session cookie

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > Security > Cookie > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > Security > Cookie Name and enter the new session 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.
  • 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
Note

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

Renaming the agent session cookie in AM/OpenAM

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

Web Policy Agent

  • AM 5 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • 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.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgents
    • Property: cookieName

Java Policy 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.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > SSO > Cookie Name and enter the new session cookie name.
  • 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.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2eeAgents
    • Property: amCookieName
Note

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

Renaming the default agent session cookie in AM/OpenAM

You can change the name of this cookie using ssoadm:

Web Policy 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 Policy 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/OpenAM runs to apply these configuration changes.

Renaming the agent group session cookie in AM/OpenAM

You can change the name of this cookie using either the console, ssoadm or Amster (AM 5 and later):

Web Policy 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.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • 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.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: WebAgentGroups
    • Property: cookieName

Java Policy 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.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Group Name] > SSO > Cookie Name and enter the new session cookie name.
  • 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.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: J2EEAgentGroups
    • Property: amCookieName
Note

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

See Also

Installation Guide › Avoiding Obvious Defaults

Reference › Configuration Reference › Deployment Configuration

Reference › Command Line Tools › ssoadm

Setup and Maintenance Guide › Setting Up Policy Agent Profiles

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-3631 (Renaming of SSO Token Cookie to substring of request URL will cause failed agent evaluation.)


How do I change the persistent cookie name (session-jwt) in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the persistent cookie name in AM/OpenAM. The persistent cookie is called session-jwt by default and is created via the Persistent Cookie module.

Overview

The property that relates to the persistent cookie name (openam-auth-persistent-cookie-name) is not exposed via the console or ssoadm by default in earlier releases. However, in those releases you can still change it via the console.

The following sections detail how to change the persistent cookie name depending on which version you are using:

Changing the persistent cookie name (AM 5.5 and later; OpenAM 13.5.2)

You can change the name of the persistent cookie as follows using either the console, Amster (AM 5.5 and later) or ssoadm:

  • Console: navigate to: Realms > [Realm Name] > Authentication > Modules > Persistent Cookie Module > Persistent Cookie Name and enter the new cookie name.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
    • Entity: PersistentCookieModule
    • Property: cookieName
  • ssoadm: enter the following command:
    $ ./ssoadm update-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile] -a openam-auth-persistent-cookie-name=[name]
    replacing [realmname], [modulename], [adminID], [passwordfile] and [name] with appropriate values.

Changing the persistent cookie name (AM 5, 5.1.x; pre-OpenAM 13.5.2)

You can change the name of the persistent cookie as follows in the console:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] and click the pencil icon against the Persistent Cookie module to edit the module properties. Enter the following Key and Value under Options:
    KEY                                  VALUE
    openam-auth-persistent-cookie-name   newName
    where newName is the new name for the persistent cookie.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Authentication Chaining > [Chain Name] and enter the following in the Options field against the Persistent Cookie module:
    openam-auth-persistent-cookie-name=newName
    where newName is the new name for the persistent cookie.

See Also

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

FAQ: Cookies in AM/OpenAM

Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

Persistent cookie is no longer created in AM/OpenAM (All versions)

Session quotas not limiting active user sessions in AM/OpenAM (All versions) when persistent cookies are used

Authentication modules in AM/OpenAM

Authentication and Single Sign-On Guide › Persistent Cookie Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7781 (persistent cookie auth module does not allow to change cookie name by default)


How do I obtain the user's session ID in AM/OpenAM (All versions) when browser cookies are disabled?

The purpose of this article is provide information on obtaining a user's session ID in AM/OpenAM when browser cookies are disabled.

Obtaining the user's session ID

The standard AM/OpenAM login page can only deliver the user's session ID in a Set-Cookie header. If your clients do not support browser cookies, you must use a different authentication interface instead, such as the REST API.

The policy agents are capable of extracting the session ID from the URL itself if you set it as a query parameter, for example: 

agent.example.com/index.jsp?iPlanetDirectoryPro=<sessionid>

However, using a query parameter like this can result in your session IDs being logged in your access logs, which is not secure. Therefore, although possible to obtain the session ID when browser cookies are disabled, it is recommended that you do use cookies for the session ID.

See Also

FAQ: Cookies in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Single Sign-On

Development Guide › Developing with the REST API

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I clear cookies in AM/OpenAM (All versions) in different browsers?

The purpose of this article is to provide guidance on how to clear cookies in AM/OpenAM for end users and system administrators.

Overview

Cookies are used for the following purposes in AM/OpenAM if you use CTS-based sessions:

  • Internal authentication session - default name AMSESSION.
  • Authentication token cookie (post authentication success) - default name iPlanetDirectoryPro. In CDSSO environments, there may be multiple entries with differing domains.
  • Load balancer cookie - default name amlbcookie.

Once AM/OpenAM has authenticated successfully, the AMSESSION is removed/invalidated and the iPlanetDirectoryPro cookie is created. The amlbcookie is created on first access to AM/OpenAM. Depending on your policy agent version, the amlbcookie can also get created during CDSSO. See OPENAM-2396 (Agents should set 'amlbcookie' when running in CDSSO mode) for further information.

See FAQ: Cookies in AM/OpenAM for further information on cookies in AM/OpenAM.

Why should I clear cookies in AM/OpenAM?

You may need to clear your cookies for the following reasons:

  • To log in as a different user.
  • To log in to a different node in the cluster.
  • To refresh the session cookie if it has become stale and the entry no longer maps to an existing session.
  • To prove that it is a clean login.
Note

Clearing other cached elements in addition to cookies is useful if you are customizing the interface and want to reload UI elements. Additionally, clearing cookies and other cached data as described in this article may impact other web pages and applications using the browser, since you are clearing data relating to all sites.

Deleting cookies on a one-off basis

Note

The instructions given here are subject to change since these browser interfaces change frequently; however, these instructions should be sufficient to point you in the right direction even if the interface has changed and links to the browsers' documentation are given in the See Also section for the latest information.

Chrome™ browser

  1. Open the Chrome browser.
  2. Click More on your browser toolbar (right-hand side) and select More Tools > Clear Browsing Data...
  3. Select the beginning of time in the Clear the following items from drop-down list.
  4. Ensure at least the following check boxes are selected:
    • Cookies and other site data
    • Passwords
    • Autofill form data
  5. Click Clear browsing data.

Firefox® browser

  1. Open the Firefox browser.
  2. Click the menu button  on your browser toolbar (right-hand side) and select History > Clear Recent History.
  3. Select Everything in the Time range to clear drop-down list.
  4. Ensure at least the following check boxes are selected:
    • Form & Search History
    • Cookies
    • Active Logins
  5. Click Clear Now.

Microsoft Edge browser

  1. Open the Edge browser.
  2. Select Hub  > History
  3. Select Clear all history.
  4. Ensure at least the following check boxes are selected:
    • Cookies and saved website data
    • Form data
    • Passwords
  5. Click Clear.

Internet Explorer®

  1. Open the Internet Explorer browser.
  2. Select Internet Options from the Tools menu.
  3. Stay on the General tab and click the Delete button in the Browsing history section. 
  4. Ensure at least the Cookies check box is selected.
  5. Click Delete.

Safari® browser

  1. Open the Safari browser.
  2. Select Clear History... from the History menu.
  3. Select all history from the Clear drop-down list.
  4. Click Clear History.

Deleting cookies each time you exit or quit the browser

Note

The instructions given here are subject to change since these browser interfaces change frequently; however, these instructions should be sufficient to point you in the right direction even if the interface has changed and links to the browsers' documentation are given in the See Also section for the latest information.

Chrome browser

  1. Open the Chrome browser.
  2. Click More on your browser toolbar (right-hand side) and select Settings.
  3. Scroll down to the On Start-up section, select either Open the New Tab Page or Open a specific page or set of pages.
  4. Click Advanced to reveal Privacy and security options.
  5. Select Content Settings > Cookies > Keep local data only until you quit your browser.

Firefox browser

  1. Open the Firefox browser.
  2. Click the menu button  on your browser toolbar (right-hand side) and select Preferences > Privacy.
  3. Choose one of the following options from the drop-down list under History:
    • Never remember history OR
    • Use custom settings for history. If you choose this option, you should:
      • Clear the Remember search and form history check box.
      • Change the Keep until option to: I close Firefox or select the Clear history when Firefox closes check box and specify which types of data should be cleared by clicking Settings. You should ensure at least the following check boxes are selected: Active Logins, Form & Search History and Cookies.
  4. Restart Firefox when prompted for the settings to take effect.

Microsoft Edge browser

  1. Open the Edge browser.
  2. Select Hub  > History
  3. Select Clear all history.
  4. Ensure at least the following check boxes are selected:
    • Cookies and saved website data
    • Form data
    • Passwords
  5. Switch the Always clear this when I close the browser option to On.

Internet Explorer®

  1. Open the Internet Explorer browser.
  2. Select Internet Options from the Tools menu.
  3. Stay on the General tab and select the Delete browsing history on exit check box in the Browsing history section. 
  4.  Click Apply.

Safari browser

  1. Open the Safari browser.
  2. Select Preferences from the Safari menu.
  3. Stay on the General tab and check the following settings:
    • Safari opens with - this should be set to A new window.
    • Remove history items - set this to After one day.
Note

You must remember that closing a Mac OS application using the red X does not actually quit the application and you will still see it running in the Dock. To ensure cookies are cleared automatically when the browser is quit, you must quit the browser using either the Quit option on the application menu or right-click on the Dock icon and select Quit. 

See Also

FAQ: Cookies in AM/OpenAM

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

Authentication and Single Sign-On Guide › Implementing Single Sign-On › About HTTP Cookies

Installation Guide › Securing Installations 

Clear, enable, and manage cookies in Chrome

Firefox - Delete browsing, search and download history on Firefox

View and delete browser history in Microsoft Edge

How to delete cookie files in Internet Explorer

Safari for Mac: Clear your Safari browsing history

Safari for Mac: Manage cookies and website data using Safari

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2396 (Agents should set 'amlbcookie' when running in CDSSO mode)


Known Issues


Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

The purpose of this article is to provide assistance if the persistent cookie (called session-jwt by default) is not created in AM/OpenAM after you have changed the default keystore and a NullPointerException is shown in the logs. This applies to the persistent cookie created via the Persistent Cookie module.

Symptoms

The persistent cookie is not created.

An error similar to the following is shown in the log (when debug level is set to Message):

postLoginProcess Class Name is : org.forgerock.openam.authentication.modules.persistentcookie.PersistentCookieAuthModule
amAuth:02/25/2014 04:21:39:487 PM GMT: Thread[http-bio-8443-exec-5,5,main]
Error 
java.lang.NullPointerException
    at org.forgerock.common.util.KeystoreManager.getPublicKey(KeystoreManager.java:128)
    at org.forgerock.jaspi.modules.session.jwt.JwtSessionModule.createSessionJwtCookie(JwtSessionModule.java:428)
    at org.forgerock.jaspi.modules.session.jwt.JwtSessionModule.secureResponse(JwtSessionModule.java:407) 

Recent Changes

Changed the AM/OpenAM keystore.

Causes

The JSON Web Token (JWT) cookie is encrypted using the default test key in the default AM/OpenAM keystore. The default test key cannot be found if the keystore changes, which causes the Persistent Cookie module to fail.

Solution

This issue can be resolved by updating the key from its default value of test to the value associated with the new keystore. You can do this globally or in a specific realm, where realm level take precedence over the global level.

Global

You can update this value globally using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Security > Persistent Cookie Encryption Certificate Alias and change test to the name of your actual key.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Core > Security > Organization Authentication Certificate Alias and change test to the name of your actual key. This option is called Persistent Cookie Encryption Certificate Alias in OpenAM 13.0
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[keyname]
    replacing [adminID], [passwordfile] and [keyname] with appropriate values.

Realm level

You can update this value in a specific realm using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and change test to the name of your actual key.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Security > Organization Authentication Certificate Alias and change test to the name of your actual key.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=[keyname]
    replacing [realmname], [adminID], [passwordfile] and [keyname] with appropriate values.
Note

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

See Also

Persistent cookie is no longer created in AM/OpenAM (All versions)

How do I change the persistent cookie name (session-jwt) in AM/OpenAM (All versions)?

Setup and Maintenance Guide › Changing Default Key Aliases

Authentication and Single Sign-On Guide › Implementing Authentication › Persistent Cookie Module

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-4370 (NPE when trying to authenticate via the REST authentication service)


Session quotas not limiting active user sessions in AM/OpenAM (All versions) when persistent cookies are used

The purpose of this article is to provide information when session quotas do not appear to be limiting the number of active user sessions in AM/OpenAM when persistent cookies are used.

Symptoms

The number of active sessions per user appears to exceed the number specified in Active User Sessions.

Recent Changes

Configured session quotas with Resulting behavior if session quota exhausted option set to anything other than DENY_ACCESS.

Enabled persistent cookies.

Causes

The persistent cookie feature enables a previously destroyed session to be resumed by refreshing the browser. When used in conjunction with session quotas, it can appear that there are more sessions than the quota should allow. In fact, each time a session is resumed using refresh, a session in another browser is destroyed, thereby maintaining the quota; as this all occurs seamlessly, it can appear that there are endless sessions, but actually the number of active sessions never exceeds the limit specified.

Solution

The functionality is working correctly and sessions are limited as per the session quota.

See Also

Authentication and Single Sign-On Guide › Implementing Session Options › Implementing Session Quotas

Authentication and Single Sign-On Guide › Implementing Authentication › Persistent Cookie Module

Session Quota basics

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-2414 (Session quota does not work when SFO is enabled)


401 Unauthorized: Session has timed out response when authenticating to AM (All versions)

The purpose of this article is to provide assistance if you receive a "Session has timed out" response when authenticating to a single module in AM. This error occurs when you have a multi-server setup in a load balanced environment that does not use session stickiness (amlbcookie).

Symptoms

The browser stops responding after the user enters their credentials. 

The following response is shown if you use a REST call or examine network traffic using your browser's Developer Tools:

{"code":401,"reason":"Unauthorized","message":"Session has timed out"}

The corresponding error is shown in the Authentication debug log:

Caused by: com.sun.identity.authentication.service.AuthException: Session has timed out|session_timeout.jsp 
   at com.sun.identity.authentication.service.AuthUtils.getAuthContext(AuthUtils.java:284) 
   at org.forgerock.openam.core.rest.authn.core.wrappers.CoreServicesWrapper.getAuthContext(CoreServicesWrapper.java:51) 
   at org.forgerock.openam.core.rest.authn.core.LoginAuthenticator.getAuthContext(LoginAuthenticator.java:207) 
   at org.forgerock.openam.core.rest.authn.core.LoginAuthenticator.getLoginProcess(LoginAuthenticator.java:92) 
   at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:212) 
... 83 more 
Caused by: com.sun.identity.authentication.service.AuthException: Session has timed out|session_timeout.jsp 

Recent Changes

Upgraded to, or installed AM 5 or later.

Implemented or changed your load balancing configuration so that it does not have session stickiness.

Causes

Sticky load balancing is a requirement in AM 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). Without sticky load balancing, the load balancer may not send the request to the right AM server, which causes this error.

Solution

This issue can be resolved using one of the following options as appropriate to your environment:

  • Implement sticky load balancing using the amlbcookie. See FAQ: Cookies in AM/OpenAM for further information on using the amlbcookie for load balancing.
  • Use Active/Passive configuration for the AM nodes; providing each node can handle the traffic volume, you will still have failover but ensure traffic is routed to the correct server.
  • Upgrade to AM 6 or later; you can download this from BackStage. You can then migrate to authentication trees and configure the storage location for authentication sessions so they are not stored in memory. See the following links for further information: 

See Also

Required callback not found in JSON response when authenticating to AM/OpenAM (All versions)

Cookies in AM/OpenAM

Installation Guide › Installing and Starting Servers › Configuring Load Balancing for a Site

Authentication and Single Sign-On Guide › Choosing Where to Store Sessions

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12675 (One-step authentication in a cluster requires sticky load balancing)

OPENAM-8336 (XUI+REST authentication with chains must have sticky load balancing)


Required callback not found in JSON response when authenticating to AM/OpenAM (All versions)

The purpose of this article is to provide assistance if you receive either a "Required callback not found in JSON response" message or an "Incorrect number of callbacks found in JSON response" message when authenticating to AM/OpenAM in a load balanced environment that does not use session stickiness (amlbcookie). This error occurs when you are using the XUI in a multi-server setup without sticky load balancing and authentication to a chain takes place across multiple servers.

Symptoms

One of the following responses is shown if you use a REST call or examine network traffic using your browser's Developer Tools:

{"code":400,"reason":"Bad Request","message":"Required callback not found in JSON response"}

{"code":400,"reason":"Bad Request","message":"Incorrect number of callbacks found in JSON response"}

The corresponding error is also shown in the Authentication debug log:

  • Required callback not found in JSON response:
    amAuthREST:10/11/2016 10:07:23:816 AM GMT: Thread[http-bio-8080-exec-8,5,main]
    AuthenticationService.authenticate() :: Rest Authentication Exception
    org.forgerock.openam.forgerockrest.authn.exceptions.RestAuthException: Required callback not found in JSON response
       at org.forgerock.openam.forgerockrest.authn.RestAuthCallbackHandlerManager.handleJsonCallbacks(RestAuthCallbackHandlerManager.java:149)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.handleCallbacks(RestAuthenticationHandler.java:304)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.processAuthentication(RestAuthenticationHandler.java:235)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:160)
       at org.forgerock.openam.forgerockrest.authn.RestAuthenticationHandler.continueAuthentication(RestAuthenticationHandler.java:109)
       at org.forgerock.openam.forgerockrest.authn.restlet.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:127)
    
  • Incorrect number of callbacks found in JSON response
    amAuthREST:10/11/2016 10:07:23:816 AM GMT: Thread[http-bio-8080-exec-2,5,main]: TransactionId[1a9f4c3c-01ac-8219-1234-693e9d8d7846-717]
    AuthenticationService.authenticate() :: Rest Authentication Exception
    org.forgerock.openam.core.rest.authn.exceptions.RestAuthException: Incorrect number of callbacks found in JSON response
       at org.forgerock.openam.core.rest.authn.RestAuthCallbackHandlerManager.handleJsonCallbacks(RestAuthCallbackHandlerManager.java:134)
       at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.handleCallbacks(RestAuthenticationHandler.java:317)
    
    

Recent Changes

Implemented or changed your load balancing configuration so that it does not have session stickiness.

Causes

If you use XUI, sticky load balancing is a requirement if you have multiple authentication modules in an authentication chain. This is a known issue: OPENAM-8336 (XUI+REST authentication with chains must have sticky load balancing). Without sticky load balancing, the load balancer may not send the request to the right AM/OpenAM server, which causes this error.

This error occurs in several other situations, not just when using two authentication modules in a chain. This includes when a user changes a password when their password has expired, see  OPENAM-9263 (Password Reset results in "Incorrect number of callbacks found in JSON Response" with LB)

Solution

This issue can be resolved using one of the following options as appropriate to your environment:

  • Implement sticky load balancing using the amlbcookie. See FAQ: Cookies in AM/OpenAM for further information on using the amlbcookie for load balancing.
  • Configure AM/OpenAM to use http and terminate SSL at the load balancer.
  • Configure the load balancer to terminate SSL and re-encrypt instead of using passthrough for SSL if https is required on all traffic.
  • Add another component (such as HAProxy) between the load balancer and AM/OpenAM that can do SSL offloading (and re-encryption if needed) instead of the load balancer.
  • Use Active/Passive configuration for the AM/OpenAM nodes; providing each node can handle the traffic volume, you will still have failover but ensure traffic is routed to the correct server.
  • Upgrade to AM 6 or later; you can download this from BackStage. You can then migrate to authentication trees and configure the storage location for authentication sessions so they are not stored in memory. See the following links for further information: 

See Also

401 Unauthorized: Session has timed out response when authenticating to AM (All versions)

FAQ: Cookies in AM/OpenAM

Installation Guide › Installing and Starting Servers › Configuring Load Balancing for a Site

Authentication and Single Sign-On Guide › Choosing Where to Store Sessions

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9719 (session upgrade fails in combination with SAML-based SSO)

OPENAM-9263 (Password Reset results in "Incorrect number of callbacks found in JSON Response" with LB)

OPENAM-8336 (XUI+REST authentication with chains must have sticky load balancing)

OPENAM-8269 ("AuthId JWT Signature not valid" error in multi-instance deployments on 13)


Login to AM/OpenAM (All versions) fails with valid username/password after enabling Secure cookies

The purpose of this article is to provide assistance if login to AM/OpenAM fails for all users (including amadmin) even though they are using valid credentials. This issue can affect both the XUI and Classic UI when you are using a non-SSL connection and you have enabled Secure cookies.

Symptoms

When logging into AM/OpenAM using an HTTP connection, login fails:

  • If you are using the Classic UI, login fails without an error and you are redirected back to the AM/OpenAM login page.
  • If you are using the XUI, login fails but you remain on the login page and a "Login/password combination is invalid." message is displayed.

This issue can affect both administrators (preventing access to the console) and users (preventing access to pages such as the User profile). Often it will seem to only affect administrators, with users still able to log in. This happens because users are often connecting to a HTTPS connection, whereas the administrator is attempting to use an internal non-secured network.

An error similar to the following is shown in the restAuthenticationFilter debug log:

restAuthenticationFilter:07/26/2015 12:41:11:165 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Filter init param, context-factory-class, not set. Falling back to the DefaultServerContextFactory.
restAuthenticationFilter:07/26/2015 12:41:11:173 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Filter init param, audit-api-class, not set. Falling back to the NoOp Audit Api.
restAuthenticationFilter:07/26/2015 12:41:11:183 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Created module, className: org.forgerock.openam.jaspi.modules.session.OpenAMSessionModule
restAuthenticationFilter:07/26/2015 12:41:11:585 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Finished initialising the DefaultRuntimeInjector
restAuthenticationFilter:07/26/2015 12:41:11:586 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Filter init param, runtime-injector-class, not set. Falling back to the DefaultRuntimeInjector.
restAuthenticationFilter:07/26/2015 12:41:11:586 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Initialising the JaspiRuntime
restAuthenticationFilter:07/26/2015 12:41:11:603 PM EDT: Thread[http-bio-8080-exec-7,5,main]
OpenAMSessionModule has successfully authenticated the client
restAuthenticationFilter:07/26/2015 12:41:11:603 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Setting principal name, null, and 0 context values on to the request.
restAuthenticationFilter:07/26/2015 12:41:11:604 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Successfully validated request.
restAuthenticationFilter:07/26/2015 12:41:11:918 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Successfully secured response.
restAuthenticationFilter:07/26/2015 12:41:11:992 PM EDT: Thread[http-bio-8080-exec-8,5,main]
OpenAMSessionModule has failed to authenticated the client, passing to Auth Modules
restAuthenticationFilter:07/26/2015 12:41:11:993 PM EDT: Thread[http-bio-8080-exec-8,5,main]
Auditing authentication result
restAuthenticationFilter:07/26/2015 12:41:11:995 PM EDT: Thread[http-bio-8080-exec-8,5,main]
Authentication has failed.
restAuthenticationFilter:07/26/2015 12:41:11:998 PM EDT: Thread[http-bio-8080-exec-8,5,main]
Access Denied
org.forgerock.jaspi.exceptions.JaspiAuthException: Access Denied
	at org.forgerock.jaspi.runtime.context.ContextHandler.handleCompletion(ContextHandler.java:131)
	at org.forgerock.jaspi.runtime.context.JaspiServerAuthContext.validateRequest(JaspiServerAuthContext.java:244)
	at org.forgerock.jaspi.runtime.JaspiRuntime.processMessage(JaspiRuntime.java:160)
	at org.forgerock.jaspi.JaspiRuntimeFilter.doFilter(JaspiRuntimeFilter.java:131)
...

You can use your browser's developer tools to view the HTTP Headers; you will notice that the first POST call to authenticate (/json/authenticate) is successful, whereas the second POST call to retrieve the ID (json/users?_action=idFromSession) fails with a 401 Unauthorized response:

{"code":401,"reason":"Unauthorized","message":"Access Denied"}

Recent Changes

Enabled Secure cookies (com.iplanet.am.cookie.secure=true) but did not implement secured (HTTPS) connections for all communications with AM/OpenAM. This could occur for example, if you were testing SSL or had only partially implemented SSL for AM/OpenAM.

Causes

If you have enabled AM/OpenAM to set cookies in secure mode, the browser will only return the session cookie if a secure protocol such as HTTPS is used; the cookie will not be returned over non-SSL connections. Although you have successfully authenticated, the cookie containing the session token is not passed to AM/OpenAM, which prevents login from succeeding. 

Solution

This issue can be resolved by either using a secured HTTPS connection to access AM/OpenAM or by disabling Secure cookies. The approach you take depends on your plans for SSL.  

  • If you have enabled SSL in AM/OpenAM, you can access AM/OpenAM using a secured HTTPS connection, where the login URL for the console would be similar to this:
    https://host1.example.com:8443/openam/XUI/#login/
  • If you have not enabled SSL, you should disable Secure cookies. Given that the console is unaccessible, you must do this via ssoadm by entering the following command:
    $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s [server] -a com.iplanet.am.cookie.secure=false
    
    replacing [adminID], [passwordfile] and [server] with appropriate values, where [server] is 'default' or the server name depending on how you configured SSL.
Note

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

See Also

How do I enable SSL in AM/OpenAM (All versions) post-install?

How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

Login to AM/OpenAM console (All versions) fails for amadmin user

Installation Guide › Securing Installations

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9515 (XUI does not enable Secure cookie flags for SSO tracking cookie on 13.5.0)


Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9

The purpose of this article is to provide assistance if the login page does not load or ssoadm fails in AM running on Apache Tomcat™ 8.5 or 9. The following error is shown when this happens: "An invalid domain [.example.com] was specified for this cookie".

Symptoms

Note

OpenAM 12.x and 13.x support Tomcat 8.0.x, but not 8.5.x; Tomcat 8.5.x is supported in AM 5 and later; Tomcat 9 is supported in AM 6 and later.

Login page

The browser shows a Loading... message; no errors are logged when trying to accessing the login page in AM. 

ssoadm

The following response is shown when ssoadm fails:

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.

 The corresponding error is shown in the CoreSystem log when this happens:

ERROR: Exception during LoginIndex
java.lang.IllegalArgumentException: An invalid domain [.example.com] was specified for this cookie
        at org.apache.tomcat.util.http.Rfc6265CookieProcessor.validateDomain(Rfc6265CookieProcessor.java:183)
        at org.apache.tomcat.util.http.Rfc6265CookieProcessor.generateHeader(Rfc6265CookieProcessor.java:125)
        at org.apache.catalina.connector.Response.generateCookieString(Response.java:989)
        at org.apache.catalina.connector.Response.addCookie(Response.java:937)

Recent Changes

Upgraded Tomcat to 8.5 or 9.

Installed AM 5 or later in a new environment that is running Tomcat 8.5 or 9.

Causes

Tomcat enforces stricter checking for valid cookie domain values per RFC 1034 and RFC 6265. In Tomcat 8.0.x, a leading dot was required for cookie domains, whereas this is no longer permitted in 8.5 and later.

Solution

This issue can be resolved by correcting your cookie domain name as follows:

  1. Revert Tomcat to use the legacy cookie processor in order to get your system back up and running. Add the following line to the context.xml file (you should create this file in the /path/to/tomcat/webapps/openam/META-INF directory if it does not already exist):
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
    
    A default context.xml file exists in the /path/to/tomcat/conf directory; this applies to all web applications, but it is preferable to create separate contexts for individual web applications as needed. See Apache Tomcat 8.5 Configuration Reference - Defining a context for further information on contexts.
  2. Modify the cookie domain name to remove the leading dot. You can remove the leading dot from your cookie domain name (for example, example.com rather than .example.com) using either the console or ssoadm:
    • Console: navigate to: Configure > Global Services > Platform > Cookie Domains and modify the cookie domain.
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=["domainname"]
      
      replacing [adminID], [passwordfile] and ["domainname"] with appropriate values.
  3. Reinstate the default cookie processor in Tomcat by removing the line you added in step 1.

See Also

Apache Tomcat 8.5 Configuration Reference - The Cookie Processor Component

Apache Tomcat 8.5 Configuration Reference - Defining a context

FAQ: Cookies in AM/OpenAM

AM/OpenAM (All versions) fail to start due to SEVERE: ContainerBase.addChild: start: error on Apache Tomcat

ssoadm fails in AM/OpenAM (All versions) with FATAL ERROR: Cannot obtain Application SSO token

OpenAM 13.5 Release Notes › OpenAM Web Application Container Requirements

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8668 (Fresh install of OpenAM doesn't load the login page on some Tomcat versions)

OPENAM-1983 (Configuration fail with second level FQDN like "example.com")


Persistent cookie is no longer created in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if the persistent cookie is not created after installing AM, OpenAM 12.0.4, 13.5, or installing the patch for OpenAM Security Advisory #201605 and you see the following error: "Signing key must be at least 256-bits base64 encoded". The persistent cookie is called session-jwt by default and is created via the Persistent Cookie module.

Symptoms

The persistent cookie is not created; users who were logged in using a persistent cookie generated in an earlier version of AM/OpenAM or before the security patch was installed must log in again. 

The following error is shown in the Authentication log when the persistent cookie is not created:

amAuthO2PersistentCookie:08/10/2016 11:47:19:546 AM EST: Thread[ajp-bio-8010-exec-10,5,main]: TransactionId[ddda86b2-56b2-4fe7-8fb1-d8fb94c0455b-475] 
ERROR: Failed to initialise the underlying JASPI Server Auth Module. 
org.forgerock.caf.authentication.api.AuthenticationException: Signing key must be at least 256-bits base64 encoded 
   at org.forgerock.jaspi.modules.session.jwt.AbstractJwtSessionModule.initialize(AbstractJwtSessionModule.java:196)
   at org.forgerock.jaspi.modules.session.jwt.ServletJwtSessionModule.initialize(ServletJwtSessionModule.java:47) 
   at org.forgerock.jaspi.modules.session.jwt.ServletJwtSessionModule.initialize(ServletJwtSessionModule.java:68) 
   at org.forgerock.openam.authentication.modules.common.JaspiAuthModuleWrapper.init(JaspiAuthModuleWrapper.java:78) 
   at org.forgerock.openam.authentication.modules.common.AbstractLoginModuleBinder.init(AbstractLoginModuleBinder.java:66) 

Recent Changes

Upgraded to, or installed AM 5 or later.

Upgraded to, or installed OpenAM 12.0.4 or 13.5.

Installed the patch for OpenAM Security Advisory #201605.

Implemented the Persistent Cookie module. 

Causes

Changes were introduced in OpenAM 12.0.4 and 13.5, and the security patch to sign the persistent cookie using a user-specified HMAC signing key in addition to it being encrypted; this improves the security of persistent cookies.

Persistent cookies must now be signed by this HMAC signing key to be considered valid; additionally the HMAC signing key must be a random string that is at least 256 bits and base64 encoded. If the HMAC signing key is either missing or invalid, the persistent cookie will not be created and you will see this error.

Solution

This issue can be resolved by setting or correcting the value of the HMAC signing key.

  1. Generate a random string that is at least 256 bits and base64 encoded for your signing key. For example, you could a use a random number generator and then encode it using the OpenDJ base64 tool or you could use openssl:
    $ openssl rand -base64 32
  2. Update the value of the HMAC signing key for the Persistent Cookie module using either the console or ssoadm:
    • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Module Name] > HMAC Signing Key and enter the string you generated in step 1.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Modules > [Module Name] > HMAC Signing Key and enter the string you generated in step 1.
    • ssoadm: enter the following command:
      $ ./ssoadm update-auth-instance -e [realmname] -m [modulename] -u [adminID] -f [passwordfile] -a openam-auth-persistent-cookie-hmac-key=[string]
      replacing [realmname], [modulename], [adminID], [passwordfile] and [string] with appropriate values, where [string] is the string you generated in step 1.
Note

The Persistent Cookie Encryption Certificate Alias is used to encrypt the persistent cookie, the new HMAC key is for signing. Both are necessary for the persistent cookie to be created,  but the value of one does not depend on the other. See Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore for further information on changing this value.

See Also

OpenAM Security Advisory #201605

Persistent cookie is not created in AM/OpenAM (All versions) after changing default keystore

How do I change the persistent cookie name (session-jwt) in AM/OpenAM (All versions)?

OpenAM 13 Release Notes › Changes and Deprecated Functionality › Important Changes to Existing Functionality

Authentication and Single Sign-On Guide › Implementing Authentication › Persistent Cookie Module

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9558 (Organization Authentication Certificate Alias property has been renamed in 13)

OPENAM-9492 (XUI should validate the value of a Persistent Cookie HMAC Signing Key)

OPENAM-8264 (insufficient validator for service property 'iplanet-am-auth-hmac-signing-shared-secret')


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

The purpose of this article is to provide assistance if you cannot log into OpenAM 12.0.0, 12.0.1, 12.0.2 or 13.0 with any users, including amadmin, and receive a "User name/password combination is invalid" error even though your credentials are correct. This issue only occurs when you use host-based cookies and are using the XUI interface.

Symptoms

The following error is shown in the browser when you attempt to log in, even though your credentials are correct:

User name/password combination is invalid.

Logging in using the Classic UI works, although this UI is deprecated in OpenAM 13.

The following cookie domains property value is shown if you call the /openam/json/serverinfo endpoint:

{"domains":[], ...

The cookie domains list is returned without a value.

Recent Changes

Upgraded to, or installed OpenAM 12.0.0, 12.0.1, 12.0.2 or 13.0.

Switched from using the Classic UI to the XUI.

Configured OpenAM to use host-based cookies rather than domain cookies.

Causes

The empty cookie domains server property prevents the iPlanetDirectoryPro cookie being set, which prevents the login succeeding. This cookie domains property is incorrectly set when host-based cookies are used in the XUI; it should show as follows with double quotes when empty, which allows the iPlanetDirectoryPro cookie to be set: 

{"domains":[""], ...

Solution

This issue can be resolved by upgrading to OpenAM 12.0.3, 12.0.4, or OpenAM 13.5 and later; you can download this from BackStage.

Workaround

Alternatively, this issue can be resolved by setting the cookie domains to "" using the following ssoadm command:

$ ./ssoadm set-attr-defs -s iPlanetAMPlatformService -t Global -u [adminID] -f [passwordfile] -a iplanet-am-platform-cookie-domains=""

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

Note

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

See Also

Best practice for upgrading to OpenAM 13.x

Best practice for upgrading to OpenAM 12.x

Authentication fails in OpenAM 13.0 with an AuthId JWT Signature not valid error

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service)


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...