Session configuration

[]

Session secret

The property sessionSecret is used to encrypt HTTP sessions. Requirements:

It must contain a random string.
A minimum length requirement is 32 characters, but it depends on the implementation (see next sections).

The value needs to be provided via the environment variable SESSION_SECRET which will have a precedence over the default configuration. If no session secret is provided, the application fails to start!

Session storage

Default storage

Without any further session configuration, session data is stored directly in the session cookie, in an encrypted form. This is limited by the maximum size of the cookie, which is approximately 4kB. Details can be found in the <code>iron-session</code> library documentation.

Adding an external session storage

An external session storage can be configured by a "sessionStore" property, which must contain a sufficient configuration for one of the supported storages: DynamoDB or Redis. Mandatory is the type property; other properties are storage-specific. The <code>express-session</code> library supports a large number of session storages, but only two are actually available by default. Any other must be added by installing the appropriate npm package and then adding the code to the Server.ts and Types.ts files.

DynamoDB as a session storage

In DynamoDB, sessions will be stored in one table, each with a hash key: id. This table needs to be created by you manually, since automatic creation is not supported. The application needs to have correct permissions to access this table.

Example of a simple configuration:

JSON

{
   "sessionStore": {
      "type": "dynamodb",
      "table": "sessions-dev"
   }
}

Hosting DynamoDB on AWS

Configuration for AWS hosting is stored in the "aws" property that adhers to the standard ConfigurationOptions from the aws-sdk library.

In addition to the CONFIGvariable, all the standard AWS-related environmental variables (like AWS_REGION) can be used when starting the container. Please refer to the third-party documentation.

When not specified, the region is set to the default eu-central-1. The example above - without any details - will use the eu-central-1 region, and permissions will be granted by the applicable ECS or EC2 policy.

More complex configurations are supported, e.g., for an application running outside the default AWS region, like in the example below. This storage will require a secret key and an access key for the authorized access.

JSON

{
   "sessionStore": {
      "type": "dynamodb",
      "table": "sessions-dev",
      "aws": {
         "region": "eu-west-1",
         "accessKeyId": "...",
         "secretAccessKey": "..."
      }
   }
}

Redis as a session storage

Note that Redis support has not been extensively tested.

Redis configuration requires two properties:

"url": a valid Redis server URL to connect to.
"prefix": a prefix for the keys. Used to avoid clash of different applications in the same Redis server.

An example configuration:

JSON

{
   "sessionStore": {
      "type": "redis",
      "url": "redis://redis1/",
      "prefix": "sess:"
   }
}