How to install megrok.login
- Download and install ActivePython
- Open Command Prompt
pypm install 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.
Add megrok.login to the dependencies in your setup.py.
- Use megrok.login in your code.
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.
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:
How to setup simple(tm) session based authentication with default values. This covers the most basic use case.
How to setup session based authentication with your own login page.
How to setup session based authentication so that users can register with the site simply by providing a self-chosen password.
How to setup session based authentication without allowing fallback to internal principals which were setup by ZCML at startup.
- More advanced stuff:
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:
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).
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.
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.
import grok import megrok.login class MyApp(grok.Application, grok.Container): megrok.login.enable() megrok.login.strict()
See tests/strict.py for details.
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.
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.
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.
- Update dependencies/imports to stay compatible with Grok 1.3. No
more zope.app.* dependencies.
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.
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.
- 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.
- 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.