Reference

Public API functions

aiohttp_security.setup(app, identity_policy, autz_policy)

Setup aiohttp application with security policies.

Parameters:

• app – aiohttp aiohttp.web.Application instance.

• identity_policy – indentification policy, an AbstractIdentityPolicy instance.

• autz_policy – authorization policy, an AbstractAuthorizationPolicy instance.

coroutine aiohttp_security.remember(request, response, identity, **kwargs)

Remember identity in response, e.g. by storing a cookie or saving info into session.

The action is performed by registered AbstractIdentityPolicy.remember().

Usually the identity is stored in user cookies somehow for using by authorized_userid() and permits().

Parameters:

• request – aiohttp.web.Request object.

• response – aiohttp.web.StreamResponse and descendants like aiohttp.web.Response.

• identity (str) – aiohttp.web.Request object.

• kwargs –

  additional arguments passed to AbstractIdentityPolicy.remember().

  They are policy-specific and may be used, e.g. for specifiying cookie lifetime.

coroutine aiohttp_security.forget(request, response)

Forget previously remembered identity.

The action is performed by registered AbstractIdentityPolicy.forget().

Parameters:

• request – aiohttp.web.Request object.

• response – aiohttp.web.StreamResponse and descendants like aiohttp.web.Response.

coroutine aiohttp_security.check_authorized(request)

Checker that doesn’t pass if user is not authorized by request.

Parameters:

request – aiohttp.web.Request object.

Return str:

authorized user ID if success

Raise:

aiohttp.web.HTTPUnauthorized for anonymous users.

Usage:

async def handler(request):
    await check_authorized(request)
    # this line is never executed for anonymous users

coroutine aiohttp_security.check_permission(request, permission)

Checker that doesn’t pass if user has no requested permission.

Parameters:

request – aiohttp.web.Request object.

Raise:

aiohttp.web.HTTPUnauthorized for anonymous users.

Raise:

aiohttp.web.HTTPForbidden if user is authorized but has no access rights.

Usage:

async def handler(request):
    await check_permission(request, 'read')
    # this line is never executed if a user has no read permission

coroutine aiohttp_security.authorized_userid(request)

Retrieve userid.

The user should be registered by remember() before the call.

Parameters:

request – aiohttp.web.Request object.

Returns:

str userid or None for session without signed in user.

coroutine aiohttp_security.permits(request, permission, context=None)

Check user’s permission.

Return True if user remembered in request has specified permission.

Allowed permissions as well as context meaning are depends on AbstractAuthorizationPolicy implementation.

Actually it’s a wrapper around AbstractAuthorizationPolicy.permits() coroutine.

The user should be registered by remember() before the call.

Parameters:

• request – aiohttp.web.Request object.

• permission – Requested permission. str or enum.Enum object.

• context – additional object may be passed into AbstractAuthorizationPolicy.permission() coroutine.

Returns:

True if registered user has requested permission, False otherwise.

coroutine aiohttp_security.is_anonymous(request)

Checks if user is anonymous user.

Return True if user is not remembered in request, otherwise returns False.

Parameters:

request – aiohttp.web.Request object.

@aiohttp_security.login_required

Decorator for handlers that checks if user is authorized.

Raises aiohttp.web.HTTPUnauthorized if user is not authorized.

Deprecated since version 0.3: Use check_authorized() async function.

@aiohttp_security.has_permission(permission)

Decorator for handlers that checks if user is authorized and has correct permission.

Raises aiohttp.web.HTTPUnauthorized if user is not authorized.

Raises aiohttp.web.HTTPForbidden if user is authorized but has no access rights.

Parameters:

permission (str) – requested permission.

Deprecated since version 0.3: Use check_authorized() async function.

Abstract policies

aiohttp_security is built on top of two abstract policies –

AbstractIdentityPolicy and AbstractAuthorizationPolicy.

The first one responds on remembering, retrieving and forgetting identity into some session storage, e.g. HTTP cookie or authorization token.

The second is responsible to return persistent userid for session-wide identity and check user’s permissions.

Most likely sofware developer reuses one of pre-implemented identity policies from aiohttp_security but build authorization policy from scratch for every application/project.

Identification policy

class aiohttp_security.AbstractIdentityPolicy

coroutine identify(request)

Extract identity from request.

Abstract method, should be overriden by descendant.

Parameters:

request – aiohttp.web.Request object.

Returns:

the claimed identity of the user associated request or None if no identity can be found associated with the request.

coroutine remember(request, response, identity, **kwargs)

Remember identity.

May use request for accessing required data and response for storing identity (e.g. updating HTTP response cookies).

kwargs may be used by concrete implementation for passing additional data.

Abstract method, should be overriden by descendant.

Parameters:

• request – aiohttp.web.Request object.

• response – aiohttp.web.StreamResponse object or derivative.

• identity – identity to store.

• kwargs – optional additional arguments. An individual identity policy and its consumers can decide on the composition and meaning of the parameter.

coroutine forget(request, response)

Forget previously stored identity.

May use request for accessing required data and response for dropping identity (e.g. updating HTTP response cookies).

Abstract method, should be overriden by descendant.

Parameters:

• request – aiohttp.web.Request object.

• response – aiohttp.web.StreamResponse object or derivative.

Authorization policy

class aiohttp_security.AbstractAuthorizationPolicy

coroutine authorized_userid(identity)

Retrieve authorized user id.

Abstract method, should be overriden by descendant.

Parameters:

identity – an identity used for authorization.

Returns:

the userid of the user identified by the identity or None if no user exists related to the identity.

coroutine permits(identity, permission, context=None)

Check user permissions.

Abstract method, should be overriden by descendant.

Parameters:

• identity – an identity used for authorization.

• permission – requested permission. The type of parameter is not fixed and depends on implementation.