wuttjamaican.auth

Auth Handler

This defines the default auth handler.

class wuttjamaican.auth.AuthHandler(config)

Base class and default implementation for the auth handler.

This is responsible for “authentication and authorization” - for instance:

• authenticate user from login credentials

• check which permissions a user/role has

• create/modify users, roles

• grant/revoke role permissions

add_api_token(user, description)

Add and return a new API token for the user.

This calls generate_api_token_string() to obtain the actual token string.

See also delete_api_token().

Parameters:

• user – User instance for which to add the token.

• description – String description for the token.

Return type:

UserAPIToken

authenticate_user(session, username, password)

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

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

Custom handlers can authenticate against anything else, using the given credentials. But they still must return a “native” User object for the app to consider the authentication successful. The handler may auto-create the user if needed.

Generally speaking the credentials 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 entered.

See also authenticate_user_token().

Parameters:

• session – Open db session.

• username – Usually a string, but also may be a User instance, in which case no user lookup will occur. (However the user is still authenticated otherwise, i.e. the password must be correct etc.)

• password – Password as string.

Returns:

User instance, or None.

authenticate_user_token(session, token)

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

See also authenticate_user().

Parameters:

• session – Open db session.

• token – Raw token string for the user.

Returns:

User instance, or None.

check_user_password(user, password)

Check a user’s password.

This will hash the given password and compare it to the hashed password we have on file for the given user account.

This is normally part of the login process, so the password param refers to the password entered by a user; this method will determine if it was correct.

Parameters:

• user – User instance.

• password – User-entered password in plain text.

Returns:

True if password matches; else False.

delete_api_token(token)

Delete the given API token.

See also add_api_token().

Parameters:

token – UserAPIToken instance.

delete_user(user)

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

Default behavior simply deletes the user account. Depending on the DB schema and data present, this may cause an error (i.e. if the user is still referenced by other tables).

Parameters:

user – User to delete.

generate_api_token_string()

Generate a new raw API token string.

This is called by add_api_token().

Returns:

Raw API token string.

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

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

Parameters:

• session – Open db session.

• principal – User or Role instance. Can also be None, in which case the “Anonymous” role will be assumed.

• include_anonymous – Whether the “Anonymous” role should be included when checking permissions. If False, the Anonymous permissions will not be checked.

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

Returns:

Set of permission names.

Return type:

set

get_role(session, key)

Locate and return a Role per the given key, if possible.

Parameters:

• session – Open db session.

• key – Value to use when searching for the role. Can be a UUID or name of a role.

Returns:

Role instance; or None.

get_role_administrator(session)

Returns the special “Administrator” role.

get_role_anonymous(session)

Returns the special “Anonymous” (aka. “Guest”) role.

get_role_authenticated(session)

Returns the special “Authenticated” role.

get_user(obj, session=None)

Return the User associated with the given object, if one can be found.

This method should accept “any” type of obj and inspect it to determine if/how a user can be found. It should return the “first, most obvious” user in the event that the given object is associated with multiple users.

For instance obj may be a string in which case a lookup may be tried on username. Or it may be a Person in which case their user may be returned.

Parameters:

• obj – Object for which user should be returned.

• session – Open db session. This is optional in some cases, i.e. one can be determined automatically if obj is some kind of object already contained in a session (e.g. Person). But a session must be provided if obj is a simple string and you need to do a lookup by username etc.

Returns:

User or None.

grant_permission(role, permission)

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

Parameters:

• role – Role instance.

• permission – Name of the permission as string.

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

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

Note

While this method is perfectly usable, it is a bit “heavy” if you need to make multiple permission checks for the same user. To optimize, call get_permissions() and keep the result, then instead of calling has_permission() just check if a given permission is contained in the cached result set.

(The logic just described is exactly what this method does, except it will not keep the result set, hence calling it multiple times for same user is not optimal.)

Parameters:

• session – Open db session.

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

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

• include_anonymous – Whether the “Anonymous” role should be included when checking permissions. If False, then Anonymous permissions will not be checked.

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

Returns:

Boolean indicating if the permission is granted.

make_person(**kwargs)

Make and return a new Person.

This is a convenience wrapper around make_person().

make_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 User constructor.

So far this logic is rather simple:

If kwargs contains person then a username will be constructed using the name data from the person (e.g. 'john.doe').

In all other cases it will return 'newuser'.

Note

This method does not confirm if the username it generates is actually “available” for a new user. See make_unique_username() for that.

Parameters:

session – Open db session.

Returns:

Generated username as string.

make_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 User constructor.

This method is a convenience which does two things:

First it calls make_preferred_username() to obtain the “preferred” username. (It passes all kwargs along when it makes that call.)

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 – Open db session.

Returns:

Username as string.

make_user(session=None, **kwargs)

Make and return a new User.

This is mostly a simple wrapper around the User constructor. All kwargs are passed on to the constructor as-is, for instance. It also will add the user to the session, if applicable.

This method also adds one other convenience:

If there is no username specified in the kwargs then it will call make_unique_username() to automatically provide one. (Note that the kwargs will be passed along to that call as well.)

Parameters:

session – Open db session, if applicable.

Returns:

The new User instance.

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.

set_user_password(user, password)

Set a user’s password.

This will update the password attribute for the user. The value will be hashed using bcrypt.

Parameters:

• user – User instance.

• password – New password in plain text.

user_is_admin(user)

Check if given user is a member of the “Administrator” role.

Return type:

bool