ActionDispatch Session Storage with Amazon DynamoDB

This gem contains an ActionDispatch AbstractStore implementation that uses Amazon DynamoDB as a session store, allowing access to sessions from other applications and devices.

Installation

Add this gem to your Rails project's Gemfile:

gem 'aws-sdk-rails', '~> 4'
gem 'aws-actiondispatch-dynamodb', '~> 0'

Then run bundle install.

This gem also brings in the following AWS gems:

• aws-sessionstore-dynamodb -> aws-sdk-dynamodb

You will have to ensure that you provide credentials for the SDK to use. See the latest AWS SDK for Ruby Docs for details.

If you're running your Rails application on Amazon EC2, the AWS SDK will check Amazon EC2 instance metadata for credentials to load. Learn more: IAM Roles for Amazon EC2

Usage

To use the session store, add or edit your config/initializers/session_store.rb file:

options = { table_name: '_your_app_session' }
Rails.application.config.session_store :dynamo_db_store, **options

You can now start your Rails application with DynamoDB session support.

Note: You will need a DynamoDB table to store your sessions. You can create the table using the provided Rake tasks or ActiveRecord migration generator after configuring.

Configuration

You can configure the session store with code, ENV, or a YAML file, in this order of precedence. To configure in code, you can directly pass options to your config/initializers/session_store.rb file like so:

options = {
  table_name: 'your-table-name',
  table_key: 'your-session-key',
  dynamo_db_client: Aws::DynamoDB::Client.new(region: 'us-west-2')
} 
Rails.application.config.session_store :dynamo_db_store, **options

The session store inherits from the Rack::Session::Abstract::Persisted class, which also supports additional options (such as :key).

For more information about this feature and configuration options, see the Configuration class and the GitHub repository.

Configuration file generator

You can generate a configuration file for the session store using the following command (--environment= is optional):

rails generate dynamo_db:session_store_config --environment=<Rails.env>

The session store configuration generator command will generate a YAML file config/aws_dynamo_db_session_store.yml with default options. If provided an environment, the file will be named config/aws_dynamo_db_session_store/<Rails.env>.yml, which takes precedence over the default file.

Migration

ActiveRecord Migration generator

You can generate a migration file for the session table using the following command ( is optional):

rails generate dynamo_db:session_store_migration <MigrationName>

The session store migration generator command will generate a migration file db/migration/#{VERSION}_#{MIGRATION_NAME}.rb.

The migration file will create and delete a table with default options. These options can be changed prior to running the migration either by changing the configuration in the initializer, editing the migration file, in ENV, or in the config YAML file. These options are documented in the Table class.

To create the table, run migrations as normal with:

rails db:migrate

To delete the table and rollback, run the following command:

rails db:migrate:down VERSION=<VERSION>

Migration Rake tasks

If you are not using ActiveRecord, you can manage the table using the provided Rake tasks:

rake dynamo_db:session_store:create_table
rake dynamo_db:session_store:delete_table

The rake tasks will create and delete a table with default options. These options can be changed prior to running the task either by changing the configuration in the initializer, in ENV, or in the config YAML file. These options are documented in the Table class.

Cleaning old sessions

By default sessions do not expire. You can use :max_age and :max_stale to configure the max age or stale period of a session.

You can use the DynamoDB Time to Live (TTL) feature on the expire_at attribute to automatically delete expired items, saving you the trouble of manually deleting them and reducing costs.

If you wish to delete old sessions based on creation age (invalidating valid sessions) or if you want control over the garbage collection process, you can use the provided Rake task:

rake dynamo_db:session_store:clean

The rake task will clean the table with default options. These options can be changed prior to running the task either by changing the configuration in the initializer, in ENV, or in the config YAML file. These options are documented in the GarbageCollector class.