Reference¶
Public API functions¶
-
aiohttp_security.
setup
(app, identity_policy, autz_policy)[source]¶ 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.
- app – aiohttp
-
coroutine
aiohttp_security.
remember
(request, response, identity, **kwargs)[source]¶ 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()
andpermits()
.Parameters: - request –
aiohttp.web.Request
object. - response –
aiohttp.web.StreamResponse
and descendants likeaiohttp.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.
- request –
-
coroutine
aiohttp_security.
forget
(request, response)[source]¶ Forget previously remembered identity.
The action is performed by registered
AbstractIdentityPolicy.forget()
.Parameters: - request –
aiohttp.web.Request
object. - response –
aiohttp.web.StreamResponse
and descendants likeaiohttp.web.Response
.
- 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)[source]¶ 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
Retrieve userid.
The user should be registered by
remember()
before the call.Parameters: request – aiohttp.web.Request
object.Returns: str
userid orNone
for session without signed in user.
-
coroutine
aiohttp_security.
permits
(request, permission, context=None)[source]¶ 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
orenum.Enum
object. - context – additional object may be passed into
AbstractAuthorizationPolicy.permission()
coroutine.
Returns: True
if registered user has requested permission,False
otherwise.- request –
-
coroutine
aiohttp_security.
is_anonymous
(request)[source]¶ Checks if user is anonymous user.
Return
True
if user is not remembered in request, otherwise returnsFalse
.Parameters: request – aiohttp.web.Request
object.
Abstract policies¶
- aiohttp_security is built on top of two abstract policies –
AbstractIdentityPolicy
andAbstractAuthorizationPolicy
.
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
[source]¶ -
coroutine
identify
(request)[source]¶ 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)[source]¶ 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.
- request –
-
coroutine
forget
(request, response)[source]¶ 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.
- request –
-
coroutine
Authorization policy¶
-
class
aiohttp_security.
AbstractAuthorizationPolicy
[source]¶