How to set a tamper-proof Salesforce session cookie with Apex

Imagine we have a website in which we want the user session to persist for a specific period, even when the user closes and reopens the browser. 

Our goal is to have operations/logic for a particular user persist on the website. Whenever the user returns to the site within a given amount of time using a session cookie.

There are a multitude of ways to store the session data. In this article, we are focusing on client-side storage (cookies). Cookies are small pieces of data that are transmitted from the server to the client (generally done once.) Then when the user comes back to the site, the cookies are sent back to the server. This allows us to track a single user across multiple connections to our site. 

Why should I care about the expiration?

Being able to easily expire user sessions allows for extra security measures. In our case, if we wanted to add a new feature that allows us to sign out of all sessions in other locations (machines where the user has logged in), this (expire session cookie) would force those other locations to re-authenticate before gaining access to the account.

This is a good security approach for when a user’s cookie is stolen or his credentials are compromised. Upon changing his password all his sessions are invalidated. An attack using an old cookie cannot continue to wreak havoc on the user’s account.

Signing your session cookie

As we know, all data stored on the client-side could potentially be compromised as a user can maliciously tamper with it. And since we are not able to avoid it, we might provide the server with the feature to recognize this manipulation. 

This feature consists of a cryptographically signed cookie. Upon receiving the cookie from the client, verify that the signature matches what you are expecting. 

HMAC (Hash-based message authentication code) is a cryptographic construct that uses a hashing algorithm (SHA-1, SHA-256, SHA-3) to create a MAC (message authentication code) with a secret key. Salesforce provides us with a class named Crypto that contains methods for creating digests, message authentication codes, and signatures, as well as encrypting and decrypting information. Click here to see more about Crypto.

Let’s code!

We are going to create a global helper class for signing session cookies. That we will be able to re-use in any part of our project.

Within this class, we are using other Salesforce helper classes such as Blob (Contains methods for the Blob primitive data type) and EncodingUtil (to encode and decode URL strings, and convert strings to hexadecimal format).

This allows us to do the following:

We can then send that to the client that requested the page. Once the client visits the next page, their browser will send that same cookie back to use. 

Assuming we need to store the ‘session ID’, we would get this as result:

Note: 

All cookies created from Salesforce contain ‘apex__’ as a prefix and are encoded before being set for the page.  Learn more about cookies here. 

To retrieve and verify the data was not tampered with, we could do the following:

If the MAC is verified, it means that the data was not tampered with by the user and we can continue our business logic. 

Real Secret Key

For extra security measures, we might set an auxiliary CustomSetting for storing AES secret keys. We will create a Secret__c CustomSetting with a field named Base64HmacKey__c.

Now, we are going to refactor our code to include this new approach:

• Add a new variable to our helper class

• Add a new function to get the secret key from the CustomSetting

• Lastly, modify the private variable named SECRET_KEY

Now we have better handling of our secret key.

Encryption

When using client-side storage, it may be beneficial to encrypt the data to add an extra layer of security. Even when encrypting the data, you need to continue using a MAC.

Using just encryption will not protect you against decrypting bad data because an attacker decided to provide invalid data. Signing the cookie data with a MAC makes sure that the attacker is not able to mess with the ciphertext.

If you’ve made it this far, thanks for reading! Also, if you are interested in Salesforce development go and check our latest articles here.