Web & mobile client-side akka-http sessions, with optional JWT support
akka-httpis an Akka module, originating from spray.io, for building reactive REST services with an elegant DSL.
akka-httpis a great toolkit for building backends for single-page or mobile applications. In almost all apps there is a need to maintain user sessions, make sure session data is secure and cannot be tampered with.
akka-http-sessionprovides directives for client-side session management in web and mobile applications, using cookies or custom headers + local storage, with optional Json Web Tokens format support.
A comprehensive FAQ is available, along with code examples (in Java, but easy to translate to Scala) which answers many common questions on how sessions work, how to secure them and implement using akka-http.
Session data typically contains at least the
idor
usernameof the logged in user. This id must be secured so that a session cannot be "stolen" or forged easily.
Sessions can be stored on the server, either in-memory or in a database, with the session
idsent to the client, or entirely on the client in a serialized format. The former approach requires sticky sessions or additional shared storage, while using the latter (which is supported by this library) sessions can be easily deserialized on any server.
A session is a string token which is sent to the client and should be sent back to the server on every request.
To prevent forging, serialized session data is signed using a server secret. The signature is appended to the session data that is sent to the client, and verified when the session token is received back.
akka-http-sessionfeatures
You can try out a simple example by running
com.softwaremill.example.ScalaExampleor
com.softwaremill.example.JavaExampleand opening http://localhost:8080.
SessionManager& configuration
All directives require an (implicit for scala) instance of a
SessionManager[T](or
SessionManager), which can be created by providing a server secret (via a
SessionConfig). The secret should be a long, random string unique to each environment your app is running in. You can generate one with
SessionUtil.randomServerSecret(). Note that when you change the secret, all sessions will become invalid.
A
SessionConfiginstance can be created using Typesafe config. The only value that you need to provide is
akka.http.session.server-secret, preferably via
application.conf(then you can safely call
SessionConfig.fromConfig) or by using
SessionConfig.default().
You can customize any of the default config options either by modifying them through
application.confor by modifying the
SessionConfigcase class. If a value has type
Option[], you can set it to
Noneby using a
nonevalue in the config file (for both java and scala).
When using cookies, by default the
secureattribute of cookies is not set (for development), however it is recommended that all sites use
httpsand all cookies have this attribute set.
All session-related directives take at least two parameters:
oneOffvs
refreshable; specifies what should happen when the session expires. If
refreshableand a refresh token is present, the session will be re-created. See below for details.
usingCookiesvs
usingHeaders
Typically, you would create aliases for the session-related directives which use the right parameters basing on the current request and logic specific to your application.
Session data can be sent to the client using cookies or custom headers. The first approach is the simplest to use, as cookies are automatically sent to the server on each request.
However, cookies have some security vulnerabilities, and are typically not used in mobile applications. For these scenarios, session data can be transported using custom headers (the names of the headers are configurable in the config).
When using headers, you need to store the session (and, if used, refresh-) tokens yourself. These tokens can be stored in-memory, or persistently e.g. using the browser's local storage.
You can dynamically decide which transport to use, basing e.g. on the user-agent or other request properties.
Sessions are typed. The
Ttype parameter in
SessionManager[T](or
SessionManager) determines what data is stored in the session. Basic types like
String,
Int,
Long,
Float,
Doubleand
Map[String, String](
Map) are supported out-of-the box. Support for other types can be added by providing a (an implicit for scala)
SessionSerializer[T, String](
SessionSerializer). For case classes, it's most convenient to use a
MultiValueSessionSerializer[T]or (
MultiValueSessionSerializer) which should convert the instance into a
String -> Stringmap (nested types are not supported on purpose, as session data should be small & simple). Examples of
SessionSerializerand
MultiValueSessionSerializerusage can be found here for scala and here for java.
Here are code samples in scala and java illustrating how to create a session manager where the session content will be a single
Longnumber.
The basic directives enable you to set, read and invalidate the session. To create a new client-side session (create and set a new session cookie), you need to use the
setSessiondirective. See how it's done in java and scala.
Note that when using cookies, their size is limited to 4KB, so you shouldn't put too much data in there (the signature takes about 50 characters).
You can require a session to be present, optionally require a session or get a full description of possible session decode outcomes. Check java and scala examples for details.
If a required session is not present, by default a
403HTTP status code is returned. Finally, a session can be invalidated. See how it's done in examples for java and scala.
It is possible to encrypt the session data by modifying the
akka.http.session.encrypt-dataconfig option. When sessions are encrypted, it's not possible to read their content on the client side.
The key used for encrypting will be calculated basing on the server secret.
By default, sessions expire after a week. This can be disabled or changed with the
akka.http.session.max-ageconfig option.
Note that when using cookies, even though the cookie sent will be a session cookie, it is possible that the client will have the browser open for a very long time, uses Chrome or FF, or if an attacker steals the cookie, it can be re-used. Hence having an expiry date for sessions is highly recommended.
By default, sessions are encoded into a string using a custom format, where expiry/data/signature parts are separated using
-, and data fields are separated using
=and url-encoded.
You can also encode sessions in the Json Web Tokens format, by adding the additional
jwtdependency, which makes use of
json4s.
When using JWT, you need to provide a serializer which serializes session data to a
JValueinstead of a
String. A number of serializers for the basic types are present in
JValueSessionSerializer, as well as a generic serializer for case classes (used above).
You may also find it helpful to include the json4s-ext library which provides serializers for common Java types such as
java.util.UUID,
org.joda.time._and Java enumerations.
Grab some java and scala examples.
There are many tools available to read JWT session data using various platforms, e.g. for Angular.
It is also possible to customize the session data content generated by overriding appropriate methods in
JwtSessionEncoder(e.g. provide additional claims in the payload).
This library supports all registered claims mentioned in RFC 7519, Section 4.1.
Static claims such as
iss(Issuer),
sub(Subject) and
aud(Audience) can be configured by setting
akka.http.session.jwt.iss,
akka.http.session.jwt.suband
akka.http.session.jwt.audstring properties, respectively.
Because claims such as
exp(Expiration Time) and
nbf(Not Before) depend on the time at which the JWT was issued, configuration expects durations instead of fixed timestamps. Effective claim values are then calculated by adding these offsets to the current timestamp (the JWT's issue time). The offset values are configured via keys defined under
akka.http.session.jwt.exp-timeoutand
akka.http.session.jwt.nbf-offset.
If
exp-timeoutis not defined, value of
akka.http.session.max-agewould be used instead.
iat(Issued At) claim represents issue time and cannot be customized. Although you can decide to include this claim in your tokens or not by setting
akka.http.session.jwt.include-iatto
trueor
false. By default, this claim is not included.
jti(JWT ID) claim is a case-sensitive string containing a unique identifier for the JWT. It must be unique per token and collisions must be prevented even among values produced by different issuers. Akka-http-session will compute and include
jticlaim if
akka.http.session.jwt.include-jtiis set to
true(it's disabled by default). Token ids are generated using the below scheme:
-or just , depending on the
issclaim presence.
You can find a sample claims configuration below: ````hocon akka.http.session { jwt { iss = "Issuer" sub = "Subject" aud = "Audience" exp-timeout = 7 days nbf-offset = 5 minutes include-iat = true include-jti = true } }
## Signing session using a configurable algorithmIn the case of JWT, it's possible to configure which JWS algorithm should be used. Currently, supported ones are:
HS256
- HMAC using SHA-256 (used by default)RS256
- RSA (RSASSA-PKCS1-v1_5) using SHA-256All non-JWT sessions use HMAC with SHA-256 and this cannot be configured.
In order to start using RSA algorithm you have to configure akka.http.session.jws.alg
and akka.http.session.jws.rsa-private-key
properties:
````hocon akka.http.session { jws { alg = "RS256" rsa-private-key = "" } }
Because
HS256is used by default you may skip the
jwsconfiguration and rely on a reference configuration delivered with the library. Alternatively, if you prefer to be more explicit, you might follow this configuration template:
hocon akka.http.session { server-secret = "" jws { alg = "HS256" } }
You might notice that even if you want to sign your sessions using RSA key and encryption is disabled, you still have to define the server-secret property.
That's because all non-JWT sessions still depend on HMAC with SHA256 algorithm which requires the server secret and the library cannot determine which session encoder(s) will be used (it's specified in the client's code).
CSRF is a kind of an attack where an attacker issues a
GETor
POSTrequest on behalf of a user, if the user e.g. clicks on a specially constructed link. See the OWASP page or the Play! docs for a thorough introduction.
Web apps which use cookies for session management should be protected against CSRF attacks. This implementation:
GETrequests are non-mutating (have no side effects)
GETrequest that doesn't have the token cookie set
Note that if the token is passed in a form field, the website isn't protected by HTTPS or you don't control all subdomains, this scheme can be broken. Currently, setting a custom header seems to be a secure solution, and is what a number of projects do (that's why, when using custom headers to send session data, no additional protection is needed).
It is recommended to generate a new CSRF token after logging in, see this SO question. A new token can be generated using the
setNewCsrfTokendirective.
By default the name of the CSRF cookie and the custom header matches what AngularJS expects and sets. These can be customized in the config.
If you'd like to implement persistent, "remember-me" sessions, you should use
refreshableinstead of
oneOffsessions. This is especially useful in mobile applications, where you log in once, and the session is remembered for a long time. Make sure to adjust the
akka.http.session.refresh-token.max-ageconfig option appropriately (defaults to 1 month)!
You can dynamically decide, basing on the request properties (e.g. a query parameter), if a session should be refreshable or not. Just pass the right parameter to
setSession.
When using refreshable sessions, in addition to an (implicit)
SessionManagerinstance, you need to provide an implementation of the
RefreshTokenStoragetrait. This trait has methods to lookup, store and delete refresh tokens. Typically it would use some persistent storage.
The tokens are never stored directly, instead only token hashes are passed to the storage. That way even if the token database is leaked, it won't be possible to forge sessions using the hashes. Moreover, in addition to the token hash, a selector value is stored. That value is used to lookup stored hashes; tokens are compared using a special constant-time comparison method, to prevent timing attacks.
When a session expires or is not present, but the refresh token is (sent from the client using either a cookie, or a custom header), a new session will be created (using the
RefreshTokenLookupResult.createSessionfunction), and a new refresh token will be created.
Note that you can differentiate between sessions created from refresh tokens and from regular authentication by storing appropriate information in the session data. That way, you can force the user to re-authenticate if the session was created by a refresh token before crucial operations.
It is of course possible to read
oneOff-session using
requiredSession(refreshable, ...). If a session was created as
oneOff, using
refreshablehas no additional effect.
The semantics of
touch[Required|Optional]Session()are a bit subtle. You can still use expiring client sessions when using refresh tokens. You will then have 2 stages of expiration: expiration of the client session (should be shorter), and expiry of the refresh token. That way you can have strongly-authenticated sessions which expire fast, and weaker-authenticated re-creatable sessions (as described in the paragraph above).
When touching an existing session, the refresh token will not be re-generated and extended, only the session cookie.
akka-httpand
akka-http-session
For
akka-httpversion
10+:
libraryDependencies += "com.softwaremill.akka-http-session" %% "core" % "0.6.1" libraryDependencies += "com.softwaremill.akka-http-session" %% "jwt" % "0.6.1" // optional
Certain releases changed the client token encoding/serialization. In those cases, it's important to enable the appropriate token migrations, otherwise existing client sessions will be invalid (and your users will be logged out).
When updating from a version before 0.5.3, set
akka.http.session.token-migration.v0-5-3.enabled = true.
When updating from a version before 0.5.2, set
akka.http.session.token-migration.v0-5-2.enabled = true.
Note that when updating through multiple releases, be sure to enable all the appropriate migrations.
For versions prior to 0.5.0, no migration path is provided. However, you can implement your own encoders/serializers to support migrating from whatever version you are using.
Since token changes may be security related, migrations should be enabled for the shortest period of time after which the vast majority of client tokens have been migrated.
We offer commercial support for akka-http-session and related technologies, as well as development services. Contact us to learn more about our offer!
Copyright (C) 2016-2021 SoftwareMill https://softwaremill.com.