Class Auth

auth=Auth(db)

- environment is there for legacy but unused (awful)
- db has to be the database where to create tables for authentication
- mailer=Mail(...) or None (no mailed) or True (make a mailer)
- hmac_key can be a hmac_key or hmac_key=Auth.get_or_create_key()
- controller (where is the user action?)
- cas_provider (delegate authentication to the URL, CAS2)

Overrides: object.__init__

usage:

to enable full record versioning (including auth tables):

auth = Auth(db) auth.define_tables(signature=True) # define our own tables db.define_table('mything',Field('name'),auth.signature) auth.enable_record_versioning(tables=db)

tables can be the db (all table) or a list of tables. only tables with modified_by and modified_on fiels (as created by auth.signature) will have versioning. Old record versions will be in table 'mything_archive' automatically defined.

when you enable enable_record_versioning, records are never deleted but marked with is_active=False.

enable_record_versioning enables a common_filter for every table that filters out records with is_active = False

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)

usage:

    auth.log_event(description='this happened', origin='auth')

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.

returns a login form

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

logout and redirects to login

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

returns a registration form

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

action user to verify the registration email, XXXXXXXXXXXXXXXX

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

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]]]])

returns a form to reset the user password (deprecated)

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

returns a form to reset the user password

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

returns a form to reset the user password

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

returns a form that lets the user change password

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

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

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

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

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)

If you have a table (db.mytable) that needs full revision history you can just do:

    form=crud.update(db.mytable,myrecord,onaccept=auth.archive)

or

    form=SQLFORM(db.mytable,myrecord).process(onaccept=auth.archive)

crud.archive will define a new table "mytable_archive" and store
a copy of the current record (if archive_current=True)
or a copy of the previous record (if archive_current=False)
in the newly created table including a reference
to the current record.

fields allows to specify extra fields that need to be archived.

If you want to access such table you need to define it yourself
in a model:

    db.define_table('mytable_archive',
        Field('current_record',db.mytable),
        db.mytable)

Notice such table includes all fields of db.mytable plus one: current_record.
crud.archive does not timestamp the stored record unless your original table
has a fields like:

    db.define_table(...,
        Field('saved_on','datetime',
             default=request.now,update=request.now,writable=False),
        Field('saved_by',auth.user,
             default=auth.user_id,update=auth.user_id,writable=False),

there is nothing special about these fields since they are filled before
the record is archived.

If you want to change the archive table name and the name of the reference field
you can do, for example:

    db.define_table('myhistory',
        Field('parent_record',db.mytable),
        db.mytable)

and use it as:

    form=crud.update(db.mytable,myrecord,
                     onaccept=lambda form:crud.archive(form,
                     archive_table=db.myhistory,
                     current_record='parent_record'))

default_settings

Value:

{'allow_basic_login': False, 'allow_basic_login_only': False, 'alternate_requires_registration': False, 'captcha': None, 'cas_maps': None, 'create_user_groups': 'user_%(id)s', 'email_case_sensitive': True, 'everybody_group_id': None, ...

default_messages

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(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
    ...

Value:

{'access_denied': 'Insufficient privileges', 'add_group_log': 'Group %(group_id)s created', 'add_membership_log': None, 'add_permission_log': None, 'change_password_log': 'User %(id)s Password changed', 'del_group_log': 'Group %(group_id)s deleted', 'del_membership_log': None, 'del_permission_log': None, ...

user_id

Get Method:

web2py.gluon.tools.Auth._get_user_id(self) - accessor for auth.user_id

Set Method:

threading.local()

Delete Method:

threading.local()