From 79e811ea79a886c828c58ec74a11497ec279efd7 Mon Sep 17 00:00:00 2001 From: Skorpeo <10620160+Skorpeo@users.noreply.github.com> Date: Wed, 13 Jun 2018 14:10:13 +0300 Subject: [PATCH] Update usage.rst (#167) --- docs/usage.rst | 79 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 58 insertions(+), 21 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index d37e503..9fe28c5 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -11,39 +11,76 @@ First of all, what is *aiohttp_security* about? -It is a set of public API functions and standard for implementation details. +*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. Public API ========== -API is implementation agnostic, all client code should not call policy -code (see below) directly but use API only. +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 +(iv) check the :term:`permission` of a remembered user (:func:`permits`). + +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. + +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. + + 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). -Via API application can remember/forget user in local session -(:func:`remember`/:func:`forget`), retrieve :term:`userid` -(:func:`authorized_userid`) and check :term:`permission` for -remembered user (:func:`permits`). -The library internals are built on top of two policies: -:term:`authentication` and :term:`authorization`. There are abstract -base classes for both concepts as well as several implementations -shipped with the library. End user is free to build own implemetations -if needed. 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. -Actions related to retrieving, storing and removing user's -:term:`identity`. +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. -Authenticated user has no access rights, the system even has no -knowledge is there the user still registered in DB. + *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. -If :class:`aiohttp.web.Request` has an :term:`identity` it means the user has -some ID that should be checked by :term:`authorization` policy. +Identity Policy +============== -:term:`identity` is a string shared between browser and server. -Thus it's not supposed to be database primary key, user login/email etc. -Random string like uuid or hash is better choice. +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. + +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. +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. + + 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 +.. [#f1] jwt - json web tokens in the works