[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/authentication/ Add plugin information to the info object, as in

[Gary Poster]

Log message for revision 40778:
  Add plugin information to the info object, as in 
  http://mail.zope.org/pipermail/zope3-dev/2005-December/016887.html
  

Changed:
  U   Zope3/trunk/src/zope/app/authentication/README.txt
  U   Zope3/trunk/src/zope/app/authentication/authentication.py
  U   Zope3/trunk/src/zope/app/authentication/interfaces.py

-=-
Modified: Zope3/trunk/src/zope/app/authentication/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/authentication/README.txt	2005-12-14 13:52:57 UTC (rev 40777)
+++ Zope3/trunk/src/zope/app/authentication/README.txt	2005-12-14 16:51:23 UTC (rev 40778)
@@ -33,9 +33,9 @@
 
 If an authenticator succeeds in authenticating a set of credentials, the PAU
 uses the authenticator to create a principal corresponding to the credentials.
-The authenticator notifies subscribers if an authenticated principal is created.
-Subscribers are responsible for adding data, especially groups, to the
-principal. Typically, if a subscriber adds data, it should also add
+The authenticator notifies subscribers if an authenticated principal is
+created. Subscribers are responsible for adding data, especially groups, to
+the principal. Typically, if a subscriber adds data, it should also add
 corresponding interface declarations.
 
 Simple Credentials Plugin
@@ -61,7 +61,8 @@
 
 As a plugin, MyCredentialsPlugin needs to be registered as a named utility:
 
-  >>> provideUtility(MyCredentialsPlugin(), name='My Credentials Plugin')
+  >>> myCredentialsPlugin = MyCredentialsPlugin()
+  >>> provideUtility(myCredentialsPlugin, name='My Credentials Plugin')
 
 Simple Authenticator Plugin
 ---------------------------
@@ -97,7 +98,8 @@
 As with the credentials plugin, the authenticator plugin must be registered
 as a named utility:
 
-  >>> provideUtility(MyAuthenticatorPlugin(), name='My Authenticator Plugin')
+  >>> myAuthenticatorPlugin = MyAuthenticatorPlugin()
+  >>> provideUtility(myAuthenticatorPlugin, name='My Authenticator Plugin')
 
 Principal Factories
 -------------------
@@ -161,6 +163,29 @@
   >>> event.request is request
   True
 
+The info object has the id, title, and description of the principal.  The info
+object is also generated by the authenticator plugin, so the plugin may
+itself have provided additional information on the info object.
+
+  >>> event.info.title
+  'Bob'
+  >>> event.info.id # does not include pau prefix
+  'bob'
+  >>> event.info.description
+  ''
+
+It is also decorated with two other attributes, credentialsPlugin and
+authenticatorPlugin: these are the plugins used to extract credentials for and
+authenticate this principal.  These attributes can be useful for subscribers
+that want to react to the plugins used.  For instance, subscribers can
+determine that a given credential plugin does or does not support logout, and
+provide information usable to show or hide logout user interface.
+
+  >>> event.info.credentialsPlugin is myCredentialsPlugin
+  True
+  >>> event.info.authenticatorPlugin is myAuthenticatorPlugin
+  True
+
 Normally, we provide subscribers to these events that add additional
 information to the principal. For example, we'll add one that sets
 the title:
@@ -417,6 +442,14 @@
   >>> event.info
   PrincipalInfo('white')
 
+The info has an authenticatorPlugin, but no credentialsPlugin, since none was
+used.
+
+  >>> event.info.credentialsPlugin is None
+  True
+  >>> event.info.authenticatorPlugin is searchable
+  True
+
 As we have seen with authenticated principals, it is common to subscribe to
 principal created events to add information to the newly created principal.
 In this case, we need to subscribe to IFoundPrincipalCreated events:

Modified: Zope3/trunk/src/zope/app/authentication/authentication.py
===================================================================
--- Zope3/trunk/src/zope/app/authentication/authentication.py	2005-12-14 13:52:57 UTC (rev 40777)
+++ Zope3/trunk/src/zope/app/authentication/authentication.py	2005-12-14 16:51:23 UTC (rev 40778)
@@ -58,6 +58,8 @@
                 info = authplugin.authenticateCredentials(credentials)
                 if info is None:
                     continue
+                info.credentialsPlugin = credplugin
+                info.authenticatorPlugin = authplugin
                 principal = component.getMultiAdapter((info, request),
                     interfaces.IAuthenticatedPrincipalFactory)(self)
                 principal.id = self.prefix + info.id
@@ -79,6 +81,8 @@
             info = authplugin.principalInfo(id)
             if info is None:
                 continue
+            info.credentialsPlugin = None
+            info.authenticatorPlugin = authplugin
             principal = interfaces.IFoundPrincipalFactory(info)(self)
             principal.id = self.prefix + info.id
             return principal

Modified: Zope3/trunk/src/zope/app/authentication/interfaces.py
===================================================================
--- Zope3/trunk/src/zope/app/authentication/interfaces.py	2005-12-14 13:52:57 UTC (rev 40777)
+++ Zope3/trunk/src/zope/app/authentication/interfaces.py	2005-12-14 16:51:23 UTC (rev 40778)
@@ -30,7 +30,15 @@
 
 
 class IPluggableAuthentication(ILogout, IContainer):
-    """Provides authentication services with the help of various plugins."""
+    """Provides authentication services with the help of various plugins.
+    
+    IPluggableAuthentication implementations will also implement
+    zope.app.security.interfaces.IAuthentication.  The `authenticate` method
+    of this interface in an IPluggableAuthentication should annotate the
+    IPrincipalInfo with the credentials plugin and authentication plugin used.
+    The `getPrincipal` method should annotate the IPrincipalInfo with the
+    authentication plugin used.
+    """
 
     contains(IPlugin)
 
@@ -133,7 +141,20 @@
 
     description = zope.interface.Attribute("A description of the principal.")
 
+    credentialsPlugin = zope.interface.Attribute(
+        """Plugin used to generate the credentials for this principal info.
+        
+        Optional.  Should be set in IPluggableAuthentication.authenticate.
+        """)
 
+    authenticatorPlugin = zope.interface.Attribute(
+        """Plugin used to authenticate the credentials for this principal info.
+        
+        Optional.  Should be set in IPluggableAuthentication.authenticate and
+        IPluggableAuthentication.getPrincipal.
+        """)
+
+
 class IPrincipalFactory(zope.interface.Interface):
     """A principal factory."""