Documentation

You are viewing the documentation for the 2.6.x release series. The latest stable release series is 3.0.x.

§Configuring the session cookie

Play stores the session using a session cookie in the browser. When you are programming, you will typically access the session through the Scala API or Java API, but there are useful configuration settings.

Session and flash cookies are stored in JSON Web Token (JWT) format. The encoding is transparent to Play, but there some useful properties of JWT which can be leveraged for session cookies, and can be configured through application.conf. Note that JWT is typically used in an HTTP header value, which is not what is active here – in addition, the JWT is signed using the secret, but is not encrypted by Play.

§Not Before Support

When a session cookie is created, the “issued at” iat and “not before” nbf claims in JWT will be set to the time of cookie creation, which prevents a cookie from being accepted before the current time.

§Session Timeout / Expiration

By default, there is no technical timeout for the Session. It expires when the user closes the web browser. If you need a functional timeout for a specific application, you set the maximum age of the session cookie by configuring the key play.http.session.maxAge in application.conf, and this will also set play.http.session.jwt.expiresAfter to the same value. The maxAge property will remove the cookie from the browser, and the JWT exp claim will be set in the cookie, and will make it invalid after the given duration.

The session cookie uses the JWT cookie encoding. If you want, you can revert back to URL encoded cookie encoding by switching to play.api.mvc.LegacyCookiesModule in the application.conf file:

play.modules.disabled+="play.api.mvc.CookiesModule"
play.modules.enabled+="play.api.mvc.LegacyCookiesModule"

§Session Configuration

The default session configuration is as follows:

# Session configuration
session = {

  # The cookie name
  cookieName = "PLAY_SESSION"

  # Whether the secure attribute of the cookie should be set to true
  secure = false

  # The max age to set on the cookie.
  # If null, the cookie expires when the user closes their browser.
  # An important thing to note, this only sets when the browser will discard the cookie.
  maxAge = null

  # Whether the HTTP only attribute of the cookie should be set to true
  httpOnly = true

  # The value of the SameSite attribute of the cookie. Set to null for no SameSite attribute.
  sameSite = "lax"

  # The domain to set on the session cookie
  # If null, does not set a domain on the session cookie.
  domain = null

  # The session path
  # Must start with /.
  path = ${play.http.context}

  jwt {
    # The JWT signature algorithm to use on the session cookie
    # uses 'alg' https://tools.ietf.org/html/rfc7515#section-4.1.1
    signatureAlgorithm = "HS256"

    # The time after which the session is automatically invalidated.
    # Use 'exp' https://tools.ietf.org/html/rfc7519#section-4.1.4
    expiresAfter = ${play.http.session.maxAge}

    # The amount of clock skew to accept between servers when performing date checks
    # If you have NTP or roughtime synchronizing between servers, you can enhance
    # security by tightening this value.
    clockSkew = 5 minutes

    # The claim key under which all user data is stored in the JWT.
    dataClaim = "data"
  }
}

Next: Configuring the JDBC connection pool

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.