ztm.membership lets topics register as principals. This means that a
user-account can be bound to a topic, optionally giving each user their own
page in a site.

Authorization can be delegated using associations.

To enable this package, navigate to the /@@membership view on the topic map
object, typically something like /topicmap/@@membership. There you can run the
setup and tell ztm.membership to plug itself into the pluggable authentication
utility for the site.

Overview:
ztm.membership enables topics to act as principals. Role- and permission- grants are 
made by creating associations of certain types in the topicmap.


Installing:
To use this package, do the following:
  * include ztm.membership in your site.zcml and setup.py files of your zope-instance
    (or in the configure.zcml and setup.py file of one of your own eggs)
    
  * run ./bin/buildout on your zope-instance.
  
  * start your zope-instance and log in as a admin-user.
  
  * Go to "/topicmap/@@import" and click "ztm.membership"-link. This will update the
    topicmap with the topictypes, associationtypes, roletypes and occurrencetypes
    used by the code in ztm.membership.
  
  * Create and register a "ztm.membership Pluggable Authentication Utility" and add 
    a "ztm.membership authenticator plugin" to the utility. You can call either call 
    the ztm.membership.authentication.setupDefaultPluggableAuthentication()-function 
    from somewhere in your own code (for instance from a handler of the IDatabaseOpenedWithRootEvent
    event), or you can do it manually via the zmi like this:
      * In a webbrowser, log on as an administrator in your zope-instance (using /@@login.html) and 
        go to this page "/++etc++site/@@contents.html"
        
         * Add a "ztm.membership Pluggable Authentication Utility" (using the add-menu at the left side of the page)

         * Click on the new utility (you should end up at "/++etc++site/PluggableAuthentication/@@configure.html")
            * Click on the "Registration"-tab
              * Click on the "Register this object"-button
                 * Click on the "Register"-button
                 
         * Go back to the authentication plugin ("/++etc++site/PluggableAuthentication/@@configure.html")
           * Click on the "Plugins"-tab
             * Add a "ztm.membership authenticator plugin" (using the add-menu at the left side of the page)
                
         * Go back to the authentication plugin ("/++etc++site/PluggableAuthentication/@@configure.html")
           * In the "Credentials Plugins"-box, enable these plugins (in this order):
              "No Channenge if Authenticated"
              "Session Credentials"
           * In the "Authenticator Plugins"-box, enable the "ZTMMembership_Authenticator"-plugin
           * Click the "Change"-button to store the new settings.
           

Using:
The ZTMMembership_PluggableAuthentication can create principals in two ways:
1) If a principal is authenticated directly by the ZTMMembership_Authenticator 
   class (by looking up a topic and checking that the supplied password matches 
   the password stored in the topic), a TopicPrincipal object will be created. 
2) If a principal is authenticated by some other authenticator (for instance a 
   principal folder or LDAP authenticator), the principal created by the other
   authenticator will be wrapped in a TopicPrincipalWrapper object, and a topic
   will be created (if needed) to represent the principal.