This blog is statically generated using Hugo, and served via Cloudflare Workers. But sometimes I want to write an article, and share it with just a few friends. Many of the popular content platforms out there have these features built in, but we would like to keep things in our own hands. The first step to any authorization mechanism is going to be user authentication and session management, so that’s what we will implement today. They say you should leave security features to the experts, but this is just a blog so we will use this as an opportunity to play with fire.
This is the first of a multi-part series where we explore this topic from the design phase.
Overview #
Session store #
For session management, we will be taking a stateless cookie-based approach. Signed token information will be encrypted and stored on the client-side. An alternative would be to have a session store on the server-side, which has its benefits. Server session stores would enable us to store more data, and also more easily revoke sessions. But we do not need either of those.
We know we are playing with fire, but let’s at least take a look at the security considerations that are out there. OWASP has published some amazing documentation that is worth a look for anybody, just to understand how nuanced this stuff is. There is a great session management cheatsheet along with a testing guide, along with a set of controls for session management in ASVS 4.0.
The OWASP control documentation indicates they are strongly aligned with NIST’s guidelines on digital identity management as SP 800-63B. We will take a look at those as well. The experts tell us that while conceptual understanding is the first step to strong software, the implementation itself requires strong secure coding practices, so we are still definitely playing with fire.
Authentication #
We will be implementing OIDC, a protocol based on the OAuth 2.0 framework. However, there is an updated set of specifications in IETF draft state, aptly named OAuth 2.1. It does not introduce anything new, and is a subset of the various OAuth 2.0 RFCs, to push for a safer and better defined standard. Some notable differences include deprecation of the implicit grant, and mandating of PKCE. Let’s keep an eye out for these differences as we move forward.
For our authentication, we will do our best to pay attention to CSRF and XSS details. While we are only concerned with logging in and identifying the user, there are other more general specifications such as FAPI 2.0 which defines a fairly precise set of requirements for secure operations. For example, even without OAuth 2.1, FAPI 2.0 required PKCE for the authorization code flows, and even specifies the code challenge method to be S256. Examining these prescriptive documents will help us understand how experts think, as we develop our own implementation.
For now I will assume that my friends all have a gmail.com email address, and will only provide a “Sign in with Google” option.
Session management #
Session management is generally implemented as some kind of key-value store, where the backing store can be a stateful server-side database, or it can be stored on the client-side. While the browser provides various storage mechanisms, there are various security pitfalls, and we will take the most common route of using secure http-only cookies. Setting cookies is straight forward using the built in Request and Response constructs in Cloudflare Workers. However, securing the contents of the cookies by means of encryption will take a little bit more thought.
There are many session implementations that we can look to for inspiration, such as Flask session, Gorilla session, and Fastify secure session. We will consider them for their security features, but our session cookie is intended primarily to hold the user’s id_token. While most session management libraries are written to hold data as a key-value pair, sometimes with a flash feature for one-time messages, we are going to implement the bare minimum to support saving id tokens into a cookie. For now, we should only need the id_token and not worry about an access_token, since we are not acting as a third party to access any specific user resources, such as Google Mail or Calendar.
My first thought for fulfilling my cryptography needs was to depend on external packages such as the jose package. It has zero dependencies and is compatible with Cloudflare Workers. The package is sponsored by Auth0, and the developer is also the author of other notable OAuth 2.0 related packages such as oauth4webapi, which is used in the nextjs-auth0 package. The code quality and documentation is very notable as well.
But we are already playing with fire, why not work directly with the WebCrypto APIs? We will not be implementing the encryption algorithms ourselves, but let’s learn how to use the cryptographic primitives provided by the standardized crypto APIs.
Encrypting our cookie payload #
Let’s assume that we have serialized some state including our id_token into a string. It could be a serialized JSON, a base64 encoding off some protobuf, anything really. We just want to encrypt this payload before it gets sent back as a cookie to the client browser. For this we will be using the AES symmetrical encryption algorithm in its GCM variant, as recommended in the OWASP cryptographic storage cheat sheet. While AES-GCM is often cited as the most secure form of AES, NIST’s SP 800-38D publication includes a list of recommendations about its use, which we should pay close attention to. While I am not well versed in cryptography, recent news indicates there are discussions around further refining these recommendations, including a revision of SP 800-38D and a call for comments regarding GCM and GMAC modes of operation.
All that to say, this is why we should really leave cryptography and implementation to the experts. For me, I am willing to risk the confidentiality of a few blog posts in the name of self-learning. According to the various publications, AES-GCM is known to have a catastrophic failure mode if the IV is reused. NIST is very clear about this:
“Across all instances of the authenticated encryption function with a given key, if even one IV is ever repeated, then the implementation may be vulnerable to the forgery attacks that are described in Ref 5 and summarized in Appendix A. In practice, this requirement is almost as important as the secrecy of the key.”
That’s pretty scary. There are recommendations about the length of the IV as well:
“For IVs, it is recommended that implementations restrict support to the length of 96 bits, to promote interoperability, efficiency, and simplicity of design.”
The MDN web docs for AesGcmParams echos this as well. The tag length used as part of the authentication defaults to 128-bits, which is also recommended by RFC5116. Reading through the API documentations after skimming the NIST publication, it feels good to know that professionals creating web standards are really trying to make sure we do not shoot ourselves in the foot.
My takeaway from this is that, using AES-GCM via WebCrypto requires us to do the basics
- Use a good random number generator for the IV and key. We will use
getRandomValues - Use a 96-bit IV for AES-GCM. We will make sure to do this when setting
iv - Rotate the keys. For the implementation we need to support decrypting with two keys, a new key and an old key.
Setting secure cookie attributes #
There are session cookies and permanent cookies, as described on the MDN page. We will be using session cookies because we want the cookie to be removed when the browser shuts down. This means that we will NOT specify Expires and Max-Age attributes.
We want to ensure our cookie is NOT accessible to JavaScript, since it is meant to be an opaque token. The following are the cookie attributes we will be setting, in accordance to the OWASP session management cheatsheet.
| Attribute | Value | Description |
|---|---|---|
| HttpOnly | N/A | This is an opaque session cookie that should not be readable from JavaScript |
| Secure | N/A | We only want to send this cookie on HTTPS requests. |
| SameSite | Lax | We want to ensure that if somebody clicking on an incoming link to our site will not have to reauthenticate. |
Note that we have not written any session timeout mechanism here. If we want to have a shorter session timeout than the id_token from Google, this would be an important consideration. However, Google’s documentation indicates that ID tokens are valid for up to 1 hour (3600 seconds), which is short enough for us. If these tokens were much longer, or we did not trust Google very much, we may be concerned about a malicious actor hijacking the cookie’s opaque payload, and accessing data using the opaque payload.
For reference, nextjs-auth0 implements this using encrypted JWTs by computing an expiration header in abstract-session and encrypting those in their stateless-session. If I wanted to control my own session timeouts, that’s probably what I would do as well, and use the jose library mentioned above.
Next time #
That concludes the first part of this series, discussing the overall design choices being made. In the next part we will explore actually implementing this.