Cookies have been used for decades as a solution for persisting data -- be it the contents of a shopping cart, or a timezone setting, or a user identity -- across a given client's interaction with a website. WebSphere Application Server (WAS) uses cookies for a few different purposes of its own. In this article we are going to focus on one of the most important WAS cookies: the LtpaToken2 cookie, which is used to persist a client's authentication state. Cookies used in this way are sometimes referred to as "SSO cookies"; in this article we'll refer to it as "the LtpaToken2 cookie" because that has been the default name of the cookie in WAS (and Liberty) for a long time, but it's important to note that the cookie name is configurable.
The LtpaToken2 cookie is an encrypted collection of data which is generated and sent to the client after a successful authentication to WAS. The cookie contains a copy of the user's authentication state -- information needed to make authorization decisions -- which in the simplest case consists of the username and the names of any groups. Additionally, it contains some metadata information describing its expiration time and the address of the server on which it was generated.
In more complex scenarios, the user's authentication state consists of more than just a username and group names. For example, when a user authenticates using external tokens such as those from a SAML or OIDC login, the external tokens may be required for authorization decisions later on, and so they must be stored along with the rest of the user's authentication state. This presents a problem, because cookies can only be so large before browsers, web servers, and other players in the HTTP flow start to reject the cookie. In general, most software involved in the HTTP flow restricts cookie sizes to around 5kb in order to ensure that request and response data do not balloon to unmanageable sizes. For WAS, this means that much of the time external tokens cannot be stored directly in the LtpaToken2 cookie. Instead, WAS puts a marker within the cookie indicating that there is some data that could not fit, and then it stores that data in-memory, so that whenever the LtpaToken2 cookie is consumed, this data can be retrieved and attached to the user's authentication state during request and response processing on the server.
There are other scenarios where a user's authentication state cannot fit into the LtpaToken2 cookie. A very large amount of group memberships, a custom TAI, or even a custom LoginModule can lead to the same condition. A good rule of thumb is that if something other than form or basic auth login is being used, then most likely the user's entire authentication state will not fit into the LtpaToken2 cookie.
An LtpaToken2 cookie can be used to authenticate not just to the WAS server where it originated (called the "originating" server), but to any other WAS server (a "downstream" server) which shares the keys that were used to encrypt the token in the first place.
When the cookie is sent back to the originating server, the server first decrypts the cookie using its LTPA keys, and then reads the cookie contents to determine whether it needs to retrieve additional data elements (called "attributes") from its in-memory storage. Going back to our original example, at this step WAS would retrieve the SAML, OIDC, or other third-party token. This process is very quick and from a performance perspective essentially the same as a scenario where the user's entire authentication state fits within the cookie. When the cookie is sent to a server other than the one where it originated, a process called "security attribute propagation" must occur in order for the login to succeed.
Security attribute propagation is the name for the process that a downstream WAS server goes through to retrieve the security attributes (going back to our example again, a SAML, OIDC, or other third-party token) from the in-memory data store on the originating WAS server. The downstream WAS server first reads the originating server information from within the decrypted LtpaToken2 cookie, and then it makes an outbound call to an MBean on the originating server. The response from the originating server contains the additional security attributes for the user, which the downstream server then attaches to the user's authentication state and stores within its own in-memory data store for future authentications. This simple process has a powerful effect: the user's complete authentication state, no matter how detailed, can essentially be stored within a single small cookie in the browser and used across any number of WAS servers.
There are some caveats of course. Depending on how large the security attributes are, the process of retrieving them may cause a delay that is visible to the end-user. If this occurs, the only real way to resolve it is to re-evaluate the initial authentication method to see if there are any data that can be omitted. Also, failures can occur during data transmission -- the downstream server must be able to communicate with the originating server on the network, and it must trust the originating server's SSL certificate.
When these caveats preclude security attribute propagation, it can be disabled. This will result in the end-user having to re-authenticate when they send their LtpaToken2 cookie to any downstream WAS server, and the resulting login will write a new LtpaToken2 cookie to the browser, so it's recommended to change the name of the LtpaToken2 cookie in the Security > Web and SIP Security > Single Sign On panel of the WAS admin console to avoid this collision. To disable security attribute propagation, toggle the checkbox labeled "Web inbound security attribute propagation" in the same Security > Web and SIP Security > Single Sign On panel. It's also worth noting that Liberty does not support security attribute propagation; on that runtime the current recommendation is to use the more portable jwtSso cookie format rather than LTPA when there is a need for the user's authentication state to be sent to multiple servers.
In most situations, security attribute propagation works quietly in the background to enable the seamless persistence of a user's authentication state across any number of WAS servers. This can greatly reduce the complexity of enabling large environments for third-party authentication mechanisms such as SAML Web SSO, OpenId Connect, and even custom TAIs. It's important to ensure that your WAS environments are compatible with this feature from a network perspective, and to know when you might want to disable it to improve performance or to overcome environmental limitations.