Merge pull request #1399 from Pylons/feature.security-docs-enhancements

security docs enhancements

6 files changed, 103 insertions, 64 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 77d80f6d6..dd68fa09c 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -167,37 +167,40 @@
 
       .. versionadded:: 1.5
 
-      A property which returns the userid of the currently authenticated user
-      or ``None`` if there is no :term:`authentication policy` in effect or
-      there is no currently authenticated user.  This differs from
-      :attr:`~pyramid.request.Request.unauthenticated_userid`, because the
-      effective authentication policy will have ensured that a record
-      associated with the userid exists in persistent storage; if it has
-      not, this value will be ``None``.
+      A property which returns the :term:`userid` of the currently
+      authenticated user or ``None`` if there is no :term:`authentication
+      policy` in effect or there is no currently authenticated user.  This
+      differs from :attr:`~pyramid.request.Request.unauthenticated_userid`,
+      because the effective authentication policy will have ensured that a
+      record associated with the :term:`userid` exists in persistent storage;
+      if it has not, this value will be ``None``.
 
    .. attribute:: unauthenticated_userid
 
       .. versionadded:: 1.5
 
       A property which returns a value which represents the *claimed* (not
-      verified) user id of the credentials present in the request. ``None`` if
-      there is no :term:`authentication policy` in effect or there is no user
-      data associated with the current request.  This differs from
-      :attr:`~pyramid.request.Request.authenticated_userid`, because the
-      effective authentication policy will not ensure that a record associated
-      with the userid exists in persistent storage.  Even if the userid
-      does not exist in persistent storage, this value will be the value
-      of the userid *claimed* by the request data.
+      verified) :term:`userid` of the credentials present in the
+      request. ``None`` if there is no :term:`authentication policy` in effect
+      or there is no user data associated with the current request.  This
+      differs from :attr:`~pyramid.request.Request.authenticated_userid`,
+      because the effective authentication policy will not ensure that a
+      record associated with the :term:`userid` exists in persistent storage.
+      Even if the :term:`userid` does not exist in persistent storage, this
+      value will be the value of the :term:`userid` *claimed* by the request
+      data.
 
    .. attribute:: effective_principals
 
       .. versionadded:: 1.5
 
       A property which returns the list of 'effective' :term:`principal`
-      identifiers for this request.  This will include the userid of the
-      currently authenticated user if a user is currently authenticated. If no
-      :term:`authentication policy` is in effect, this will return a sequence
-      containing only the :attr:`pyramid.security.Everyone` principal.
+      identifiers for this request.  This list typically includes the
+      :term:`userid` of the currently authenticated user if a user is
+      currently authenticated, but this depends on the
+      :term:`authentication policy` in effect.  If no :term:`authentication
+      policy` is in effect, this will return a sequence containing only the
+      :attr:`pyramid.security.Everyone` principal.
 
    .. method:: invoke_subrequest(request, use_tweens=False)
 
diff --git a/docs/api/security.rst b/docs/api/security.rst
index 814b68e5a..88086dbbf 100644
--- a/docs/api/security.rst
+++ b/docs/api/security.rst
@@ -16,7 +16,7 @@ Authentication API Functions
 
 .. autofunction:: forget
 
-.. autofunction:: remember
+.. autofunction:: remember(request, userid, **kwargs)
 
 Authorization API Functions
 ---------------------------
diff --git a/docs/glossary.rst b/docs/glossary.rst
index ef7e9a9ae..01300a0be 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -286,13 +286,22 @@ Glossary
      :term:`authorization policy`.
 
    principal
-     A *principal* is a string or unicode object representing a userid
-     or a group id.  It is provided by an :term:`authentication
-     policy`.  For example, if a user had the user id "bob", and Bob
-     was part of two groups named "group foo" and "group bar", the
-     request might have information attached to it that would
-     indicate that Bob was represented by three principals: "bob",
-     "group foo" and "group bar".
+     A *principal* is a string or unicode object representing an
+     entity, typically a user or group.  Principals are provided by an
+     :term:`authentication policy`.  For example, if a user had the
+     :term:`userid` `"bob"`, and was part of two groups named `"group foo"`
+     and "group bar", the request might have information attached to
+     it that would indicate that Bob was represented by three
+     principals: `"bob"`, `"group foo"` and `"group bar"`.
+
+   userid
+     A *userid* is a string or unicode object used to identify and
+     authenticate a real-world user (or client).  A userid is
+     supplied to an :term:`authentication policy` in order to discover
+     the user's :term:`principals <principal>`.  The default behavior
+     of the authentication policies :app:`Pyramid` provides is to
+     return the user's userid as a principal, but this is not strictly
+     necessary in custom policies that define their principals differently.
 
    authorization policy
      An authorization policy in :app:`Pyramid` terms is a bit of
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 8db23a33b..2dc0c76af 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -6,13 +6,28 @@
 Security
 ========
 
-:app:`Pyramid` provides an optional declarative authorization system
-that can prevent a :term:`view` from being invoked based on an
+:app:`Pyramid` provides an optional, declarative, security system.
+Security in :app:`Pyramid` is separated into authentication and
+authorization. The two systems communicate via :term:`principal`
+identifiers. 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 that are in effect during the request. Authorization then determines
+access based on the :term:`principal` identifiers, the requested
+:term:`permission`, and a :term:`context`.
+
+The :app:`Pyramid` authorization system
+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 user may or may not have previously visited the application and
+  supplied authentication credentials, including a :term:`userid`.  If
+  so, the application may have called
+  :func:`pyramid.security.remember` to remember these.
+
 - A :term:`request` is generated when a user visits the application.
 
 - Based on the request, a :term:`context` resource is located through
@@ -25,7 +40,9 @@ allowed.  Here's how it works at a high level:
   context as well as other attributes of the request.
 
 - If an :term:`authentication policy` is in effect, it is passed the
-  request; it returns some number of :term:`principal` identifiers.
+  request. It will return some number of :term:`principal` identifiers.
+  To do this, the policy would need to determine the authenticated
+  :term:`userid` present in the request.
 
 - If an :term:`authorization policy` is in effect and the :term:`view
   configuration` associated with the view callable that was found has
@@ -41,15 +58,6 @@ allowed.  Here's how it 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
@@ -104,7 +112,8 @@ For example:
 
 The above configuration enables 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
+to a single :term:`userid` and matches that userid's
+:term:`principals <principal>` against the principals present in any
 :term:`ACL` found in the resource tree when attempting to call some
 :term:`view`.
 
@@ -595,36 +604,53 @@ that implements the following interface:
        """ An object representing a Pyramid authentication policy. """
 
        def authenticated_userid(self, request):
-           """ Return the authenticated userid or ``None`` if no
-           authenticated userid can be found. This method of the policy 
-           should ensure that a record exists in whatever persistent store is 
-           used related to the user (the user should not have been deleted); 
-           if a record associated with the current id does not exist in a 
-           persistent store, it should return ``None``."""
+           """ Return the authenticated :term:`userid` or ``None`` if
+           no authenticated userid can be found. This method of the
+           policy should ensure that a record exists in whatever
+           persistent store is used related to the user (the user
+           should not have been deleted); if a record associated with
+           the current id does not exist in a persistent store, it
+           should return ``None``.
+
+           """
 
        def unauthenticated_userid(self, request):
-           """ Return the *unauthenticated* userid.  This method performs the
-           same duty as ``authenticated_userid`` but is permitted to return the
-           userid based only on data present in the request; it needn't (and
-           shouldn't) check any persistent store to ensure that the user record
-           related to the request userid exists."""
+           """ Return the *unauthenticated* userid.  This method
+           performs the same duty as ``authenticated_userid`` but is
+           permitted to return the userid based only on data present
+           in the request; it needn't (and shouldn't) check any
+           persistent store to ensure that the user record related to
+           the request userid exists.
+
+           This method is intended primarily a helper to assist the
+           ``authenticated_userid`` method in pulling credentials out
+           of the request data, abstracting away the specific headers,
+           query strings, etc that are used to authenticate the request.
+
+           """
 
        def effective_principals(self, request):
            """ Return a sequence representing the effective principals
-           including the userid and any groups belonged to by the current
-           user, including 'system' groups such as
-           ``pyramid.security.Everyone`` and
-           ``pyramid.security.Authenticated``. """
+           typically including the :term:`userid` and any groups belonged
+           to by the current user, always including 'system' groups such
+           as ``pyramid.security.Everyone`` and
+           ``pyramid.security.Authenticated``.
 
-       def remember(self, request, principal, **kw):
+           """
+
+       def remember(self, request, userid, **kw):
            """ Return a set of headers suitable for 'remembering' the
-           principal named ``principal`` when set in a response.  An
-           individual authentication policy and its consumers can decide
-           on the composition and meaning of **kw. """
-       
+           :term:`userid` named ``userid`` when set in a response.  An
+           individual authentication policy and its consumers can
+           decide on the composition and meaning of **kw.
+
+           """
+
        def forget(self, request):
            """ Return a set of headers suitable for 'forgetting' the
-           current user on subsequent requests. """
+           current user on subsequent requests.
+
+           """
 
 After you do so, you can pass an instance of such a class into the
 :class:`~pyramid.config.Configurator.set_authentication_policy` method
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
index eb785dd1c..28380bd66 100644
--- a/docs/tutorials/wiki/design.rst
+++ b/docs/tutorials/wiki/design.rst
@@ -53,10 +53,10 @@ Security
 We'll eventually be adding security to our application.  The components we'll
 use to do this are below.
 
-- USERS, a dictionary mapping usernames to their
+- USERS, a dictionary mapping :term:`userids <userid>` to their
   corresponding passwords.
 
-- GROUPS, a dictionary mapping usernames to a
+- GROUPS, a dictionary mapping :term:`userids <userid>` to a
   list of groups to which they belong to.
 
 - ``groupfinder``, an *authorization callback* that looks up
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index df2c83398..ff7413668 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -53,7 +53,8 @@ Security
 We'll eventually be adding security to our application.  The components we'll
 use to do this are below.
 
-- USERS, a dictionary mapping users names to their corresponding passwords.
+- USERS, a dictionary mapping users names (the user's :term:`userids
+  <userid>`) to their corresponding passwords.
 
 - GROUPS, a dictionary mapping user names to a list of groups they belong to.