# Reference

## Public API functions

`aiohttp_security.``setup`(app, identity_policy, autz_policy)

  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)

  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()` and `permits()`.

  Parameters:

  - request – `aiohttp.web.Request` object.
  - response – `aiohttp.web.StreamResponse` and descendants like `aiohttp.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)

  Forget previously remembered identity.

  The action is performed by registered `AbstractIdentityPolicy.forget()`.

  Parameters:

  - request – `aiohttp.web.Request` object.
  - response – `aiohttp.web.StreamResponse` and descendants like `aiohttp.web.Response`.

coroutine `aiohttp_security.``check_authorized`(request)

  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)

  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)

  Retrieve userid.

  The user should be registered by `remember()` before the call.

  Parameters: | request – `aiohttp.web.Request` object.
  Returns: | `str` userid or `None` for session without signed in user.

coroutine `aiohttp_security.``permits`(request, permission, context=None)

  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` or `enum.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)

  Checks if user is anonymous user.

  Return `True` if user is not remembered in request, otherwise returns `False`.

  Parameters: | request – `aiohttp.web.Request` object.

`@``aiohttp_security.``login_required`

  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)

  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 –
  `AbstractIdentityPolicy` and `AbstractAuthorizationPolicy`.

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`
  coroutine `identify`(request)

    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)

    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)

    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.

### Authorization policy

class `aiohttp_security.``AbstractAuthorizationPolicy`
  coroutine `authorized_userid`(identity)

    Retrieve authorized user id.

    Abstract method, should be overriden by descendant.

    Parameters: | identity – an identity used for authorization.
    Returns: | the userid of the user identified by the identity or `None` if no user exists related to the identity.

  coroutine `permits`(identity, permission, context=None)

    Check user permissions.

    Abstract method, should be overriden by descendant.

    Parameters:

    - identity – an identity used for authorization.
    - permission – requested permission. The type of parameter is not fixed and depends on implementation.