aiohttp-session

Common errors

• RuntimeError: Cannot install aiohttp_session[aioredis] without aioredis library

  cause Prior to v2.12.0, the `aioredis` extra explicitly required the `aioredis` package. Post v2.12.0, it shifted to `redis`.
  fix If on `aiohttp-session < 2.12.0`, ensure `pip install aioredis`. If on `aiohttp-session >= 2.12.0`, ensure `pip install redis` or `pip install aiohttp-session[aioredis]`.

• cryptography.fernet.InvalidToken: Message too short

  cause This error often indicates that the `EncryptedCookieStorage` received a cookie it couldn't decrypt. Common causes include a corrupted session cookie, or the application's encryption key changing between server restarts.
  fix Verify that the Fernet encryption key used by `EncryptedCookieStorage` is consistent across all application instances and restarts. Ensure that `Fernet.generate_key()` is not called repeatedly in production. Users with invalid cookies will simply receive a new session.

• TypeError: session_middleware() got an unexpected keyword argument 'storage'

  cause The `session_middleware` function is typically called as `session_middleware(storage_instance)` and then passed to `app.middlewares`. If `setup(app, storage_instance)` is used, you generally don't interact with `session_middleware` directly.
  fix Use `setup(app, storage_instance)` to configure the session middleware, or pass `session_middleware(storage_instance)` directly to the `middlewares` list when creating `web.Application`.

• KeyError: 'AIOHTTP_SESSION' (or other cookie name) or session data not persisting between requests.

  cause This usually means the session middleware is not correctly registered or the `aiohttp.web.Application` instance receiving requests is not the one configured with the session middleware.
  fix Ensure `aiohttp_session.setup(app, storage)` is called on the `web.Application` instance that handles your routes, or that `session_middleware(storage)` is properly included in the `middlewares` list of `web.Application`.

Warnings

• breaking Support for Python 3.7 was dropped in `aiohttp-session` v2.12.1. Applications running on Python 3.7 will need to upgrade their Python version.
  Fix: Upgrade your Python environment to 3.8 or higher.
• breaking Starting with `aiohttp-session` v2.12.0, `RedisStorage` migrated its core dependency from `aioredis` to `redis`. If you were manually installing `aioredis` for Redis sessions without using the `[aioredis]` extra, you must now install `redis` instead.
  Fix: If using RedisStorage, ensure `pip install redis` or `pip install aiohttp-session[aioredis]` is used. The `[aioredis]` extra will now install `redis`.
• gotcha Using `SimpleCookieStorage` directly is insecure as it stores session data in plain JSON. It is strictly recommended for testing or development purposes only.
  Fix: For production environments, always use `EncryptedCookieStorage` or a server-side storage like `RedisStorage` or `MemcachedStorage`.
• gotcha To prevent session fixation attacks, always call `new_session()` in login views to generate a fresh session identity for authenticated users.
  Fix: Replace `await get_session(request)` with `await new_session(request)` in code paths where a user's authentication status changes (e.g., after login).
• gotcha The `EncryptedCookieStorage` requires a strong 32-byte secret key (or a `Fernet` object) for encryption. Generating a new key on every application restart will invalidate all existing sessions, logging out users.
  Fix: Generate a `Fernet.generate_key()` once and persist it securely (e.g., in an environment variable or a secret management service) across application restarts. Pass this consistent key to `EncryptedCookieStorage`.

Install

• pip install aiohttp-session Core library
• pip install aiohttp-session[secure] For EncryptedCookieStorage
• pip install aiohttp-session[aioredis] For RedisStorage (installs 'redis' since v2.12.0)

Imports

• get_session

  from aiohttp_session import get_session

• setup

  from aiohttp_session import setup

• EncryptedCookieStorage

  from aiohttp_session.cookie_storage import EncryptedCookieStorage

• RedisStorage

  from aiohttp_session.redis_storage import RedisStorage

• Fernet

  from cryptography.fernet import Fernet

Quickstart

This quickstart demonstrates setting up a basic aiohttp.web application with session management using EncryptedCookieStorage. It initializes a Fernet key (generating one if not provided via environment variable, highlighting the need for persistence in production), registers the session middleware with `setup()`, and uses `get_session()` within a handler to store and retrieve user visit times. Run the server, then access `http://localhost:8080` in your browser to see session data persist.

import asyncio
import os
from cryptography import fernet
from aiohttp import web
from aiohttp_session import get_session, setup
from aiohttp_session.cookie_storage import EncryptedCookieStorage

async def handler(request):
    session = await get_session(request)
    last_visit = session.get('last_visit', 'Never')
    session['last_visit'] = str(request.app['current_time'])
    text = f"Last visited: {last_visit}\nHello, current time is {session['last_visit']}"
    return web.Response(text=text)

async def make_app():
    app = web.Application()
    
    # Generate a Fernet key. In production, this should be stored securely
    # and loaded from environment variables or a secret management system.
    # Using a dummy key for demonstration purposes.
    fernet_key_str = os.environ.get('AIOHTTP_SESSION_KEY', None)
    if fernet_key_str is None:
        # WARNING: DO NOT generate a new key on every app startup in production!
        # A new key invalidates all existing sessions. Load from a persistent source.
        fernet_key = fernet.Fernet.generate_key()
        print(f"Generated new Fernet key (for demo only): {fernet_key.decode()}\nSet AIOHTTP_SESSION_KEY env var in production.")
    else:
        fernet_key = fernet_key_str.encode()

    f = fernet.Fernet(fernet_key)
    setup(app, EncryptedCookieStorage(f))
    app['current_time'] = 'Not set yet'
    app.router.add_get('/', handler)
    return app

async def main():
    app = await make_app()
    runner = web.AppRunner(app)
    await runner.setup()
    site = web.TCPSite(runner, 'localhost', 8080)
    await site.start()
    print("Server started at http://localhost:8080")
    try:
        while True:
            app['current_time'] = asyncio.get_event_loop().time()
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        pass
    finally:
        await runner.cleanup()

if __name__ == '__main__':
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Server stopped.")