Salesforce Auth Plugin for Plone PAS

 http://plone.org/products/salesforceauthplugin

Installation, Configuration, and Usage

 I. Overview 

  This document provides details on how to install and use Salesforce Auth Plugin
  within your Plone site.


 II. Requirements

  a. Active Salesforce.com account with API access from http://www.salesforce.com

  b. Developed and tested against >= Plone 3.0.x (Zope 2.10.x with Python 2.4.x), though
     it may work with >= Plone 2.5.x (Zope 2.9.x with Python 2.4.x)

  c. salesforcebaseconnector (and its pre-reqs, such as 'beatbox' python product)
     Instructions for configuration of salesforcebaseconnector are in README.txt of the
     product which is downloadable here:
     http://plone.org/products/salesforcebaseconnector

  d. some basic understanding the PAS and PlonePAS infrastructure and capabilities


 III. Required Steps for Installation into Plone

  Step 1 - IMPORTANT: Make sure you install/configure salesforcebaseconnector as 
      mentioned above and set your login and password.

  Step 2 - Install the salesforceauthplugin product as you would for
      any normal Plone product (unzip it in your Zope's Products
      directory and install it using Add/Remove Products or
      Portal Quick Installer).


 IV. Configure Plugin

  Though you've already installed the Salesforce Auth Plugin, which creates and activates
  a PAS plugin for use in authentication, user creation, and profile management, this 
  has no impact on your Plone site's authentication scheme until you've done some additional 
  configuration.

  Configure the salesforceauthplugin through the ZMI, at acl_users/salesforceauthmultiplugin.

  At a minimum, you need to determine and configure on the Salesforce Auth Plugin:

  a. Which Salesforce.com object (i.e. Contact, Lead, Account, etc.) you'll treat as users 
     within your site (remember that if you'd like to treat multiple Salesforce objects as
     users, you can do so by setting up multiple Salesforce Auth Plugins).  See 
     "Caveats" in this document for more information on this.

  b. Which fields of the aforementioned chosen SFObject will serve as the username
     and password credentials for authentication.  At this point, the Salesforce Auth
     Plugin assumes that credentials will include and be limited to some field
     used for "username" and another optionally encryption aware field for password. This
     would look like:
     
      password|Password__c
      username|UserName__c

  In addition, you can enable password encryption, setup additional authentication
  requirements (in the form of a SOQL statement), and choose which properties to 
  manage in Salesforce.com, rather than within Mutable Properties.  This would look
  like:
  
    assistant_name|AssistantName
    department|Department


 V. Caching
 
  In addition to creating and activating a PAS plugin for use in authentication, 
  user creation, and profile management within your acl_users object, Salesforce
  Auth Plugin also associates a RAM cache with the created plugin.  The cache period
  is set for 10 minutes by default.  This is essential for ensuring that the use of
  Salesforce Auth Plugin doesn't adversely impact the performance of your Plone site.
  
  The Salesforce Auth Plugin caches user enumerations and user properties.  If you only
  manage your users and user properties through Plone, the cache will not have any
  adverse effects, as the Salesforce Auth Plugin will invalidate the cache when changes
  take place.  However, be aware that when modifying users through Salesforce.com, Plone
  may not be aware of the changes for up to 10 minutes.  This applies for any of the
  following modifications via Salesforce.com.
  
  a. new user added
  b. user removed
  d. user properties for user are changed
  
  To modify the cache period: In the ZMI, go to SalesforceAuthPluginCache in your portal root.
  
  To remove the cache: In the ZMI, go to acl_users/salesforceauthmultiplugin and go to the
  Caching tab.
  
  User authentication can also be optionally cached.  This is disabled by default.  To enable
  it, set CACHE_PASSWORDS to True in config.py.  This may boost performance at the expense of
  also introducing a 10-minute delay when passwords are changed via salesforce.com.
  

 VI. Through The Web Testing

  Let's try joining a site and seeing if the login appears in Salesforce.com

  Once the plugin is installed open up a browser and enter the url of your
  Plone instance. You may need to log out first which will require closing your
  browser and reopening it.

  For Plone 3.0.x:

   In Plone 3.0, registration is disabled by default.

   As site admin, head over to "Site Setup->Security" then check the 
   "Enable self-registration" option.  
   
   You may want to make sure your new Plone site's Mail server settings (and
   "From:" address) are setup so when you create a new account, Plone can
   send its Welcome email.

   Click on the link to join (in the upper right hand corner, next to the log-in
   link) to create a new login.

   Go ahead and add the user and then log in to your Salesforce account
   at http://www.salesforce.com. The user you just added
   should be found in your list of contacts.

   Then, you should be able to log out of Plone and try logging in as
   the new user you just created.  See the "Customizing" section of this
   document for tips about how you might tweak the user experience a bit more.
   


 VII. Customizing

  For simple tweaks to the personalize form, see documentation in 
  "customizing_personalize.txt" within the ./docs directory.

  Other customization techniques to be flushed out as needed.
  
  A. Helpful Tips
  
   * If you're setting a Date or DateTime property on a Salesforce object
     make sure your input field type is of DateTime format.  Manually, this 
     is done with:
     
      <input type="text" name="birthdate:date"/>


 VIII. Caveats

  * At this time, Contact, Account, and Lead objects have been pretty 
    thoroughly tested and are the target use cases for this product.  One might
    commonly want to use some custom Salesforce.com object to serve as the user object.
    While technically, probably any object could work for authentication, assuming a username
    and password field have been configured, other Salesforce.com objects may or may not work
    with all available PAS configuration options.

  * As a follow-up to the caveat regarding which Salesforce objects are likely to work with this
    product, at this time objects where there are required fields that don't except a string data type
    will not work as a user adder utility.  For example, the Event object requires an integer for 
    length in minutes as well as an HTML4 formatted date/time for start of event.  By contrast,
    the interface for doAddUser mandates that only the login and password are passed in the signature.
    For this reason, when create is called via the Salesforce.com API, we use the provided login value
    for all required fields needed to create the object.  Thus, PAS join capability is unlikely 
    to pass doAddUser the appropriate data types for all required fields for more complex Salesforce
    objects (ala Event) in order to allow the initial creation of the object to happen.  Of course,
    PlonePAS will then go forth and update (using set property capabilities) those fields that were
    temporarily stocked with the login value if they were asked somewhere in the signup process, since
    this happens after doAddUser is called.

  * Self-Service Users and Salesforce.com Users have not been tested with this product.  They 
    may or may not work.  In future releases, code/testing efforts will likely be put forth to 
    ensure that this works.

