[Zope-PAS] Re: New IChallengePlugin interface

[Zachery Bir]

Since we don't specify attribute interfaces in Zope 2, I've left it in 
the docs of IChallengePlugin.

class IChallengePlugin( Interface ):

    """ Initiate a challenge to the user to provide credentials.

        Challenge plugins have an attribute 'protocol' representing
        the protocol the plugin operates under. Plugins operating
        under the same protocol will all be given an attempt to
        fire. The first plugin of a protocol group that successfully
        fires establishes the protocol of the overall challenge. By
        default, the protocol should be the id of the plugin, which
        means if it fires, it fires alone.
    """

    def challenge( request, response ):

        """ Assert via the response that credentials will be gathered.

        Takes a REQUEST object and a RESPONSE object, and returns
        either self.protocol if it fires, or None.

        Two common ways to initiate a challenge:

          - Add a 'WWW-Authenticate' header to the response object.

            NOTE: add, since the HTTP spec specifically allows for
            more than one challenge in a given response.

          - Cause the response object to redirect to another URL (a
            login form page, for instance)
        """