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

security docs enhancements

1 files changed, 16 insertions, 7 deletions

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