Reference

Public API functions

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 idenity is stored in user cookies homehow 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.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 (str) – requested permission.
• context – additional object may be passed into AbstractAuthorizationPolicy.permission() coroutine.

Returns:

True if registered user has requested permission, False otherwise.

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.

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.