diff options
Diffstat (limited to 'docs/narr/security.rst')
| -rw-r--r-- | docs/narr/security.rst | 211 |
1 files changed, 28 insertions, 183 deletions
diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 63d1cad25..f9fee59dd 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -59,9 +59,6 @@ views are accessible by completely anonymous users. In order to begin protecting views from execution based on security settings, you need to enable an authorization policy. -You can enable an authorization policy imperatively, or declaratively -via ZCML. - Enabling an Authorization Policy Imperatively ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -110,46 +107,8 @@ See also the :mod:`pyramid.authorization` and :mod:`pyramid.authentication` modules for alternate implementations of authorization and authentication policies. -Enabling an Authorization Policy Via ZCML -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you'd rather use :term:`ZCML` to specify an authorization policy -than imperative configuration, modify the ZCML file loaded by your -application (usually named ``configure.zcml``) to enable an -authorization policy. - -For example, to enable a policy which compares the value of an "auth -ticket" cookie passed in the request's environment which contains a -reference to a single :term:`principal` against the principals present -in any :term:`ACL` found in model data when attempting to call some -:term:`view`, modify your ``configure.zcml`` to look something like -this: - -.. code-block:: xml - :linenos: - - <configure xmlns="http://pylonshq.com/pyramid"> - - <!-- views and other directives before this... --> - - <authtktauthenticationpolicy - secret="iamsosecret"/> - - <aclauthorizationpolicy/> - - </configure> - -"Under the hood", these statements cause an instance of the class -:class:`pyramid.authentication.AuthTktAuthenticationPolicy` to be -injected as the :term:`authentication policy` used by this application -and an instance of the class -:class:`pyramid.authorization.ACLAuthorizationPolicy` to be -injected as the :term:`authorization policy` used by this application. - -:mod:`pyramid` ships with a number of authorization and -authentication policy ZCML directives that should prove useful. See -:ref:`authentication_policies_directives_section` and -:ref:`authorization_policies_directives_section` for more information. +You can also enable a security policy declaratively via ZCML. See +:ref:`zcml_authorization_policy`. .. index:: single: permissions @@ -166,19 +125,19 @@ security settings in a :term:`context`, you must pass a usually just strings, and they have no required composition: you can name permissions whatever you like. -For example, the following declaration protects the view named -``add_entry.html`` when invoked against a ``Blog`` context with the -``add`` permission: +For example, the following view declaration protects the view named +``add_entry.html`` when invoked against a ``Blog`` context with the ``add`` +permission using the :meth:`pyramid.configuration.Configurator.add_view` API: -.. code-block:: xml +.. code-block:: python :linenos: - <view - context=".models.Blog" - view=".views.blog_entry_add_view" - name="add_entry.html" - permission="add" - /> + # config is an instance of pyramid.configuration.Configurator + + config.add_view('mypackage.views.blog_entry_add_view', + name='add_entry.html', + context='mypackage.models.Blog', + permission='add') The equivalent view registration including the ``add`` permission name may be performed via the ``@view_config`` decorator: @@ -195,22 +154,15 @@ may be performed via the ``@view_config`` decorator: """ Add blog entry code goes here """ pass -Or the same thing can be done using the -:meth:`pyramid.configuration.Configurator.add_view` method: +Or the same thing can be done using the ``permission`` attribute of the ZCML +:ref:`view_directive` directive. -.. ignore-next-block -.. code-block:: python - :linenos: - - config.add_view(blog_entry_add_view, - context=Blog, name='add_entry.html', permission='add') - -As a result of any of these various view configuration statements, if -an authorization policy is in place when the view callable is found -during normal application operations, the requesting user will need to -possess the ``add`` permission against the :term:`context` to be able -to invoke the ``blog_entry_add_view`` view. If he does not, the -:term:`Forbidden view` will be invoked. +As a result of any of these various view configuration statements, if an +authorization policy is in place when the view callable is found during +normal application operations, the requesting user will need to possess the +``add`` permission against the :term:`context` to be able to invoke the +``blog_entry_add_view`` view. If he does not, the :term:`Forbidden view` +will be invoked. .. _setting_a_default_permission: @@ -348,15 +300,14 @@ The first element of any ACE is either the ACE matches. The second element is a :term:`principal`. The third argument is a permission or sequence of permission names. -A principal is usually a user id, however it also may be a group id if -your authentication system provides group information and the -effective :term:`authentication policy` policy is written to respect -group information. For example, the -:class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` -enabled by the ``repozewho1authenticationpolicy`` ZCML directive -respects group information if you configure it with a ``callback``. -See :ref:`authentication_policies_directives_section` for more -information about the ``callback`` attribute. +A principal is usually a user id, however it also may be a group id if your +authentication system provides group information and the effective +:term:`authentication policy` policy is written to respect group information. +For example, the +:class:`pyramid.authentication.RepozeWho1AuthenicationPolicy` respects group +information if you configure it with a ``callback``. See +:ref:`authentication_policies_directives_section` for more information about +the ``callback`` attribute. Each ACE in an ACL is processed by an authorization policy *in the order dictated by the ACL*. So if you have an ACL like this: @@ -585,112 +536,6 @@ via print statements when a call to :func:`pyramid.security.has_permission` fails is often useful. .. index:: - pair: ZCML directive; authentication policy - -.. _authentication_policies_directives_section: - -Built-In Authentication Policy ZCML Directives ----------------------------------------------- - -Instead of configuring an authentication policy and authorization -policy imperatively, :mod:`pyramid` ships with a few "pre-chewed" -authentication policy ZCML directives that you can make use of within -your application. - -``authtktauthenticationpolicy`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When this directive is used, authentication information is obtained -from an "auth ticket" cookie value, assumed to be set by a custom -login form. - -An example of its usage, with all attributes fully expanded: - -.. code-block:: xml - :linenos: - - <authtktauthenticationpolicy - secret="goshiamsosecret" - callback=".somemodule.somefunc" - cookie_name="mycookiename" - secure="false" - include_ip="false" - timeout="86400" - reissue_time="600" - max_age="31536000" - path="/" - http_only="false" - /> - -See :ref:`authtktauthenticationpolicy_directive` for details about -this directive. - -``remoteuserauthenticationpolicy`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When this directive is used, authentication information is obtained -from a ``REMOTE_USER`` key in the WSGI environment, assumed to -be set by a WSGI server or an upstream middleware component. - -An example of its usage, with all attributes fully expanded: - -.. code-block:: xml - :linenos: - - <remoteuserauthenticationpolicy - environ_key="REMOTE_USER" - callback=".somemodule.somefunc" - /> - -See :ref:`remoteuserauthenticationpolicy_directive` for detailed -information. - -``repozewho1authenticationpolicy`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When this directive is used, authentication information is obtained -from a ``repoze.who.identity`` key in the WSGI environment, assumed to -be set by :term:`repoze.who` middleware. - -An example of its usage, with all attributes fully expanded: - -.. code-block:: xml - :linenos: - - <repozewho1authenticationpolicy - identifier_name="auth_tkt" - callback=".somemodule.somefunc" - /> - -See :ref:`repozewho1authenticationpolicy_directive` for detailed -information. - -.. index:: - pair: ZCML directive; authorization policy - -.. _authorization_policies_directives_section: - -Built-In Authorization Policy ZCML Directives ---------------------------------------------- - -``aclauthorizationpolicy`` - -When this directive is used, authorization information is obtained -from :term:`ACL` objects attached to model instances. - -An example of its usage, with all attributes fully expanded: - -.. code-block:: xml - :linenos: - - <aclauthorizationpolicy/> - -In other words, it has no configuration attributes; its existence in a -``configure.zcml`` file enables it. - -See :ref:`aclauthorizationpolicy_directive` for detailed information. - -.. index:: single: authentication policy (creating) .. _creating_an_authentication_policy: |