Aiohttp Security 0 5 0

aiohttp-security 0.5.0

Overview

aiohttp_security provides identity and authorization for aiohttp.web applications. Part of the aio-libs project, it separates concerns into two abstract policies:

• Identity Policy — handles remembering, identifying, and forgetting a user's identity (authentication persistence via cookies, sessions, or JWT).
• Authorization Policy — maps identities to user IDs and checks permissions (developer-implemented per application).

Ships with three built-in identity policies (CookiesIdentityPolicy, SessionIdentityPolicy, JWTIdentityPolicy) and expects developers to implement their own authorization policy.

When to Use

• Building aiohttp.web applications requiring user authentication and route-level authorization
• Implementing login/logout flows with session or cookie-based identity persistence
• Protecting endpoints with permission-based access control
• Integrating JWT bearer token authentication into aiohttp applications
• Building custom authorization logic backed by databases, LDAP, or other user stores

Core Concepts

Identity

A session-wide string identifying the user between browser and server. Use random strings (UUIDs, hashes) rather than database IDs, usernames, or emails. Stored client-side (cookie) or server-side (session storage).

Userid

The user's persistent identifier — typically their login name or email. Retrieved from the identity via the authorization policy's authorized_userid() method.

Permission

A string (or enum) representing an access right required to reach a resource. Developers define whatever permission names make sense (e.g., "read", "write", "admin").

Authentication vs Authorization

• Authentication confirms who the user is (identity verification). Developer implements; library requires it results in an identity string.
• Authorization checks what the authenticated user is allowed to do (permission checking via authorization policy).

Installation / Setup

pip install aiohttp-security          # basic cookie support
pip install aiohttp-security[session] # with aiohttp-session support
pip install PyJWT                     # for JWT identity policy

Requires aiohttp>=3.9, Python 3.9+. Optional: aiohttp-session, PyJWT.

Usage Examples

Basic Setup with Session Identity

Most common pattern uses SessionIdentityPolicy with a custom authorization policy:

from aiohttp import web
from aiohttp_session import SimpleCookieStorage, session_middleware
from aiohttp_security import check_permission, is_anonymous, remember, forget, setup as setup_security, SessionIdentityPolicy
from aiohttp_security.abc import AbstractAuthorizationPolicy


class MyAuthorizationPolicy(AbstractAuthorizationPolicy):
    async def authorized_userid(self, identity):
        """Return user_id for the given identity, or None if unknown."""
        pass

    async def permits(self, identity, permission, context=None):
        """Return True if identity has the permission, else False."""
        return False


async def make_app():
    middleware = session_middleware(SimpleCookieStorage())
    app = web.Application(middlewares=[middleware])
    app.add_routes([
        web.get('/', handler_root),
        web.get('/login', handler_login),
        web.get('/logout', handler_logout),
        web.get('/protected', handler_protected),
    ])
    setup_security(app, SessionIdentityPolicy(), MyAuthorizationPolicy())
    return app

Warning: Never use SimpleCookieStorage in production. Use EncryptedCookieStorage or RedisStorage.

Login Handler

async def handler_login(request):
    data = await request.post()
    username, password = data.get('username'), data.get('password')
    if not await verify_credentials(username, password):
        return web.Response(text="Invalid credentials", status=401)
    redirect_response = web.HTTPFound('/')
    await remember(request, redirect_response, username)
    raise redirect_response

Logout Handler

async def handler_logout(request):
    redirect_response = web.HTTPFound('/')
    await forget(request, redirect_response)
    raise redirect_response

Protecting Routes with Permissions

async def handler_protected(request):
    await check_permission(request, 'admin')
    return web.Response(text="You have admin access!")

check_permission() raises HTTPUnauthorized if anonymous, HTTPForbidden if lacking the permission.

Checking Authentication Without Permissions

from aiohttp_security import check_authorized

async def handler_account(request):
    userid = await check_authorized(request)
    return web.Response(text=f"Welcome, {userid}!")

Checking Anonymous Status

async def handler_root(request):
    is_logged = not await is_anonymous(request)
    return web.Response(text=f"You are {'logged in' if is_logged else 'anonymous'}")

Getting the Current User ID

from aiohttp_security import authorized_userid

async def handler_profile(request):
    userid = await authorized_userid(request)
    if userid is None:
        return web.Response(text="Not logged in", status=401)
    return web.Response(text=f"User ID: {userid}")

Direct Permission Checking

from aiohttp_security import permits

async def handler_dashboard(request):
    can_edit = await permits(request, 'edit')
    can_delete = await permits(request, 'delete')
    return web.json_response({"can_edit": can_edit, "can_delete": can_delete})

Advanced Topics

API Reference: Public API functions, abstract policies, built-in identity policies → API Reference

Advanced Patterns: Database-backed authorization, enum permissions, complete app setup, password verification, identity best practices → Advanced Patterns