aiohttp-security/docs/reference.rst

281 lines
8.0 KiB
ReStructuredText
Raw Permalink Normal View History

2015-07-08 17:30:24 +00:00
.. _aiohttp-security-reference:
===========
Reference
===========
.. module:: aiohttp_security
.. currentmodule:: aiohttp_security
.. highlight:: python
2015-09-06 05:12:18 +00:00
Public API functions
====================
2018-09-06 10:06:55 +00:00
.. function:: setup(app, identity_policy, autz_policy)
Setup :mod:`aiohttp` application with security policies.
:param app: aiohttp :class:`aiohttp.web.Application` instance.
:param identity_policy: indentification policy, an
:class:`AbstractIdentityPolicy` instance.
:param autz_policy: authorization policy, an
:class:`AbstractAuthorizationPolicy` instance.
2015-11-06 14:45:20 +00:00
.. coroutinefunction:: remember(request, response, identity, **kwargs)
2015-09-06 05:12:18 +00:00
2015-11-02 20:28:10 +00:00
Remember *identity* in *response*, e.g. by storing a cookie or
saving info into session.
2015-09-06 05:12:18 +00:00
2015-10-29 08:31:24 +00:00
The action is performed by registered
2015-11-06 14:45:20 +00:00
:meth:`AbstractIdentityPolicy.remember`.
2015-10-29 08:31:24 +00:00
2018-02-01 08:50:58 +00:00
Usually the *identity* is stored in user cookies somehow for using by
2015-11-06 14:45:20 +00:00
:func:`authorized_userid` and :func:`permits`.
2015-10-29 08:31:24 +00:00
:param request: :class:`aiohttp.web.Request` object.
:param response: :class:`aiohttp.web.StreamResponse` and
descendants like :class:`aiohttp.web.Response`.
:param str identity: :class:`aiohttp.web.Request` object.
2015-09-06 05:12:18 +00:00
2015-11-06 14:45:20 +00:00
:param kwargs: additional arguments passed to
:meth:`AbstractIdentityPolicy.remember`.
2015-11-02 20:28:10 +00:00
2015-11-06 14:45:20 +00:00
They are policy-specific and may be used, e.g. for
specifiying cookie lifetime.
2015-11-02 20:28:10 +00:00
2015-11-06 14:45:20 +00:00
.. coroutinefunction:: forget(request, response)
2015-11-02 20:28:10 +00:00
Forget previously remembered :term:`identity`.
The action is performed by registered
2015-11-06 14:45:20 +00:00
:meth:`AbstractIdentityPolicy.forget`.
2015-11-02 20:28:10 +00:00
:param request: :class:`aiohttp.web.Request` object.
:param response: :class:`aiohttp.web.StreamResponse` and
descendants like :class:`aiohttp.web.Response`.
2018-09-06 10:06:55 +00:00
.. coroutinefunction:: check_authorized(request)
Checker that doesn't pass if user is not authorized by *request*.
:param request: :class:`aiohttp.web.Request` object.
:return str: authorized user ID if success
:raise: :class:`aiohttp.web.HTTPUnauthorized` for anonymous users.
Usage::
async def handler(request):
await check_authorized(request)
# this line is never executed for anonymous users
.. coroutinefunction:: check_permission(request, permission)
Checker that doesn't pass if user has no requested permission.
:param request: :class:`aiohttp.web.Request` object.
:raise: :class:`aiohttp.web.HTTPUnauthorized` for anonymous users.
:raise: :class:`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
2015-11-06 14:45:20 +00:00
.. coroutinefunction:: authorized_userid(request)
2015-11-02 20:28:10 +00:00
Retrieve :term:`userid`.
2015-11-06 14:45:20 +00:00
The user should be registered by :func:`remember` before the call.
2015-11-02 20:28:10 +00:00
:param request: :class:`aiohttp.web.Request` object.
2015-11-05 20:59:21 +00:00
:return: :class:`str` :term:`userid` or ``None`` for session
without signed in user.
2015-11-02 20:28:10 +00:00
2015-11-06 14:45:20 +00:00
.. coroutinefunction:: permits(request, permission, context=None)
2015-11-02 20:28:10 +00:00
2015-11-05 20:59:21 +00:00
Check user's permission.
Return ``True`` if user remembered in *request* has specified *permission*.
Allowed permissions as well as *context* meaning are depends on
:class:`AbstractAuthorizationPolicy` implementation.
Actually it's a wrapper around
:meth:`AbstractAuthorizationPolicy.permits` coroutine.
2015-11-06 14:45:20 +00:00
The user should be registered by :func:`remember` before the call.
2015-11-05 20:59:21 +00:00
2015-11-02 20:28:10 +00:00
:param request: :class:`aiohttp.web.Request` object.
2018-09-06 10:06:55 +00:00
:param permission: Requested :term:`permission`. :class:`str` or
:class:`enum.Enum` object.
2015-11-05 20:59:21 +00:00
:param context: additional object may be passed into
:meth:`AbstractAuthorizationPolicy.permission`
coroutine.
2015-11-02 20:28:10 +00:00
:return: ``True`` if registered user has requested *permission*,
``False`` otherwise.
.. coroutinefunction:: is_anonymous(request)
Checks if user is anonymous user.
2018-09-06 10:06:55 +00:00
Return ``True`` if user is not remembered in request, otherwise
returns ``False``.
:param request: :class:`aiohttp.web.Request` object.
.. decorator:: login_required
Decorator for handlers that checks if user is authorized.
Raises :class:`aiohttp.web.HTTPUnauthorized` if user is not authorized.
2018-09-06 10:06:55 +00:00
.. deprecated:: 0.3
Use :func:`check_authorized` async function.
.. decorator:: has_permission(permission)
Decorator for handlers that checks if user is authorized
and has correct permission.
2018-09-06 10:06:55 +00:00
Raises :class:`aiohttp.web.HTTPUnauthorized` if user is not
authorized.
2015-09-06 05:12:18 +00:00
2018-09-06 10:06:55 +00:00
Raises :class:`aiohttp.web.HTTPForbidden` if user is
authorized but has no access rights.
2015-09-06 05:12:18 +00:00
2018-09-06 10:06:55 +00:00
:param str permission: requested :term:`permission`.
2015-10-29 08:31:24 +00:00
2018-09-06 10:06:55 +00:00
.. deprecated:: 0.3
2015-10-29 08:31:24 +00:00
2018-09-06 10:06:55 +00:00
Use :func:`check_authorized` async function.
2015-10-29 08:31:24 +00:00
2015-09-06 05:12:18 +00:00
Abstract policies
=================
2015-07-08 17:30:24 +00:00
2015-11-05 20:59:21 +00:00
*aiohttp_security* is built on top of two *abstract policies* --
:class:`AbstractIdentityPolicy` and
:class:`AbstractAuthorizationPolicy`.
The first one responds on remembering, retrieving and forgetting
:term:`identity` into some session storage, e.g. HTTP cookie or
authorization token.
The second is responsible to return persistent :term:`userid` for
session-wide :term:`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:: AbstractIdentityPolicy
.. coroutinemethod:: identify(request)
Extract :term:`identity` from *request*.
Abstract method, should be overriden by descendant.
:param request: :class:`aiohttp.web.Request` object.
:return: the claimed identity of the user associated request or
``None`` if no identity can be found associated with
the request.
.. coroutinemethod:: 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.
:param request: :class:`aiohttp.web.Request` object.
:param response: :class:`aiohttp.web.StreamResponse` object or
derivative.
:param identity: :term:`identity` to store.
:param kwargs: optional additional arguments. An individual
identity policy and its consumers can decide on
the composition and meaning of the parameter.
.. coroutinemethod:: forget(request, response)
Forget previously stored :term:`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.
:param request: :class:`aiohttp.web.Request` object.
2015-07-08 17:30:24 +00:00
2015-11-05 20:59:21 +00:00
:param response: :class:`aiohttp.web.StreamResponse` object or
derivative.
2015-11-06 14:45:20 +00:00
Authorization policy
---------------------
.. class:: AbstractAuthorizationPolicy
.. coroutinemethod:: authorized_userid(identity)
Retrieve authorized user id.
Abstract method, should be overriden by descendant.
:param identity: an :term:`identity` used for authorization.
:return: the :term:`userid` of the user identified by the
*identity* or ``None`` if no user exists related to the
identity.
.. coroutinemethod:: permits(identity, permission, context=None)
Check user permissions.
Abstract method, should be overriden by descendant.
:param identity: an :term:`identity` used for authorization.
:param permission: requested permission. The type of parameter
is not fixed and depends on implementation.