Merge branch 'caseman-master'

1 files changed, 18 insertions, 8 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index ebaeb1526..e395b15f1 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -6,13 +6,14 @@
 Security
 ========
 
-:app:`Pyramid` provides an optional declarative authorization system that
-prevents a :term:`view` from being invoked when the user represented by
-credentials in the :term:`request` does not have an appropriate level of
-access when a particular resource is the :term:`context`.  Here's how it
-works at a high level:
+:app:`Pyramid` provides an optional declarative authorization system
+that can prevent a :term:`view` from being invoked based on an
+:term:`authorization policy`. Before a view is invoked, the
+authorization system can use the credentials in the :term:`request`
+along with the :term:`context` resource to determine if access will be
+allowed.  Here's how it works at a high level:
 
-- A :term:`request` is generated when a user visits our application.
+- A :term:`request` is generated when a user visits the application.
 
 - Based on the request, a :term:`context` resource is located through
   :term:`resource location`.  A context is located differently depending on
@@ -40,6 +41,15 @@ works at a high level:
 - If the authorization policy denies access, the view callable is not
   invoked; instead the :term:`forbidden view` is invoked.
 
+Security in :app:`Pyramid`, unlike many systems, cleanly and explicitly
+separates authentication and authorization. Authentication is merely the
+mechanism by which credentials provided in the :term:`request` are
+resolved to one or more :term:`principal` identifiers. These identifiers
+represent the users and groups in effect during the request.
+Authorization then determines access based on the :term:`principal`
+identifiers, the :term:`view callable` being invoked, and the
+:term:`context` resource.
+
 Authorization is enabled by modifying your application to include an
 :term:`authentication policy` and :term:`authorization policy`.
 :app:`Pyramid` comes with a variety of implementations of these
@@ -163,8 +173,8 @@ to invoke the ``blog_entry_add_view`` view.  If he does not, the
 Setting a Default Permission
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a permission is not supplied to a view configuration, the
-registered view always be executable by entirely anonymous users: any
+If a permission is not supplied to a view configuration, the registered
+view will always be executable by entirely anonymous users: any
 authorization policy in effect is ignored.
 
 In support of making it easier to configure applications which are