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:

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

Navbar with support for more templates This uses some code from the old navbar.

Keyword arguments: mode -- see options for list of

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

Important: If you use auth.enable_record_versioning, do not use auth.archive or you will end up with duplicates. auth.archive does explicitly what enable_record_versioning does automatically.

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.

perform basic login.

:param basic_auth_realm: optional basic http authentication realm. :type basic_auth_realm: str or unicode or function or callable or boolean.

reads current.request.env.http_authorization and returns basic_allowed,basic_accepted,user.

if basic_auth_realm is defined is a callable it's return value is used to set the basic authentication realm, if it's a string its content is used instead. Otherwise basic authentication realm is set to the application name. If basic_auth_realm is None or False (the default) the behavior is to skip sending any challenge.

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

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

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.

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

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.

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.

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

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, 'allow_delete_accounts': False, 'alternate_requires_registration': False, 'auth_manager_role': None, 'captcha': None, 'cas_maps': None, 'client_side': True, ...

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

user.id or None

Get Method:

_get_user_id(self) - accessor for auth.user_id