Metadata-Version: 1.0
Name: megrok.login
Version: 0.4
Summary: Providing login screens for your Grok apps made easy.
Home-page: http://pypi.python.org/pypi/megrok.login
Author: Uli Fouquet and the Zope Community
Author-email: uli@gnufix.de
License: ZPL 2.1
Description: megrok.login
        ************
        
        Setting up session based login screens for your Grok-based webapps
        made easy.
        
        With ``megrok.login`` you can setup a "Pluggable Authentication
        Utility" (PAU) automatically, whenever an instance of a
        ``grok.Application`` is put into the ZODB. The most notable effect is,
        that you will have a login screen instead of the basic-auth
        authentication when users try to access protected views.
        
        To enable your users to login via a login screen instead of
        basic-auth, it is sufficient to create and install an application like
        this::
        
        import grok
        import megrok.login
        
        class App(grok.Application, grok.Container):
        """An application.
        """
        megrok.login.enable()
        
        See detailed documentation below for details on finetuning
        authentication with ``megrok.login``.
        
        
        Installation
        ============
        
        1) Add `megrok.login` to the dependencies in your ``setup.py``.
        
        2) Run::
        
        $ ./bin/buildout
        
        3) Use ``megrok.login`` in your code.
        
        
        Detailed Documentation
        **********************
        
        
        megrok.login
        ************
        
        Setting up login pages for your web app made easy.
        
        With `megrok.login` you can setup simple session based login pages
        for your ``grok.Application`` and other ``grok.Site`` instances. This
        is different to out-of-the-box behaviour, where authentication happens
        by basic-auth.
        
        Introduction
        ============
        
        Here we sketch in short, how you can enable simple session based
        authentication with ``megrok.login``. More complex examples can
        be found in the `tests` subdirectory:
        
        * Basic usage:
        
        - ``simple.py``:
        
        How to setup simple(tm) session based authentication with default
        values. This covers the most basic use case.
        
        - ``customlogin.py``:
        
        How to setup session based authentication with your own login page.
        
        - ``autoregister.py``:
        
        How to setup session based authentication so that users can
        register with the site simply by providing a self-chosen password.
        
        - ``strict.py``:
        
        How to setup session based authentication without allowing fallback
        to internal principals which were setup by ZCML at startup.
        
        * More advanced stuff:
        
        - ``custompausetup.py``:
        
        How to setup session based authentication with your own setup of
        the ``Pluggable Authentication Utility``.
        
        
        The ``megrok.login`` directives
        ===============================
        
        What you can do with ``megrok.login``:
        
        
        ``megrok.login.enable()``
        -------------------------
        
        Enables session based authentication. This marker directive *must* be
        used in order to use ``megrok.login`` functionality. It can be set on
        any `grok.Site` class::
        
        import grok
        import megrok.login
        class MyApp(grok.Application, grok.Container):
        megrok.login.enable()
        
        If no other ``megrok.login`` directive is used, it enables session
        based authentication (login screens instead of basic-auth).
        
        ``megrok.login.viewname(<viewname>)``
        -------------------------------------
        
        Registers the view with the name ``<viewname>`` as login page. This
        way you can specify your own login page. You must also use
        ``megrok.login.enable()`` to make this work::
        
        import grok
        import megrok.login
        
        class MyApp(grok.Application, grok.Container):
        megrok.login.enable()
        megrok.login.viewname('login')
        
        class Login(grok.View):
        def render(self):
        
        def update(self, camefrom=None, SUBMIT=None):
        self.camefrom=camefrom
        if SUBMIT is not None and camefrom is not None:
        # The credentials were entered. Go back. If the entered
        # credentials are not valid, another redirect will happen
        # to this view.
        self.redirect(camefrom)
        return
        
        whereas the template for the login view might look like this::
        
        <html>
        <head>
        <title>Login</title>
        </head>
        <body>
        <h1>Custom Login Page</h1>
        <form method="post">
        <div>
        <label for="login">Username</label>
        <input type="text" name="login" id="login" />
        </div>
        <div>
        <label for="password">Password</label>
        <input type="password" name="password" id="password" />
        </div>
        <div>
        <input type="hidden" name="camefrom"
        tal:attributes="value view/camefrom" />
        <input type="submit" name="SUBMIT" value="Log in" />
        </div>
        </form>
        </body>
        </html>
        
        See ``tests/customlogin.py`` for details.
        
        ``megrok.login.strict()``
        -------------------------
        
        Normally, ``megrok.login`` installs two authenticator plugins for your
        site:
        
        * a normal ``PrincipalFolder``, that can contain principals (users)
        but is empty in the beginning.
        
        * a fallback authenticator, that authenticates against the principals
        of the internal principal registry.
        
        If you use ``megrok.login.strict()``, the latter is not installed and
        users like the manager user defined in your site.zcml won't be
        accepted by your login page.
        
        Example::
        
        import grok
        import megrok.login
        class MyApp(grok.Application, grok.Container):
        megrok.login.enable()
        megrok.login.strict()
        
        See ``tests/strict.py`` for details.
        
        
        ``megrok.login.autoregister()``
        -------------------------------
        
        If this directive is used, the authentication system will register
        automatically any user that still does not exist on login and add it
        to the ``PrincipalFolder``.
        
        Example::
        
        import grok
        import megrok.login
        
        class ManageApp(grok.Permission):
        grok.name('app.ManageAutoRegister')
        
        class AutoRegisterApp(grok.Application, grok.Container):
        megrok.login.enable()
        # We grant this permission to autoregistered users.
        megrok.login.autoregister('app.ManageAutoRegister')
        
        See ``tests/autoregister.py`` for details.
        
        
        ``megrok.login.setup(<callable>)``
        ----------------------------------
        
        If you want to setup the Pluggable Authentication Utility (PAU)
        yourself, then you can use this directive. It expects a callable as
        argument, that will be called with an already created PAU instance as
        argument as soon as an application (or other ``grok.Site``) object is
        added to the ZODB.
        
        See ``tests/custompausetup.py`` for details.
        
        
        
        
        megrok.login changes
        ********************
        
        0.4 (2011-02-09)
        ==================
        
        * Update dependencies/imports to stay compatible with Grok 1.3. No
        more zope.app.\* dependencies.
        
        .. warning:: This version is not compatible with Grok < 1.3!
        
        Note that starting with this release you have to register session
        support manually, like this in your ``configure.zcml``:
        
        <include package="zope.session" file="configure.zcml" />
        
        This is not needed, if you use ``z3c.autoinclude`` and have some
        ``includeDependencies`` directive in your ``configure.zcml``.
        
        * Added (optional) ``loginForm.html`` view to replace the one yet
        provided by `zope.app.authentication`.
        
        .. note:: To activate the included ``loginForm.html`` you have to
        include the ``megrok.login.loginpage.zcml`` **explicitly**. Add
        a snippet like this in your ``configure.zcml``:
        
        <include package="megrok.login" file="loginpage.zcml" />
        
        If you define your own login page, this step is not needed.
        
        
        0.3 (2010-07-03)
        ================
        
        * Support for Grok 1.1, 1.2.
        
        We now use zope.pluggableauth and friends if available. Note, that
        if you run into problems like non-found authentication adapters, you
        might have to add `zope.app.authentication` manually in your
        project. You can do so by adding::
        
        <include package="zope.app.authentication" file="configure.zcml"
        />
        
        in your projects' `configure.zcml`.
        
        If you use ``includeDependencies`` in your projects'
        ``configure.zcml`` (which is most likely true for all projects based
        on `grokproject`, it should be sufficient to depend on
        `megrok.login` in your project's ``setup.py``, as the
        ``configure.zcml`` of `megrok.login` now includes
        ``zope.app.authentication`` for you.
        
        * Default PAU setup now does not include 'No Challenge if
        Authenticated' authenticator plugin anymore. Using this plugin in a
        pipe of authenicators, already authenticated users that entered a
        still forbidden page got ``Unauthorized`` errors instead of being
        redirected to the login page.
        
        Note that this new behaviour applies only to applications newly
        created. If you have some older applications setup with an older
        version of `megrok.login`, you have to modify the authenticator
        plugins of your already setup PAU manually, for instance using the
        ZMI.
        
        
        0.2 (2009-12-09)
        ================
        
        * Changed utility setup to reflect changes in Grok API: eventually use
        `IUtilitySetup` instead of `grokcore.meta.setupUtility`. Thanks go to
        Simon Jagoe.
        
        * Changed the test configuration to handle the new grok.View permission.
        
        * Added the versions.cfg file from grok.
        
        
        0.1 (2008-12-26)
        ================
        
        (initial version)
        
        
        Download
        ********
        
Keywords: zope3 zope login grok security PAU
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Framework :: Zope3
