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.
- 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.
- 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
.
- coroutine aiohttp_security.check_authorized(request)[source]¶
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
- coroutine aiohttp_security.authorized_userid(request)[source]¶
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.
- 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.
- @aiohttp_security.login_required[source]¶
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)[source]¶
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 –
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.
- 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.