aiohttp-security

0.5.0 verified Fri May 01 auth: no python maintenance

A library for security-related functionality in aiohttp.web applications, including session-based and JWT identity policies, authorization, and permission checks. Current version is 0.5.0, released in February 2023. Release cadence is low, with the last release over two years ago.

pip install aiohttp-security

Common errors

error ImportError: cannot import name 'login_required' from 'aiohttp_security' ↓

cause login_required decorator was deprecated and removed in a later version (0.3.0+).

fix

Use check_authorized function: from aiohttp_security import check_authorized

error TypeError: object str can't be used in 'await' expression ↓

cause Forgot to await check_authorized or other async function.

fix

Add await: identity = await check_authorized(request)

error aiohttp_security.exceptions.AuthorizationFailed: Authorization failed ↓

cause User does not have required permission or is not authorized.

fix

Check that user is logged in and has the required permission when using check_permission.

error AttributeError: 'Application' object has no attribute 'on_response_prepare' ↓

cause Using incompatible version of aiohttp (maybe <3.0) or missing setup steps.

fix

Ensure you are using aiohttp >=3.2 and call aiohttp_session.setup before aiohttp_security.setup.

Warnings

deprecated The decorators login_required and has_permission are deprecated since 0.3.0. Use check_authorized and check_permission functions instead. ↓

fix Replace @login_required with await check_authorized(request) inside handler.

gotcha In version 0.5.0, JWTIdentityPolicy identity now returns str (not dict). Previously it returned a dict, which may break code expecting dict. ↓

fix Update code to handle identity as a string (e.g., username). Use JWTIdentityPolicy with custom payload processing if dict needed.

gotcha aiohttp-session is optional but required for SessionIdentityPolicy. Missing it causes ImportError. ↓

fix Install aiohttp-session: pip install aiohttp-session

breaking Since 0.5.0, aiohttp.web.AppKey is used for internal storage. Older versions used plain strings; code directly accessing app internals may break. ↓

fix Use public API functions; do not access app['aiohttp_security'] directly.

Imports

authorized_userid

wrong

from aiohttp_security.api import authorized_userid

correct

from aiohttp_security import authorized_userid

authorized_userid is exported at package level, not from api submodule

check_authorized
wrong
```
from aiohttp_security.decorators import check_authorized
```
correct
```
from aiohttp_security import check_authorized
```
check_authorized is exported at package level; decorators module exists but old alias

Quickstart

Initialize aiohttp-security with session identity policy and protect a route with check_authorized.

import aiohttp
from aiohttp import web
from aiohttp_security import setup, SimpleIdentityPolicy, check_authorized, check_permission
from aiohttp_security import SessionIdentityPolicy
import aiohttp_session
from aiohttp_session import SimpleCookieStorage

async def handler(request):
    identity = await check_authorized(request)
    return web.json_response({"user": identity})

app = web.Application()
aiohttp_session.setup(app, SimpleCookieStorage())
# Example: using SessionIdentityPolicy
policy = SessionIdentityPolicy()
setup(app, policy)
app.router.add_get('/protected', handler)
web.run_app(app)