Web2py - Access Control



Almost every application needs to be able to authenticate users and set permissions. web2py comes with an extensive and customizable role-based access control mechanism.web2py. It also supports the protocols, such as CAS, OpenID, OAuth 1.0, LDAP, PAM, X509, and many more.

web2py includes a mechanism known as Role Based Access Control mechanism (RBAC) which is an approach to restricting system access to authorized users. The web2py class that implements RBAC is called Auth.

Look at the schema given below.


Auth defines the following tables −

Sr.No Table Name & Description


stores users' name, email address, password, and status.



stores groups or roles for users in a many-to-many structure



Stores the information of links users and groups in a many-to-many structure



The table links groups and permissions.



logs changes in the other tables and successful access



It is used for Central Authentication Service

Customizing Auth

There are two ways to customize Auth.

  • To define a custom db.auth_user table from scratch.

  • Let web2py define the auth table.

Let us look at the last method of defining the auth table. In the db.py model, replace the following line −


Replace it with the following code −

auth.settings.extra_fields['auth_user'] = [
   Field('phone_number',requires = IS_MATCH('\d{3}\-\d{3}\-\d{4}')),

auth.define_tables(username = True)

The assumption is that each user consists of phone number, username and address.

auth.settings.extra_fields is a dictionary of extra fields. The key is the name of the auth table to which to add the extra fields. The value is a list of extra fields. Here, we have added two extra fields, phone_number and address.

username has to be treated in a special way, because it is involved in the authentication process, which is normally based on the email field. By passing the username argument to the following line, it is informed to web2py that we want the username field, and we want to use it for login instead of the email field. It acts like a primary key.

auth.define_tables(username = True)

The username is treated as a unique value. There may be cases when registration happens outside the normal registration form. It also happens so, that the new user is forced to login, to complete their registration.

This can be done using a dummy field, complete_registration that is set to False by default, and is set to True when they update their profile.

auth.settings.extra_fields['auth_user'] = [
   Field('phone_number',requires = IS_MATCH('\d{3}\-\d{3}\-\d{4}'),
   comment = "i.e. 123-123-1234"),
   Field('complete_registration',default = False,update = True,
   writable = False, readable = False)

auth.define_tables(username = True)

This scenario may intend the new users, upon login, to complete their registration.

In db.py, in the models folder, we can append the following code −

if auth.user and not auth.user.complete_registration:
if not (request.controller,request.function) == ('default','user'):

This will force the new users to edit their profile as per the requirements.


It is the process of granting some access or giving permission of something to the users.

In web2py once the new user is created or registered, a new group is created to contain the user. The role of the new user is conventionally termed as “user_[id]” where id is the unique identification of the user.

The default value for the creation of the new group is −

auth.settings.create_user_groups = "user_%(id)s"

The creation of the groups among the users can be disabled by −

auth.settings.create_user_groups = None

Creation, granting access to particular members and permissions can be achieved programmatically with the help of appadmin also.

Some of the implementations are listed as follows −

Sr.No Command & Usage

auth.add_group('role', 'description')

returns the id of the newly created group.



Deletes the group with the specified id



Deletes the user group with the given identification.



Returns the value of id of group uniquely associated for the given user.


auth.add_membership(group_id, user_id)

Returns the value of user_id for the given group_id


auth.del_membership(group_id, user_id)

Revokes access of the given member_id i.e. user_id from the given group.


auth.has_membership(group_id, user_id, role)

Checks whether user_id belongs to the given group.

Central Authentication Service (CAS)

web2py provides an industry standard namely, Client Authentication Service – CAS for both client and server built-in web2py. It is a third party authentication tool.

It is an open protocol for distributed authentication. The working of CAS is as follows −

  • If the user visits the website, the protocol checks whether the user is authenticated.

  • If the user is not authenticated to the application, the protocol redirects to the page where the user can register or log in to the application.

  • If the registration is completed, user receives an email. The registration is not complete until and unless user verifies the email.

  • After successful registration, the user is authenticated with the key, which is used by CAS appliance.

  • The key is used to get the credentials of user via HTTP request, which is set in the background.