Recently we released a Java API for the akka-http-session library, a set of akka-http directives useful when building HTTP routes which need to handle session data.

Having ported this library to Java, we decided to include a guide containing not only complete working examples of all the various directives, but also explaining the core concepts of session handling.

Session security is addressed as well. Starting with ways to secure a cookie, the guide continues with example HTTP routes, and explains session encryption along with the possible use cases, where it makes sense.

Another section is dedicated to protecting against Cross-Site Request Forgery (CSRF) attacks. Again, this part of the guide not only explains how such an attack is performed, but also provides a working example and a client session showing all the cookies and headers required to be set to be safe.

Finally, we noticed some issues filed against akka-http-session which turned out not to be bugs. This issue mentions that an invalidated session can still be used. Because it’s counter-intuitive at first sight, we tried to make it clear that the invalidation logic is delegated to the client. We tried to address some more of these rather documentation issues within this guide.

As the library itself, this guide is open source. Clone it, import to your IDE and get some of the sample HTTP routes running to get a better understanding of how the akka-http-session library handles sessions.