rattail.auth

Auth Handler

See also Auth Handler.

class rattail.auth.AuthHandler(config, **kwargs)

Base class and default implementation for the so-called “auth” handler, by which we mean “authentication and authorization”.

In practice this is also responsible for creating new users, and various things pertaining to roles, etc.

add_api_token(user, description, **kwargs)

Add a new API token for the user.

authenticate_user(session, username, password)

Authenticate the given user credentials, and if successful, return the user object.

Default logic will (try to) locate a user record with matching username, then confirm the supplied password is also a match.

You may of course define a custom handler and then could authenticate against anything you like, e.g. the POS system or LDAP etc. The only trick is that this must return a Rattail user, not some other kind. So you may have to devisde a way to auto-create the Rattail user as needed, when authentication for the external system succeeds.

Generally speaking the credentials passed in will have come directly from a user login attempt in the web app etc. Again the default logic assumes a “username” but in practice it may be an email address etc. - whatever the user types.

Parameters:

• session – Current session for Rattail DB.

• username – Username as string.

• password – Password as string.

Returns:

On success, a User instance; else None.

authenticate_user_token(session, token)

Authenticate the given user API token string, and if valid, return the corresponding User object.

delete_api_token(token, **kwargs)

Delete a new API token for the user.

delete_user(user, **kwargs)

Delete the given user account. Use with caution! As this generally cannot be undone.

Default behavior here is of course to delete the account, but it also must try to “remove” the user association from various places, in particular the continuum transactions table. Please note that this will leave certain record versions as appearing to be “without an author”.

Parameters:

user – Reference to a User to be deleted.

Returns:

Boolean indicating success.

Note that the utility of this method even having a return value is deemed questionable, so it’s possible in the future this may just return None on success, and raise an error to indicate failure.

generate_preferred_username(session, **kwargs)

Generate a “preferred” username using data from kwargs as hints.

Note that kwargs should be of the same sort that might be passed to the constructor for a new User instance.

So far there is only one “hint” which is honored by the default logic; however the intention is to leave this flexible as other kinds of hints may be useful in the future.

This method does not confirm if the username it generates is actually “available” for a new user. If you need confirmation then use generate_unique_username() instead.

Parameters:

• session – Current session for Rattail DB.

• person – Reference to a Person instance. If you specify this hint, then default logic will generate a username using first and last names, like 'first.last'. (You can override with a custom handler if needed.)

Returns:

Generated username as string.

generate_raw_api_token()

Generate a new raw API token string.

generate_unique_username(session, **kwargs)

Generate a unique username using data from kwargs as hints.

Note that kwargs should be of the same sort that might be passed to the constructor for a new User instance.

This method is a convenience which does two things:

First it calls generate_preferred_username() to obtain the “preferred” username. (It passes kwargs along when it makes the call. See generate_preferred_username() for more info.)

Then it checks to see if the resulting username is already taken. If it is, then a “counter” is appended to the username, and incremented until a username can be found which is not yet taken.

It returns the first “available” (hence unique) username which is found. Note that it is considered unique and therefore available at the time; however this method does not “reserve” the username in any way. It is assumed that you would create the user yourself once you have the username.

Parameters:

session – Current session for Rattail DB.

Returns:

Username as string.

get_email_address(user, **kwargs)

Get the “best” email address we have on file for the given user.

get_merge_preview_data(user, **kwargs)

Must return a data dictionary for the given object, which can be presented to the user during a merge preview.

get_merge_preview_fields(**kwargs)

Returns a sequence of fields which will be used during a merge preview.

get_merge_resulting_data(removing, keeping, **kwargs)

Must return a dictionary to represent what the final data would look like, should the proposed merge occur. Note that we’re still in preview mode here, this doesn’t actually cause any particular data to become final.

Parameters:

• removing – Data dictionary for the object to be removed, as obtained via get_merge_preview_data().

• keeping – Data dictionary for the object to be preserved, as obtained via get_merge_preview_data().

get_permissions(session, principal, include_guest=True, include_authenticated=True)

Return a set of permission names, which represents all permissions effectively granted to the given user or role.

Parameters:

• session – Current session for Rattail DB.

• principal – Either a User or Role instance. It is also expected that this may sometimes be None, in which case the “Guest” role will typically be assumed.

• include_guest – Whether or not the “Guest” role should be included when checking permissions. If False, then Guest’s permissions will not be consulted.

• include_authenticated – Whether or not the “Authenticated” role should be included when checking permissions.

Returns:

Set of permission names.

get_short_display_name(user, **kwargs)

Returns “short display name” for the user. This is for convenience of mobile view, at least…

get_user(obj, **kwargs)

Return the User associated with the given object, if any.

grant_permission(role, permission)

Grant a permission to the role. If the role already has the permission, nothing is done.

Parameters:

• role – A Role instance.

• permission – Name of the permission as string.

has_permission(session, principal, permission, include_guest=True, include_authenticated=True)

Check if the given user or role has been granted the given permission.

Parameters:

• session – Current session for Rattail DB.

• principal – Either a User or Role instance. It is also expected that this may sometimes be None, in which case the “Guest” role will typically be assumed.

• permission – Name of the permission for which to check.

• include_guest – Whether or not the “Guest” role should be included when checking permissions. If False, then Guest’s permissions will not be consulted.

• include_authenticated – Whether or not the “Authenticated” role should be included when checking permissions.

Returns:

Boolean indicating if the permission has been granted.

make_user(session=None, **kwargs)

Make and return a new user.

This is mostly just a simple wrapper around the normal User constructor. All kwargs for instance are passed on to the constructor.

Default logic here only adds one other convenience:

If there is no username specified in the kwargs then it will call generate_unique_username() to automatically provide a username. Note that all kwargs are passed along in that call.

Parameters:

session – Current session for the Rattail DB. This is “sort of” optional, but please do provide it, as it may become requied in the future.

Returns:

A new User instance.

merge_update_keeping_object(removing, keeping)

Update the object to be kept, with any relevant data from the object to be removed, in the context of a merge.

remove_user_from_continuum_transactions(user)

Remove the given user from all Continuum transactions, i.e. all data versioning tables.

You probably will not need to invoke this directly; it is invoked as needed from within delete_user().

Parameters:

user – A User instance which should be purged from the versioning tables.

revoke_permission(role, permission)

Revoke a permission from the role. If the role does not have the permission, nothing is done.

Parameters:

• role – A Role instance.

• permission – Name of the permission as string.

why_not_merge(removing, keeping, **kwargs)

Evaluate the given merge candidates and if there is a reason not to merge them, return that reason.

Parameters:

• removing – Object which will be removed, should the merge happen.

• keeping – Object which will be kept, should the merge happen.

Returns:

String indicating reason not to merge, or None.