.. _aiohttp-security-usage:


=======
 Usage
=======

.. currentmodule:: aiohttp_security
.. highlight:: python


First of all, what is *aiohttp_security* about?

It is a set of public API functions and standard for implementation details.


Public API
==========

API is implementation agnostic, all client code should not call policy
code (see below) directly but use API only.

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
==============

Actions related to retrieving, storing and removing user's
:term:`identity`.

Authenticated user has no access rights, the system even has no
knowledge is there the user still registered in DB.

If :class:`aiohttp.web.Request` has an :term:`identity` it means the user has
some ID that should be checked by :term:`authorization` 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.