python/aiohttp-security
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update to 0.3.0

Browse Source
This commit is contained in:
Andrew Svetlov
2018-09-06 13:06:55 +03:00
parent 097f7ecc43
commit 9b1d08c661
23 changed files with 418 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/example.rst
View File

@@ -9,7 +9,7 @@ Simple example::
from aiohttp import web
from aiohttp_session import SimpleCookieStorage, session_middleware
from aiohttp_security import has_permission, \
from aiohttp_security import check_permission, \
is_anonymous, remember, forget, \
setup as setup_security, SessionIdentityPolicy
from aiohttp_security.abc import AbstractAuthorizationPolicy
@@ -63,13 +63,13 @@ Simple example::
raise redirect_response
@has_permission('listen')
async def handler_listen(request):
await check_permission(request, 'listen')
return web.Response(body="I can listen!")
@has_permission('speak')
async def handler_speak(request):
await check_permission(request, 'speak')
return web.Response(body="I can speak!")
@@ -85,11 +85,12 @@ Simple example::
app = web.Application(middlewares=[middleware])
# add the routes
app.router.add_route('GET', '/', handler_root)
app.router.add_route('GET', '/login', handler_login_jack)
app.router.add_route('GET', '/logout', handler_logout)
app.router.add_route('GET', '/listen', handler_listen)
app.router.add_route('GET', '/speak', handler_speak)
app.add_routes([
web.get('/', handler_root),
web.get('/login', handler_login_jack),
web.get('/logout', handler_logout),
web.get('/listen', handler_listen),
web.get('/speak', handler_speak)])
# set up policies
policy = SessionIdentityPolicy()

10
docs/example_db_auth.rst
View File

@@ -133,7 +133,7 @@ Once we have all the code in place we can install it for our application::
password='aiohttp_security',
database='aiohttp_security',
host='127.0.0.1')
app = web.Application(loop=loop)
app = web.Application()
setup_session(app, RedisStorage(redis_pool))
setup_security(app,
SessionIdentityPolicy(),
@@ -142,23 +142,23 @@ Once we have all the code in place we can install it for our application::
Now we have authorization and can decorate every other view with access rights
based on permissions. There are already implemented two decorators::
based on permissions. There are already implemented two helpers::
from aiohttp_security import has_permission, login_required
from aiohttp_security import check_authorized, check_permission
For each view you need to protect - just apply the decorator on it::
class Web:
@has_permission('protected')
async def protected_page(self, request):
await check_permission(request, 'protected')
response = web.Response(body=b'You are on protected page')
return response
or::
class Web:
@login_required
async def logout(self, request):
await check_authorized(request)
response = web.Response(body=b'You have been logged out')
await forget(request, response)
return response

1
docs/index.rst
View File

@@ -3,6 +3,7 @@ aiohttp_security
The library provides security for :ref:`aiohttp.web<aiohttp-web>`.
The current version is |version|
Contents
--------

78
docs/reference.rst
View File

@@ -13,6 +13,19 @@
Public API functions
====================
.. 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.
.. coroutinefunction:: remember(request, response, identity, **kwargs)
Remember *identity* in *response*, e.g. by storing a cookie or
@@ -50,6 +63,41 @@ Public API functions
descendants like :class:`aiohttp.web.Response`.
.. 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
.. coroutinefunction:: authorized_userid(request)
Retrieve :term:`userid`.
@@ -78,7 +126,8 @@ Public API functions
:param request: :class:`aiohttp.web.Request` object.
:param permission: Requested :term:`permission`. :class:`str` or :class:`enum.Enum` object.
:param permission: Requested :term:`permission`. :class:`str` or
:class:`enum.Enum` object.
:param context: additional object may be passed into
:meth:`AbstractAuthorizationPolicy.permission`
@@ -92,7 +141,8 @@ Public API functions
Checks if user is anonymous user.
Return ``True`` if user is not remembered in request, otherwise returns ``False``.
Return ``True`` if user is not remembered in request, otherwise
returns ``False``.
:param request: :class:`aiohttp.web.Request` object.
@@ -103,29 +153,27 @@ Public API functions
Raises :class:`aiohttp.web.HTTPUnauthorized` if user is not authorized.
.. 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.
Raises :class:`aiohttp.web.HTTPUnauthorized` if user is not authorized.
Raises :class:`aiohttp.web.HTTPForbidden` if user is authorized but has no access rights.
Raises :class:`aiohttp.web.HTTPUnauthorized` if user is not
authorized.
Raises :class:`aiohttp.web.HTTPForbidden` if user is
authorized but has no access rights.
:param str permission: requested :term:`permission`.
.. deprecated:: 0.3
.. 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.
Use :func:`check_authorized` async function.
Abstract policies

110
docs/usage.rst
View File

@@ -11,22 +11,30 @@
First of all, what is *aiohttp_security* about?
*aiohttp_security* is a set of public API functions as well as a reference standard for implementation details for securing access to assets served by a wsgi server.
Assets are secured using authentication and authorization as explained below. *aiohttp_security* is part of the *aio_libs* project which takes advantage of asynchronous
processing using Python's asyncio library.
*aiohttp-security* is a set of public API functions as well as a
reference standard for implementation details for securing access to
assets served by a wsgi server.
Assets are secured using authentication and authorization as explained
below. *aiohttp-security* is part of the
`aio-libs <https://github.com/aio-libs>`_ project which takes advantage
of asynchronous processing using Python's asyncio library.
Public API
==========
The API is agnostic to the low level implementation details such that all client code only needs to implement the endpoints as provided by the API (instead of calling policy
code directly (see explanation below)).
The API is agnostic to the low level implementation details such that
all client code only needs to implement the endpoints as provided by
the API (instead of calling policy code directly (see explanation
below)).
Via the API an application can:
(i) remember a user in a local session (:func:`remember`),
(ii) forget a user in a local session (:func:`forget`),
(iii) retrieve the :term:`userid` (:func:`authorized_userid`) of a remembered user from an :term:`identity` (discussed below), and
(iii) retrieve the :term:`userid` (:func:`authorized_userid`) of a
remembered user from an :term:`identity` (discussed below), and
(iv) check the :term:`permission` of a remembered user (:func:`permits`).
The library internals are built on top of two concepts:
@@ -34,52 +42,100 @@ The library internals are built on top of two concepts:
1) :term:`authentication`, and
2) :term:`authorization`.
There are abstract base classes for both types as well as several pre-built implementations
that are shipped with the library. However, the end user is free to build their own implementations.
The library comes with two pre-built identity policies; one that uses cookies, and one that uses sessions [#f1]_.
It is envisioned that in most use cases developers will use one of the provided identity policies (Cookie or Session) and
implement their own authorization policy.
There are abstract base classes for both types as well as several
pre-built implementations that are shipped with the library. However,
the end user is free to build their own implementations.
The library comes with two pre-built identity policies; one that uses
cookies, and one that uses sessions [#f1]_. It is envisioned that in
most use cases developers will use one of the provided identity
policies (Cookie or Session) and implement their own authorization
policy.
The workflow is as follows:
1) User is authenticated. This has to be implemented by the developer.
2) Once user is authenticated an identity string has to be created for that user. This has to be implemented by the developer.
3) The identity string is passed to the Identity Policy's remember method and the user is now remembered (Cookie or Session if using built-in). *Only once a user is remembered can the other API methods:* :func:`permits`, :func:`forget`, *and* :func:`authorized_userid` *be invoked* .
4) If the user tries to access a restricted asset the :func:`permits` method is called. Usually assets are protected using the **@aiohttp_security.has_permission(**\ *permission*\ **)** decorator. This should return True if permission is granted.
2) Once user is authenticated an identity string has to be created for
that user. This has to be implemented by the developer.
3) The identity string is passed to the Identity Policy's remember
method and the user is now remembered (Cookie or Session if using
built-in). *Only once a user is remembered can the other API
methods:* :func:`permits`, :func:`forget`, *and*
:func:`authorized_userid` *be invoked* .
4) If the user tries to access a restricted asset the :func:`permits`
method is called. Usually assets are protected using the
:func:`check_permission` helper. This should return True if
permission is granted.
The :func:`permits` method is implemented by the developer as part of the :class:`AbstractAuthorizationPolicy` and passed to the application at runtime via setup.
In addition a :func:`@aiohttp_security.login_required decorator` also exists that requires no permissions (i.e. doesn't call :func:`permits` method) but only requires that the user is remembered (i.e. authenticated/logged in).
The :func:`permits` method is implemented by the developer as part of
the :class:`AbstractAuthorizationPolicy` and passed to the
application at runtime via setup.
In addition a :func:`check_authorized` also
exists that requires no permissions (i.e. doesn't call :func:`permits`
method) but only requires that the user is remembered
(i.e. authenticated/logged in).
Authentication
==============
Authentication is the process where a user's identity is verified. It confirms who the user is. This is traditionally done using a user name and password (note: this is not the only way).
A authenticated user has no access rights, rather an authenticated user merely confirms that the user exists and that the user is who they say they are.
In *aiohttp_security* the developer is responsible for their own authentication mechanism. *aiohttp_security* only requires that the authentication result in a identity string which
corresponds to a user's id in the underlying system.
Authentication is the process where a user's identity is verified. It
confirms who the user is. This is traditionally done using a user name
and password (note: this is not the only way).
*Note:* :term:`identity` is a string that is shared between the browser and the server. Therefore it is recommended that a random string such as a uuid or hash is used rather than things like a database primary key, user login/email, etc.
A authenticated user has no access rights, rather an authenticated
user merely confirms that the user exists and that the user is who
they say they are.
In *aiohttp_security* the developer is responsible for their own
authentication mechanism. *aiohttp_security* only requires that the
authentication result in a identity string which corresponds to a
user's id in the underlying system.
.. note::
:term:`identity` is a string that is shared between the browser and
the server. Therefore it is recommended that a random string
such as a uuid or hash is used rather than things like a
database primary key, user login/email, etc.
Identity Policy
==============
===============
Once a user is authenticated the *aiohttp_security* API is invoked for storing, retrieving, and removing a user's :term:`identity`. This is accommplished via AbstractIdentityPolicy's :func:`remember`, :func:`identify`, and :func:`forget` methods. The Identity Policy is therefore the mechanism by which a authenticated user is persisted in the system.
Once a user is authenticated the *aiohttp_security* API is invoked for
storing, retrieving, and removing a user's :term:`identity`. This is
accommplished via AbstractIdentityPolicy's :func:`remember`,
:func:`identify`, and :func:`forget` methods. The Identity Policy is
therefore the mechanism by which a authenticated user is persisted in
the system.
*aiohttp_security* has two built in identity policy's for this purpose. :term:`CookiesIdentityPolicy` that uses cookies and :term:`SessionIdentityPolicy` that uses sessions via :term:`aiohttp.session` library.
*aiohttp_security* has two built in identity policy's for this
purpose. :class:`CookiesIdentityPolicy` that uses cookies and
:class:`SessionIdentityPolicy` that uses sessions via
``aiohttp-session`` library.
Authorization
==============
Once a user is authenticated (see above) it means that the user has an :term:`identity`. This :term:`identity` can now be used for checking access rights or :term:`permission` using a :term:`authorization` policy.
Once a user is authenticated (see above) it means that the user has an
:term:`identity`. This :term:`identity` can now be used for checking
access rights or :term:`permission` using a :term:`authorization`
policy.
The authorization policy's :func:`permits()` method is used for this purpose.
When :class:`aiohttp.web.Request` has an :term:`identity` it means the user has been authenticated and therefore has an :term:`identity` that can be checked by the :term:`authorization` policy.
When :class:`aiohttp.web.Request` has an :term:`identity` it means the
user has been authenticated and therefore has an :term:`identity` that
can be checked by the :term:`authorization` policy.
As noted above, :term:`identity` is a string that is shared between the browser and the server. Therefore it is recommended that a random string such as a uuid or hash is used rather than things like a database primary key, user login/email, etc.
As noted above, :term:`identity` is a string that is shared between
the browser and the server. Therefore it is recommended that a
random string such as a uuid or hash is used rather than things like
a database primary key, user login/email, etc.
.. rubric:: Footnotes