Home       Trees       Indices       Help   
web2py Web Framework
Package web2py :: Package gluon :: Module tools :: Class Auth
[hide private]
[frames] | no frames]

Class Auth

source code

object --+
         |
        Auth


Class for authentication, authorization, role based access control.

Includes:

- registration and profile
- login and logout
- username and password retrieval
- event logging
- role creation and assignment
- user defined group/role based permission

Authentication Example::

    from contrib.utils import *
    mail=Mail()
    mail.settings.server='smtp.gmail.com:587'
    mail.settings.sender='you@somewhere.com'
    mail.settings.login='username:password'
    auth=Auth(globals(), db)
    auth.settings.mailer=mail
    # auth.settings....=...
    auth.define_tables()
    def authentication():
        return dict(form=auth())

exposes:

- http://.../{application}/{controller}/authentication/login
- http://.../{application}/{controller}/authentication/logout
- http://.../{application}/{controller}/authentication/register
- http://.../{application}/{controller}/authentication/verify_email
- http://.../{application}/{controller}/authentication/retrieve_username
- http://.../{application}/{controller}/authentication/retrieve_password
- http://.../{application}/{controller}/authentication/reset_password
- http://.../{application}/{controller}/authentication/profile
- http://.../{application}/{controller}/authentication/change_password

On registration a group with role=new_user.id is created
and user is given membership of this group.

You can create a group with::

    group_id=auth.add_group('Manager', 'can access the manage action')
    auth.add_permission(group_id, 'access to manage')

Here "access to manage" is just a user defined string.
You can give access to a user::

    auth.add_membership(group_id, user_id)

If user id is omitted, the logged in user is assumed

Then you can decorate any action::

    @auth.requires_permission('access to manage')
    def manage():
        return dict()

You can restrict a permission to a specific table::

    auth.add_permission(group_id, 'edit', db.sometable)
    @auth.requires_permission('edit', db.sometable)

Or to a specific record::

    auth.add_permission(group_id, 'edit', db.sometable, 45)
    @auth.requires_permission('edit', db.sometable, 45)

If authorization is not granted calls::

    auth.settings.on_failed_authorization

Other options::

    auth.settings.mailer=None
    auth.settings.expiration=3600 # seconds

    ...

    ### these are messages that can be customized
    ...


Instance Methods [hide private]
 
url(self, f=1, args=[], vars={}) source code
 
__init__(self, environment=1, db=1, controller='default', cas_provider=1)
auth=Auth(globals(), db)...		 source code
 
_get_user_id(self)
accessor for auth.user_id		 source code
 
_HTTP(self, *a, **b)
only used in lambda: self._HTTP(404)		 source code
 
__call__(self)
usage:		 source code
 
navbar(self, prefix='Welcome', action=1) source code
 
__get_migrate(self, tablename, migrate=True) source code
 
define_tables(self, username=True, migrate=True, fake_migrate=True)
to be called unless tables are defined manually		 source code
 
log_event(self, description, origin='auth')
usage:		 source code
 
get_or_create_user(self, keys)
Used for alternate login methods: If the user exists already then password is updated.		 source code
 
basic(self) source code
 
login_bare(self, username, password)
logins user		 source code
 
cas_login(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>, version=1) source code
 
cas_validate(self, version=1) source code
 
login(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a login form ..		 source code
 
logout(self, next=<function <lambda> at 0x26ba500>, onlogout=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
logout and redirects to login ..		 source code
 
register(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a registration form ..		 source code
 
is_logged_in(self)
checks if the user is logged in and returns True/False.		 source code
 
verify_email(self, next=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
action user to verify the registration email, XXXXXXXXXXXXXXXX ..		 source code
 
retrieve_username(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a form to retrieve the user username (only if there is a username field) ..		 source code
 
random_password(self) source code
 
reset_password_deprecated(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a form to reset the user password (deprecated) ..		 source code
 
reset_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a form to reset the user password ..		 source code
 
request_reset_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a form to reset the user password ..		 source code
 
retrieve_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>) source code
 
change_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a form that lets the user change password ..		 source code
 
profile(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)
returns a form that lets the user change his/her profile ..		 source code
 
is_impersonating(self) source code
 
impersonate(self, user_id=<function <lambda> at 0x26ba500>)
usage: POST TO http://..../impersonate request.post_vars.user_id=<id> set request.post_vars.user_id to 0 to restore original user.		 source code
 
groups(self)
displays the groups and their roles for the logged in user		 source code
 
not_authorized(self)
you can change the view for this page to make it look as you like		 source code
 
requires(self, condition)
decorator that prevents access to action if not logged in		 source code
 
requires_login(self)
decorator that prevents access to action if not logged in		 source code
 
requires_membership(self, role=1, group_id=1)
decorator that prevents access to action if not logged in or if user logged in is not a member of group_id.		 source code
 
requires_permission(self, name, table_name='', record_id=0)
decorator that prevents access to action if not logged in or if user logged in is not a member of any group (role) that has 'name' access to 'table_name', 'record_id'.		 source code
 
requires_signature(self)
decorator that prevents access to action if not logged in or if user logged in is not a member of group_id.		 source code
 
add_group(self, role, description='')
creates a group associated to a role		 source code
 
del_group(self, group_id)
deletes a group		 source code
 
id_group(self, role)
returns the group_id of the group specified by the role		 source code
 
user_group(self, user_id=1)
returns the group_id of the group uniquely associated to this user i.e.		 source code
 
has_membership(self, group_id=1, user_id=1, role=1)
checks if user is member of group_id or role		 source code
 
add_membership(self, group_id=1, user_id=1, role=1)
gives user_id membership of group_id or role if user_id==None than user_id is that of current logged in user		 source code
 
del_membership(self, group_id, user_id=1, role=1)
revokes membership from group_id to user_id if user_id==None than user_id is that of current logged in user		 source code
 
has_permission(self, name='any', table_name='', record_id=0, user_id=1, group_id=1)
checks if user_id or current logged in user is member of a group that has 'name' permission on 'table_name' and 'record_id' if group_id is passed, it checks whether the group has the permission		 source code
 
add_permission(self, group_id, name='any', table_name='', record_id=0)
gives group_id 'name' access to 'table_name' and 'record_id'		 source code
 
del_permission(self, group_id, name='any', table_name='', record_id=0)
revokes group_id 'name' access to 'table_name' and 'record_id'		 source code
 
accessible_query(self, name, table, user_id=1)
returns a query with all accessible records for user_id or the current logged in user this method does not work on GAE because uses JOIN and IN		 source code

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

Properties [hide private]
  user_id
user.id or None

Inherited from object: __class__

Method Details [hide private]

__init__(self, environment=1, db=1, controller='default', cas_provider=1)
(Constructor)

source code  

auth=Auth(globals(), db)

- environment is there for legacy but unused (awful)
- db has to be the database where to create tables for authentication
Overrides: object.__init__

__call__(self)
(Call operator)

source code 

usage:

def authentication(): return dict(form=auth())

define_tables(self, username=True, migrate=True, fake_migrate=True)

source code 

to be called unless tables are defined manually

usages: 
   # defines all needed tables and table files
   # 'myprefix_auth_user.table', ...
   auth.define_tables(migrate='myprefix_')

   # defines all needed tables without migration/table files
   auth.define_tables(migrate=False)

log_event(self, description, origin='auth')

source code 
usage: 
   auth.log_event(description='this happened', origin='auth')

get_or_create_user(self, keys)

source code  

Used for alternate login methods:
    If the user exists already then password is updated.
    If the user doesn't yet exist, then they are created.

login(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a login form

.. method:: Auth.login([next=DEFAULT [, onvalidation=DEFAULT
    [, onaccept=DEFAULT [, log=DEFAULT]]]])

logout(self, next=<function <lambda> at 0x26ba500>, onlogout=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

logout and redirects to login

.. method:: Auth.logout ([next=DEFAULT[, onlogout=DEFAULT[,
    log=DEFAULT]]])

register(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a registration form

.. method:: Auth.register([next=DEFAULT [, onvalidation=DEFAULT
    [, onaccept=DEFAULT [, log=DEFAULT]]]])

is_logged_in(self)

source code 
checks if the user is logged in and returns True/False. if so user is in auth.user as well as in session.auth.user

verify_email(self, next=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

action user to verify the registration email, XXXXXXXXXXXXXXXX

.. method:: Auth.verify_email([next=DEFAULT [, onvalidation=DEFAULT
    [, onaccept=DEFAULT [, log=DEFAULT]]]])

retrieve_username(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a form to retrieve the user username
(only if there is a username field)

.. method:: Auth.retrieve_username([next=DEFAULT
    [, onvalidation=DEFAULT [, onaccept=DEFAULT [, log=DEFAULT]]]])

reset_password_deprecated(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a form to reset the user password (deprecated)

.. method:: Auth.reset_password_deprecated([next=DEFAULT
    [, onvalidation=DEFAULT [, onaccept=DEFAULT [, log=DEFAULT]]]])

reset_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a form to reset the user password

.. method:: Auth.reset_password([next=DEFAULT
    [, onvalidation=DEFAULT [, onaccept=DEFAULT [, log=DEFAULT]]]])

request_reset_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a form to reset the user password

.. method:: Auth.reset_password([next=DEFAULT
    [, onvalidation=DEFAULT [, onaccept=DEFAULT [, log=DEFAULT]]]])

change_password(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a form that lets the user change password

.. method:: Auth.change_password([next=DEFAULT[, onvalidation=DEFAULT[,
    onaccept=DEFAULT[, log=DEFAULT]]]])

profile(self, next=<function <lambda> at 0x26ba500>, onvalidation=<function <lambda> at 0x26ba500>, onaccept=<function <lambda> at 0x26ba500>, log=<function <lambda> at 0x26ba500>)

source code  

returns a form that lets the user change his/her profile

.. method:: Auth.profile([next=DEFAULT [, onvalidation=DEFAULT
    [, onaccept=DEFAULT [, log=DEFAULT]]]])

impersonate(self, user_id=<function <lambda> at 0x26ba500>)

source code 

usage: POST TO http://..../impersonate request.post_vars.user_id=<id> set request.post_vars.user_id to 0 to restore original user.

requires impersonator is logged in and has_permission('impersonate', 'auth_user', user_id)

requires_membership(self, role=1, group_id=1)

source code 
decorator that prevents access to action if not logged in or if user logged in is not a member of group_id. If role is provided instead of group_id then the group_id is calculated.

requires_signature(self)

source code 
decorator that prevents access to action if not logged in or if user logged in is not a member of group_id. If role is provided instead of group_id then the group_id is calculated.

user_group(self, user_id=1)

source code 
returns the group_id of the group uniquely associated to this user i.e. role=user:[user_id]

accessible_query(self, name, table, user_id=1)

source code 

returns a query with all accessible records for user_id or the current logged in user this method does not work on GAE because uses JOIN and IN

example: 
  db(auth.accessible_query('read', db.mytable)).select(db.mytable.ALL)

Property Details [hide private]

user_id

user.id or None
Get Method:
web2py.gluon.tools.Auth._get_user_id(self) - accessor for auth.user_id
Set Method:
1
- PyMySQL: A pure-Python drop-in replacement for MySQLdb.
Delete Method:
1
- PyMySQL: A pure-Python drop-in replacement for MySQLdb.

   Home       Trees       Indices       Help   
web2py Web Framework
Generated by Epydoc 3.0beta1 on Thu Aug 4 00:47:01 2011 http://epydoc.sourceforge.net