Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 653 lines (495 sloc) 24.227 kB
c5f24b2 Prep for b1
Chris McDonough authored
1 .. index::
2 single: security
3
07a69ea Tweaks.
Chris McDonough authored
4 .. _security_chapter:
5
1462bc4 Add the beginnings of security docs.
Chris McDonough authored
6 Security
7 ========
8
93d5dbd @caseman reword security intro paragraph
caseman authored
9 :app:`Pyramid` provides an optional declarative authorization system
c90930a @caseman slight clarification
caseman authored
10 that can prevent a :term:`view` from being invoked based on an
93d5dbd @caseman reword security intro paragraph
caseman authored
11 :term:`authorization policy`. Before a view is invoked, the
12 authorization system can use the credentials in the :term:`request`
13 along with the :term:`context` resource to determine if access will be
14 allowed. Here's how it works at a high level:
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
15
82e0452 @caseman our => the
caseman authored
16 - A :term:`request` is generated when a user visits the application.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
17
780999e @mcdonc context finding -> resource location
mcdonc authored
18 - Based on the request, a :term:`context` resource is located through
19 :term:`resource location`. A context is located differently depending on
20 whether the application uses :term:`traversal` or :term:`URL dispatch`, but
21 a context is ultimately found in either case. See
ee50aec @caseman Remove resource location chapter and move intro parts to url dispatch…
caseman authored
22 the :ref:`urldispatch_chapter` chapter for more information.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
23
590fe7c Massive overhaul to deal with the reality that we don't map URLs dire…
Chris McDonough authored
24 - A :term:`view callable` is located by :term:`view lookup` using the
c5f24b2 Prep for b1
Chris McDonough authored
25 context as well as other attributes of the request.
590fe7c Massive overhaul to deal with the reality that we don't map URLs dire…
Chris McDonough authored
26
27 - If an :term:`authentication policy` is in effect, it is passed the
28 request; it returns some number of :term:`principal` identifiers.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
29
30 - If an :term:`authorization policy` is in effect and the :term:`view
31 configuration` associated with the view callable that was found has
32 a :term:`permission` associated with it, the authorization policy is
590fe7c Massive overhaul to deal with the reality that we don't map URLs dire…
Chris McDonough authored
33 passed the :term:`context`, some number of :term:`principal`
34 identifiers returned by the authentication policy, and the
35 :term:`permission` associated with the view; it will allow or deny
36 access.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
37
590fe7c Massive overhaul to deal with the reality that we don't map URLs dire…
Chris McDonough authored
38 - If the authorization policy allows access, the view callable is
39 invoked.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
40
590fe7c Massive overhaul to deal with the reality that we don't map URLs dire…
Chris McDonough authored
41 - If the authorization policy denies access, the view callable is not
42 invoked; instead the :term:`forbidden view` is invoked.
1462bc4 Add the beginnings of security docs.
Chris McDonough authored
43
3dc9116 @caseman XXX explain the authentication/authorization separate in pyramid. Con…
caseman authored
44 Security in :app:`Pyramid`, unlike many systems, cleanly and explicitly
45 separates authentication and authorization. Authentication is merely the
46 mechanism by which credentials provided in the :term:`request` are
47 resolved to one or more :term:`principal` identifiers. These identifiers
48 represent the users and groups in effect during the request.
49 Authorization then determines access based on the :term:`principal`
50 identifiers, the :term:`view callable` being invoked, and the
51 :term:`context` resource.
52
5f44b29 @cguardia The security chapter had a few more typos than the others. Someone ha…
cguardia authored
53 Authorization is enabled by modifying your application to include an
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
54 :term:`authentication policy` and :term:`authorization policy`.
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
55 :app:`Pyramid` comes with a variety of implementations of these
56 policies. To provide maximal flexibility, :app:`Pyramid` also
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
57 allows you to create custom authentication policies and authorization
58 policies.
1462bc4 Add the beginnings of security docs.
Chris McDonough authored
59
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
60 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
61 single: authorization policy
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
62
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored
63 .. _enabling_authorization_policy:
64
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
65 Enabling an Authorization Policy
66 --------------------------------
1462bc4 Add the beginnings of security docs.
Chris McDonough authored
67
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
68 By default, :app:`Pyramid` enables no authorization policy. All
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
69 views are accessible by completely anonymous users. In order to begin
70 protecting views from execution based on security settings, you need
71 to enable an authorization policy.
72
73 Enabling an Authorization Policy Imperatively
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1462bc4 Add the beginnings of security docs.
Chris McDonough authored
75
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
76 Use the :meth:`~pyramid.config.Configurator.set_authorization_policy` method
77 of the :class:`~pyramid.config.Configurator` to enable an authorization
78 policy.
1462bc4 Add the beginnings of security docs.
Chris McDonough authored
79
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
80 You must also enable an :term:`authentication policy` in order to enable the
81 authorization policy. This is because authorization, in general, depends
82 upon authentication. Use the
83 :meth:`~pyramid.config.Configurator.set_authentication_policy` and method
84 during application setup to specify the authentication policy.
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
85
86 For example:
87
0ac7b07 Fix syntax errors found via manuel, and add manuel-style markers to p…
Chris McDonough authored
88 .. ignore-next-block
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
89 .. code-block:: python
90 :linenos:
91
d7f2590 @mcdonc fix docs: pyramid.configuration -> pyramid.config
mcdonc authored
92 from pyramid.config import Configurator
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
93 from pyramid.authentication import AuthTktAuthenticationPolicy
94 from pyramid.authorization import ACLAuthorizationPolicy
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
95 authentication_policy = AuthTktAuthenticationPolicy('seekrit')
96 authorization_policy = ACLAuthorizationPolicy()
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
97 config = Configurator()
98 config.set_authentication_policy(authentication_policy)
99 config.set_authorization_policy(authorization_policy)
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
100
d89aee7 - Each of the follow methods of the Configurator now allow the
Chris McDonough authored
101 .. note:: the ``authentication_policy`` and ``authorization_policy``
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
102 arguments may also be passed to their respective methods mentioned above
103 as :term:`dotted Python name` values, each representing the dotted name
104 path to a suitable implementation global defined at Python module scope.
d89aee7 - Each of the follow methods of the Configurator now allow the
Chris McDonough authored
105
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
106 The above configuration enables a policy which compares the value of an "auth
107 ticket" cookie passed in the request's environment which contains a reference
108 to a single :term:`principal` against the principals present in any
109 :term:`ACL` found in the resource tree when attempting to call some
110 :term:`view`.
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
111
112 While it is possible to mix and match different authentication and
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
113 authorization policies, it is an error to configure a Pyramid application
114 with an authentication policy but without the authorization policy or vice
115 versa. If you do this, you'll receive an error at application startup time.
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
116
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
117 See also the :mod:`pyramid.authorization` and
118 :mod:`pyramid.authentication` modules for alternate implementations
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
119 of authorization and authentication policies.
120
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
121 .. index::
122 single: permissions
123 single: protecting views
124
410457b More reviews finished.
Chris McDonough authored
125 .. _protecting_views:
126
8b8e109 ACL stuff.
Chris McDonough authored
127 Protecting Views with Permissions
128 ---------------------------------
129
780999e @mcdonc context finding -> resource location
mcdonc authored
130 To protect a :term:`view callable` from invocation based on a user's security
131 settings when a particular type of resource becomes the :term:`context`, you
132 must pass a :term:`permission` to :term:`view configuration`. Permissions
133 are usually just strings, and they have no required composition: you can name
134 permissions whatever you like.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
135
c7c40b9 @mcdonc de-zcml-ify various chapters and move ZCML to the declarative chapter
mcdonc authored
136 For example, the following view declaration protects the view named
780999e @mcdonc context finding -> resource location
mcdonc authored
137 ``add_entry.html`` when the context resource is of type ``Blog`` with the
138 ``add`` permission using the :meth:`pyramid.config.Configurator.add_view`
139 API:
d9c735d
Chris McDonough authored
140
c7c40b9 @mcdonc de-zcml-ify various chapters and move ZCML to the declarative chapter
mcdonc authored
141 .. code-block:: python
d9c735d
Chris McDonough authored
142 :linenos:
8b8e109 ACL stuff.
Chris McDonough authored
143
d7f2590 @mcdonc fix docs: pyramid.configuration -> pyramid.config
mcdonc authored
144 # config is an instance of pyramid.config.Configurator
c7c40b9 @mcdonc de-zcml-ify various chapters and move ZCML to the declarative chapter
mcdonc authored
145
146 config.add_view('mypackage.views.blog_entry_add_view',
147 name='add_entry.html',
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
148 context='mypackage.resources.Blog',
c7c40b9 @mcdonc de-zcml-ify various chapters and move ZCML to the declarative chapter
mcdonc authored
149 permission='add')
8b8e109 ACL stuff.
Chris McDonough authored
150
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
151 The equivalent view registration including the ``add`` permission name
197f0cb @mcdonc bfg_view -> view_config
mcdonc authored
152 may be performed via the ``@view_config`` decorator:
1b29574 Expand.
Chris McDonough authored
153
0ac7b07 Fix syntax errors found via manuel, and add manuel-style markers to p…
Chris McDonough authored
154 .. ignore-next-block
1b29574 Expand.
Chris McDonough authored
155 .. code-block:: python
156 :linenos:
157
197f0cb @mcdonc bfg_view -> view_config
mcdonc authored
158 from pyramid.view import view_config
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
159 from resources import Blog
1b29574 Expand.
Chris McDonough authored
160
197f0cb @mcdonc bfg_view -> view_config
mcdonc authored
161 @view_config(context=Blog, name='add_entry.html', permission='add')
6103bf8 Document the request-only calling convention as the default.
Chris McDonough authored
162 def blog_entry_add_view(request):
1b29574 Expand.
Chris McDonough authored
163 """ Add blog entry code goes here """
164 pass
165
c7c40b9 @mcdonc de-zcml-ify various chapters and move ZCML to the declarative chapter
mcdonc authored
166 As a result of any of these various view configuration statements, if an
167 authorization policy is in place when the view callable is found during
168 normal application operations, the requesting user will need to possess the
780999e @mcdonc context finding -> resource location
mcdonc authored
169 ``add`` permission against the :term:`context` resource in order to be able
170 to invoke the ``blog_entry_add_view`` view. If he does not, the
171 :term:`Forbidden view` will be invoked.
8b8e109 ACL stuff.
Chris McDonough authored
172
6ce1e0c @mcdonc add more index markers
mcdonc authored
173 .. index::
174 pair: permission; default
175
e25a70a Features
Chris McDonough authored
176 .. _setting_a_default_permission:
177
178 Setting a Default Permission
179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180
cb0f3c4 @caseman add missing word
caseman authored
181 If a permission is not supplied to a view configuration, the registered
182 view will always be executable by entirely anonymous users: any
e25a70a Features
Chris McDonough authored
183 authorization policy in effect is ignored.
184
185 In support of making it easier to configure applications which are
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
186 "secure by default", :app:`Pyramid` allows you to configure a
e25a70a Features
Chris McDonough authored
187 *default* permission. If supplied, the default permission is used as
188 the permission string to all view registrations which don't otherwise
189 name a ``permission`` argument.
190
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
191 The :meth:`pyramid.config.Configurator.set_default_permission` method
192 supports configuring a default permission for an application.
e25a70a Features
Chris McDonough authored
193
1ad1dbb @mcdonc forward port of bugfix from bfg trunk
mcdonc authored
194 When a default permission is registered:
e25a70a Features
Chris McDonough authored
195
5a3520f @cmbeelby Capitalization fix
cmbeelby authored
196 - If a view configuration names an explicit ``permission``, the default
1ad1dbb @mcdonc forward port of bugfix from bfg trunk
mcdonc authored
197 permission is ignored for that view registration, and the
198 view-configuration-named permission is used.
199
fecefff @mmerickel Added the `pyramid.security.NO_PERMISSION_REQUIRED` constant.
mmerickel authored
200 - If a view configuration names the permission
201 :data:`pyramid.security.NO_PERMISSION_REQUIRED`, the default permission
202 is ignored, and the view is registered *without* a permission (making it
1ad1dbb @mcdonc forward port of bugfix from bfg trunk
mcdonc authored
203 available to all callers regardless of their credentials).
e25a70a Features
Chris McDonough authored
204
2021a00 @mcdonc - Beef up documentation related to ``set_default_permission``: explic…
mcdonc authored
205 .. warning::
206
207 When you register a default permission, *all* views (even :term:`exception
208 view` views) are protected by a permission. For all views which are truly
209 meant to be anonymously accessible, you will need to associate the view's
fecefff @mmerickel Added the `pyramid.security.NO_PERMISSION_REQUIRED` constant.
mmerickel authored
210 configuration with the :data:`pyramid.security.NO_PERMISSION_REQUIRED`
211 permission.
2021a00 @mcdonc - Beef up documentation related to ``set_default_permission``: explic…
mcdonc authored
212
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
213 .. index::
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
214 single: ACL
215 single: access control list
6ce1e0c @mcdonc add more index markers
mcdonc authored
216 pair: resource; ACL
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
217
c1278c8 Add headers.
Chris McDonough authored
218 .. _assigning_acls:
219
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
220 Assigning ACLs to your Resource Objects
221 ---------------------------------------
8b8e109 ACL stuff.
Chris McDonough authored
222
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
223 When the default :app:`Pyramid` :term:`authorization policy` determines
780999e @mcdonc context finding -> resource location
mcdonc authored
224 whether a user possesses a particular permission with respect to a resource,
225 it examines the :term:`ACL` associated with the resource. An ACL is
226 associated with a resource by adding an ``__acl__`` attribute to the resource
227 object. This attribute can be defined on the resource *instance* if you need
228 instance-level security, or it can be defined on the resource *class* if you
229 just need type-level security.
8b8e109 ACL stuff.
Chris McDonough authored
230
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
231 For example, an ACL might be attached to the resource for a blog via its
d9c735d
Chris McDonough authored
232 class:
233
234 .. code-block:: python
235 :linenos:
236
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
237 from pyramid.security import Everyone
238 from pyramid.security import Allow
d9c735d
Chris McDonough authored
239
1b29574 Expand.
Chris McDonough authored
240 class Blog(object):
241 __acl__ = [
242 (Allow, Everyone, 'view'),
243 (Allow, 'group:editors', 'add'),
244 (Allow, 'group:editors', 'edit'),
245 ]
246
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
247 Or, if your resources are persistent, an ACL might be specified via the
248 ``__acl__`` attribute of an *instance* of a resource:
1b29574 Expand.
Chris McDonough authored
249
250 .. code-block:: python
251 :linenos:
252
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
253 from pyramid.security import Everyone
254 from pyramid.security import Allow
1b29574 Expand.
Chris McDonough authored
255
256 class Blog(object):
d9c735d
Chris McDonough authored
257 pass
258
1b29574 Expand.
Chris McDonough authored
259 blog = Blog()
260
261 blog.__acl__ = [
d9c735d
Chris McDonough authored
262 (Allow, Everyone, 'view'),
263 (Allow, 'group:editors', 'add'),
264 (Allow, 'group:editors', 'edit'),
265 ]
8b8e109 ACL stuff.
Chris McDonough authored
266
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
267 Whether an ACL is attached to a resource's class or an instance of the
268 resource itself, the effect is the same. It is useful to decorate individual
269 resource instances with an ACL (as opposed to just decorating their class) in
270 applications such as "CMS" systems where fine-grained access is required on
271 an object-by-object basis.
1b29574 Expand.
Chris McDonough authored
272
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
273 .. index::
274 single: ACE
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
275 single: access control entry
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
276
1b29574 Expand.
Chris McDonough authored
277 Elements of an ACL
278 ------------------
279
280 Here's an example ACL:
281
282 .. code-block:: python
283 :linenos:
284
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
285 from pyramid.security import Everyone
286 from pyramid.security import Allow
1b29574 Expand.
Chris McDonough authored
287
288 __acl__ = [
289 (Allow, Everyone, 'view'),
290 (Allow, 'group:editors', 'add'),
291 (Allow, 'group:editors', 'edit'),
292 ]
293
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
294 The example ACL indicates that the
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
295 :data:`pyramid.security.Everyone` principal -- a special
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
296 system-defined principal indicating, literally, everyone -- is allowed
178623b Tweaks.
Chris McDonough authored
297 to view the blog, the ``group:editors`` principal is allowed to add to
298 and edit the blog.
8b8e109 ACL stuff.
Chris McDonough authored
299
5f44b29 @cguardia The security chapter had a few more typos than the others. Someone ha…
cguardia authored
300 Each element of an ACL is an :term:`ACE` or access control entry.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
301 For example, in the above code block, there are three ACEs: ``(Allow,
302 Everyone, 'view')``, ``(Allow, 'group:editors', 'add')``, and
303 ``(Allow, 'group:editors', 'edit')``.
9c82bce Document sequence-ability of ACE permission list.
Chris McDonough authored
304
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
305 The first element of any ACE is either
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
306 :data:`pyramid.security.Allow`, or
307 :data:`pyramid.security.Deny`, representing the action to take when
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
308 the ACE matches. The second element is a :term:`principal`. The
309 third argument is a permission or sequence of permission names.
9c82bce Document sequence-ability of ACE permission list.
Chris McDonough authored
310
c7c40b9 @mcdonc de-zcml-ify various chapters and move ZCML to the declarative chapter
mcdonc authored
311 A principal is usually a user id, however it also may be a group id if your
312 authentication system provides group information and the effective
313 :term:`authentication policy` policy is written to respect group information.
314 For example, the
315 :class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` respects group
e47c780 @mcdonc remove reference to ZCML directives; doesnt work in printed book
mcdonc authored
316 information if you configure it with a ``callback``.
1b29574 Expand.
Chris McDonough authored
317
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
318 Each ACE in an ACL is processed by an authorization policy *in the
319 order dictated by the ACL*. So if you have an ACL like this:
1b29574 Expand.
Chris McDonough authored
320
321 .. code-block:: python
322 :linenos:
323
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
324 from pyramid.security import Everyone
325 from pyramid.security import Allow
326 from pyramid.security import Deny
1b29574 Expand.
Chris McDonough authored
327
328 __acl__ = [
329 (Allow, Everyone, 'view'),
330 (Deny, Everyone, 'view'),
331 ]
332
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
333 The default authorization policy will *allow* everyone the view
334 permission, even though later in the ACL you have an ACE that denies
335 everyone the view permission. On the other hand, if you have an ACL
336 like this:
1b29574 Expand.
Chris McDonough authored
337
338 .. code-block:: python
339 :linenos:
340
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
341 from pyramid.security import Everyone
342 from pyramid.security import Allow
343 from pyramid.security import Deny
1b29574 Expand.
Chris McDonough authored
344
345 __acl__ = [
346 (Deny, Everyone, 'view'),
347 (Allow, Everyone, 'view'),
348 ]
349
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
350 The authorization policy will deny everyone the view permission, even
1b29574 Expand.
Chris McDonough authored
351 though later in the ACL is an ACE that allows everyone.
352
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
353 The third argument in an ACE can also be a sequence of permission
354 names instead of a single permission name. So instead of creating
355 multiple ACEs representing a number of different permission grants to
356 a single ``group:editors`` group, we can collapse this into a single
357 ACE, as below.
358
359 .. code-block:: python
360 :linenos:
361
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
362 from pyramid.security import Everyone
363 from pyramid.security import Allow
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
364
365 __acl__ = [
366 (Allow, Everyone, 'view'),
367 (Allow, 'group:editors', ('add', 'edit')),
368 ]
369
370
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
371 .. index::
1dff935 Speling.
Chris McDonough authored
372 single: principal
c5f24b2 Prep for b1
Chris McDonough authored
373 single: principal names
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
374
1b29574 Expand.
Chris McDonough authored
375 Special Principal Names
376 -----------------------
377
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
378 Special principal names exist in the :mod:`pyramid.security`
1b29574 Expand.
Chris McDonough authored
379 module. They can be imported for use in your own code to populate
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
380 ACLs, e.g. :data:`pyramid.security.Everyone`.
1b29574 Expand.
Chris McDonough authored
381
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
382 :data:`pyramid.security.Everyone`
1b29574 Expand.
Chris McDonough authored
383
384 Literally, everyone, no matter what. This object is actually a
385 string "under the hood" (``system.Everyone``). Every user "is" the
386 principal named Everyone during every request, even if a security
387 policy is not in use.
388
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
389 :data:`pyramid.security.Authenticated`
1b29574 Expand.
Chris McDonough authored
390
391 Any user with credentials as determined by the current security
392 policy. You might think of it as any user that is "logged in".
393 This object is actually a string "under the hood"
394 (``system.Authenticated``).
395
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
396 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
397 single: permission names
398 single: special permission names
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
399
1b29574 Expand.
Chris McDonough authored
400 Special Permissions
401 -------------------
402
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
403 Special permission names exist in the :mod:`pyramid.security`
1b29574 Expand.
Chris McDonough authored
404 module. These can be imported for use in ACLs.
405
406 .. _all_permissions:
407
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
408 :data:`pyramid.security.ALL_PERMISSIONS`
1b29574 Expand.
Chris McDonough authored
409
410 An object representing, literally, *all* permissions. Useful in an
411 ACL like so: ``(Allow, 'fred', ALL_PERMISSIONS)``. The
727d349 Spellcheck.
Chris McDonough authored
412 ``ALL_PERMISSIONS`` object is actually a stand-in object that has a
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
413 ``__contains__`` method that always returns ``True``, which, for all
a1a9fb7 Merge authchanges branch to trunk.
Chris McDonough authored
414 known authorization policies, has the effect of indicating that a
415 given principal "has" any permission asked for by the system.
1b29574 Expand.
Chris McDonough authored
416
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
417 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
418 single: special ACE
419 single: ACE (special)
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
420
1b29574 Expand.
Chris McDonough authored
421 Special ACEs
422 ------------
423
780999e @mcdonc context finding -> resource location
mcdonc authored
424 A convenience :term:`ACE` is defined representing a deny to everyone of all
425 permissions in :data:`pyramid.security.DENY_ALL`. This ACE is often used as
426 the *last* ACE of an ACL to explicitly cause inheriting authorization
427 policies to "stop looking up the traversal tree" (effectively breaking any
428 inheritance). For example, an ACL which allows *only* ``fred`` the view
429 permission for a particular resource despite what inherited ACLs may say when
430 the default authorization policy is in effect might look like so:
1b29574 Expand.
Chris McDonough authored
431
432 .. code-block:: python
433 :linenos:
434
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
435 from pyramid.security import Allow
436 from pyramid.security import DENY_ALL
1b29574 Expand.
Chris McDonough authored
437
cf58abf Clean up.
Chris McDonough authored
438 __acl__ = [ (Allow, 'fred', 'view'), DENY_ALL ]
6499237 Tweaks.
Chris McDonough authored
439
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
440 "Under the hood", the :data:`pyramid.security.DENY_ALL` ACE equals
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
441 the following:
442
443 .. code-block:: python
16cd50c @blaflamme Normalized narrative doc, code with linenos while text+bash don't
blaflamme authored
444 :linenos:
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
445
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
446 from pyramid.security import ALL_PERMISSIONS
5f44b29 @cguardia The security chapter had a few more typos than the others. Someone ha…
cguardia authored
447 __acl__ = [ (Deny, Everyone, ALL_PERMISSIONS) ]
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
448
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
449 .. index::
450 single: ACL inheritance
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
451 pair: location-aware; security
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
452
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored
453 ACL Inheritance and Location-Awareness
454 --------------------------------------
8b8e109 ACL stuff.
Chris McDonough authored
455
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
456 While the default :term:`authorization policy` is in place, if a resource
457 object does not have an ACL when it is the context, its *parent* is consulted
458 for an ACL. If that object does not have an ACL, *its* parent is consulted
459 for an ACL, ad infinitum, until we've reached the root and there are no more
460 parents left.
226b492 Features
Chris McDonough authored
461
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored
462 In order to allow the security machinery to perform ACL inheritance, resource
463 objects must provide *location-awareness*. Providing *location-awareness*
464 means two things: the root object in the resource tree must have a
9b514e5 @cmbeelby Wrong name for variable
cmbeelby authored
465 ``__name__`` attribute and a ``__parent__`` attribute.
8b8e109 ACL stuff.
Chris McDonough authored
466
85fd25e
Chris McDonough authored
467 .. code-block:: python
cbdc369 Features
Chris McDonough authored
468 :linenos:
469
470 class Blog(object):
471 __name__ = ''
472 __parent__ = None
473
474 An object with a ``__parent__`` attribute and a ``__name__`` attribute
475 is said to be *location-aware*. Location-aware objects define an
476 ``__parent__`` attribute which points at their parent object. The
477 root object's ``__parent__`` is ``None``.
8b8e109 ACL stuff.
Chris McDonough authored
478
cbdc369 Features
Chris McDonough authored
479 See :ref:`location_module` for documentations of functions which use
27b8759 Remove incorrect info from security chapter.
Chris McDonough authored
480 location-awareness. See also :ref:`location_aware`.
cbdc369 Features
Chris McDonough authored
481
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
482 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
483 single: forbidden view
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
484
7bc20e1 General editing walkthrough.
Chris McDonough authored
485 Changing the Forbidden View
486 ---------------------------
487
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
488 When :app:`Pyramid` denies a view invocation due to an
7bc20e1 General editing walkthrough.
Chris McDonough authored
489 authorization denial, the special ``forbidden`` view is invoked. "Out
490 of the box", this forbidden view is very plain. See
491 :ref:`changing_the_forbidden_view` within :ref:`hooks_chapter` for
492 instructions on how to create a custom forbidden view and arrange for
493 it to be called when view authorization is denied.
494
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
495 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
496 single: debugging authorization failures
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
497
47b4d3e Docs
Chris McDonough authored
498 .. _debug_authorization_section:
2f1209a Info about debugging security failures.
Chris McDonough authored
499
17ce574 Features
Chris McDonough authored
500 Debugging View Authorization Failures
501 -------------------------------------
2f1209a Info about debugging security failures.
Chris McDonough authored
502
17ce574 Features
Chris McDonough authored
503 If your application in your judgment is allowing or denying view
504 access inappropriately, start your application under a shell using the
7b9066c @jahmad BFG_ -> PYRAMID_
jahmad authored
505 ``PYRAMID_DEBUG_AUTHORIZATION`` environment variable set to ``1``. For
23bfce0 @blaflamme Narrative doc cleanup
blaflamme authored
506 example:
507
508 .. code-block:: text
47b4d3e Docs
Chris McDonough authored
509
cfb2b55 @mcdonc remove all reference to the paster command-line utility
mcdonc authored
510 $ PYRAMID_DEBUG_AUTHORIZATION=1 bin/pserve myproject.ini
2f1209a Info about debugging security failures.
Chris McDonough authored
511
17ce574 Features
Chris McDonough authored
512 When any authorization takes place during a top-level view rendering,
513 a message will be logged to the console (to stderr) about what ACE in
514 which ACL permitted or denied the authorization based on
515 authentication information.
47b4d3e Docs
Chris McDonough authored
516
517 This behavior can also be turned on in the application ``.ini`` file
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
518 by setting the ``pyramid.debug_authorization`` key to ``true`` within the
23bfce0 @blaflamme Narrative doc cleanup
blaflamme authored
519 application's configuration section, e.g.:
520
16cd50c @blaflamme Normalized narrative doc, code with linenos while text+bash don't
blaflamme authored
521 .. code-block:: ini
522 :linenos:
47b4d3e Docs
Chris McDonough authored
523
524 [app:main]
3d338ea @mcdonc - Use [app:main] instead of a pipeline in all scaffolds and tutorials
mcdonc authored
525 use = egg:MyProject
875ded3 @mmerickel Updated all of the docs to reflect the new pyramid.* settings prefix.
mmerickel authored
526 pyramid.debug_authorization = true
2f1209a Info about debugging security failures.
Chris McDonough authored
527
17ce574 Features
Chris McDonough authored
528 With this debug flag turned on, the response sent to the browser will
529 also contain security debugging information in its body.
530
531 Debugging Imperative Authorization Failures
532 -------------------------------------------
533
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
534 The :func:`pyramid.security.has_permission` API is used to check
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
535 security within view functions imperatively. It returns instances of
536 objects that are effectively booleans. But these objects are not raw
537 ``True`` or ``False`` objects, and have information attached to them
538 about why the permission was allowed or denied. The object will be
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
539 one of :data:`pyramid.security.ACLAllowed`,
540 :data:`pyramid.security.ACLDenied`,
541 :data:`pyramid.security.Allowed`, or
542 :data:`pyramid.security.Denied`, as documented in
5f44b29 @cguardia The security chapter had a few more typos than the others. Someone ha…
cguardia authored
543 :ref:`security_module`. At the very minimum these objects will have a
544 ``msg`` attribute, which is a string indicating why the permission was
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
545 denied or allowed. Introspecting this information in the debugger or
546 via print statements when a call to
70acd25 @mcdonc module name contractions
mcdonc authored
547 :func:`~pyramid.security.has_permission` fails is often useful.
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
548
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
549 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
550 single: authentication policy (creating)
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
551
cf58abf Clean up.
Chris McDonough authored
552 .. _creating_an_authentication_policy:
553
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
554 Creating Your Own Authentication Policy
555 ---------------------------------------
556
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
557 :app:`Pyramid` ships with a number of useful out-of-the-box
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
558 security policies (see :mod:`pyramid.authentication`). However,
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
559 creating your own authentication policy is often necessary when you
560 want to control the "horizontal and vertical" of how your users
5f44b29 @cguardia The security chapter had a few more typos than the others. Someone ha…
cguardia authored
561 authenticate. Doing so is a matter of creating an instance of something
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
562 that implements the following interface:
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
563
564 .. code-block:: python
16cd50c @blaflamme Normalized narrative doc, code with linenos while text+bash don't
blaflamme authored
565 :linenos:
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
566
546ae05 @ejo Adding 'I' to example custom AuthenticationPolicy; it's an interface.
ejo authored
567 class IAuthenticationPolicy(object):
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
568 """ An object representing a Pyramid authentication policy. """
80b4af9 @mcdonc Fix authentication policy example.
mcdonc authored
569
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
570 def authenticated_userid(self, request):
571 """ Return the authenticated userid or ``None`` if no
80b4af9 @mcdonc Fix authentication policy example.
mcdonc authored
572 authenticated userid can be found. This method of the policy
573 should ensure that a record exists in whatever persistent store is
574 used related to the user (the user should not have been deleted);
575 if a record associated with the current id does not exist in a
576 persistent store, it should return ``None``."""
577
578 def unauthenticated_userid(self, request):
579 """ Return the *unauthenticated* userid. This method performs the
580 same duty as ``authenticated_userid`` but is permitted to return the
581 userid based only on data present in the request; it needn't (and
582 shouldn't) check any persistent store to ensure that the user record
583 related to the request userid exists."""
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
584
585 def effective_principals(self, request):
586 """ Return a sequence representing the effective principals
587 including the userid and any groups belonged to by the current
57cc868 @mcdonc - Slightly improved interface docs for ``IAuthorizationPolicy``.
mcdonc authored
588 user, including 'system' groups such as
589 ``pyramid.security.Everyone`` and
590 ``pyramid.security.Authenticated``. """
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
591
592 def remember(self, request, principal, **kw):
593 """ Return a set of headers suitable for 'remembering' the
594 principal named ``principal`` when set in a response. An
595 individual authentication policy and its consumers can decide
596 on the composition and meaning of **kw. """
597
598 def forget(self, request):
599 """ Return a set of headers suitable for 'forgetting' the
600 current user on subsequent requests. """
601
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
602 After you do so, you can pass an instance of such a class into the
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
603 :class:`~pyramid.config.Configurator.set_authentication_policy` method
604 configuration time to use it.
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
605
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
606 .. index::
c5f24b2 Prep for b1
Chris McDonough authored
607 single: authorization policy (creating)
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored
608
cf58abf Clean up.
Chris McDonough authored
609 .. _creating_an_authorization_policy:
610
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
611 Creating Your Own Authorization Policy
612 --------------------------------------
613
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
614 An authorization policy is a policy that allows or denies access after a user
615 has been authenticated. Most :app:`Pyramid` applications will use the
616 default :class:`pyramid.authorization.ACLAuthorizationPolicy`.
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
617
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
618 However, in some cases, it's useful to be able to use a different
5f44b29 @cguardia The security chapter had a few more typos than the others. Someone ha…
cguardia authored
619 authorization policy than the default
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
620 :class:`~pyramid.authorization.ACLAuthorizationPolicy`. For example, it
621 might be desirable to construct an alternate authorization policy which
622 allows the application to use an authorization mechanism that does not
623 involve :term:`ACL` objects.
cf58abf Clean up.
Chris McDonough authored
624
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored
625 :app:`Pyramid` ships with only a single default authorization
125e974 Adjust for 7.5x9.25in output.
Chris McDonough authored
626 policy, so you'll need to create your own if you'd like to use a
627 different one. Creating and using your own authorization policy is a
628 matter of creating an instance of an object that implements the
629 following interface:
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
630
631 .. code-block:: python
16cd50c @blaflamme Normalized narrative doc, code with linenos while text+bash don't
blaflamme authored
632 :linenos:
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
633
634 class IAuthorizationPolicy(object):
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored
635 """ An object representing a Pyramid authorization policy. """
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
636 def permits(self, context, principals, permission):
57cc868 @mcdonc - Slightly improved interface docs for ``IAuthorizationPolicy``.
mcdonc authored
637 """ Return ``True`` if any of the ``principals`` is allowed the
638 ``permission`` in the current ``context``, else return ``False``
639 """
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
640
641 def principals_allowed_by_permission(self, context, permission):
57cc868 @mcdonc - Slightly improved interface docs for ``IAuthorizationPolicy``.
mcdonc authored
642 """ Return a set of principal identifiers allowed by the
643 ``permission`` in ``context``. This behavior is optional; if you
644 choose to not implement it you should define this method as
645 something which raises a ``NotImplementedError``. This method
646 will only be called when the
647 ``pyramid.security.principals_allowed_by_permission`` API is
648 used."""
643bd09 - Add interface docs related to how to create authentication policies
Chris McDonough authored
649
7c411c4 Roles and imperative documentation for security policy config.
Chris McDonough authored
650 After you do so, you can pass an instance of such a class into the
3bee9e9 @mcdonc fixes #398 .. mention only method-based authN configuration, remove i…
mcdonc authored
651 :class:`~pyramid.config.Configurator.set_authorization_policy` method at
652 configuration time to use it.
Something went wrong with that request. Please try again.