1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
.. _aiohttp-security-reference:
===========
Reference
===========
.. module:: aiohttp_security
.. currentmodule:: aiohttp_security
.. highlight:: python
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
saving info into session.
The action is performed by registered
:meth:`AbstractIdentityPolicy.remember`.
Usually the *identity* is stored in user cookies somehow for using by
:func:`authorized_userid` and :func:`permits`.
: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.
:param kwargs: additional arguments passed to
:meth:`AbstractIdentityPolicy.remember`.
They are policy-specific and may be used, e.g. for
specifiying cookie lifetime.
.. coroutinefunction:: forget(request, response)
Forget previously remembered :term:`identity`.
The action is performed by registered
:meth:`AbstractIdentityPolicy.forget`.
:param request: :class:`aiohttp.web.Request` object.
:param response: :class:`aiohttp.web.StreamResponse` and
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`.
The user should be registered by :func:`remember` before the call.
:param request: :class:`aiohttp.web.Request` object.
:return: :class:`str` :term:`userid` or ``None`` for session
without signed in user.
.. coroutinefunction:: 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
:class:`AbstractAuthorizationPolicy` implementation.
Actually it's a wrapper around
:meth:`AbstractAuthorizationPolicy.permits` coroutine.
The user should be registered by :func:`remember` before the call.
:param request: :class:`aiohttp.web.Request` object.
:param permission: Requested :term:`permission`. :class:`str` or
:class:`enum.Enum` object.
:param context: additional object may be passed into
:meth:`AbstractAuthorizationPolicy.permission`
coroutine.
:return: ``True`` if registered user has requested *permission*,
``False`` otherwise.
.. coroutinefunction:: is_anonymous(request)
Checks if user is anonymous user.
Return ``True`` if user is not remembered in request, otherwise
returns ``False``.
:param request: :class:`aiohttp.web.Request` object.
Abstract policies
=================
*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.
:param response: :class:`aiohttp.web.StreamResponse` object or
derivative.
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.
|
