Onegov User API

Models

class onegov.user.models.User(**kwargs)

Defines a generic user.

type

the type of the item, this can be used to create custom polymorphic subclasses of this class. See http://docs.sqlalchemy.org/en/improve_toc/ orm/extensions/declarative/inheritance.html.

property es_suggestion

Returns suggest-as-you-type value of the document. The field used for this property should also be indexed, or the suggestion will lead to nowhere.

If a single string is returned, the completion input equals the completion output. (My Title -> My Title)

If an array of strings is returned, all values are possible inputs and the first value is the output. (My Title/Title My -> My Title)

id

the user id is a uuid because that’s more secure (no id guessing)

username

the username may be any string, but will usually be an email address

password_hash

the password is stored with the hashing algorithm defined by onegov.core

role

the role is relevant for security in onegov.core

group_id

the group this user belongs to

realname

the real name of the user for display (use the name property to automatically get the name or the username)

data

extra data that may be stored with this user, the format and content of this data is defined by the consumer of onegov.user by default, this data is only loaded by request, so if you need to load a lot of data columns, do something like this:

session.query(User).options(undefer("data"))

second_factor

two-factor authentication schemes are enabled with this property if no two-factor auth is used, the value is NULL, if one is used, there should be a dictionary with the type of the two-factor authentication as well as custom values required by the two-factor implementation.

e.g.:

{
    'type': 'yubikey',
    'data': 'ccccccbcgujh'
}

Note that ‘data’ could also be a nested dictionary!

source

A user can technically come from changing providers - the source refers to the last provider he used.

source_id

A string describing the user id on the source, which is an id that is supposed never change (unlike the username, which may change).

If set, the source_id is unique per source.

active

true if the user is active

signup_token

the signup token used by the user

title

Returns the realname or the username of the user, depending on what’s available first.

password

An alias for password_hash.

is_matching_password(password)

Returns True if the given password (cleartext) matches the stored password hash.

classmethod get_initials(username, realname=None)

Takes the name and returns initials which are at most two characters wide.

Examples:

admin => A nathan.drake@example.org => ND Victor Sullivan => VS Charles Montgomery Burns => CB

property yubikey_serial

Returns the yubikey serial of the yubikey associated with this user (if any).

sessions = None

sessions of this user

tags = None

tags of this user

phone_number = None

the phone number of this user

cleanup_sessions(request)

Removes stored sessions not valid anymore.

save_current_session(request)

Stores the current browser session.

remove_current_session(request)

Removes the current browser session.

logout_all_sessions(request)

Terminates all open browser sessions.

class onegov.user.models.UserGroup(**kwargs)

Defines a generic user group.

type

the type of the item, this can be used to create custom polymorphic subclasses of this class. See http://docs.sqlalchemy.org/en/improve_toc/ orm/extensions/declarative/inheritance.html.

id

the id of the user group

name

the name of this group

Collections

class onegov.user.collections.UserCollection(session, **filters)

Manages a list of users.

Use it like this:

from onegov.user import UserCollection
users = UserCollection(session)

query()

Returns a query using onegov.user.models.User. With the current filters applied.

add(username, password, role, data=None, second_factor=None, active=True, realname=None, signup_token=None, group=None)

Add a user to the collection.

The arguments given to this function are the attributes of the User class with the same name.

property tags

All available tags.

property usernames

All available usernames.

usernames_by_tags(tags)

All usernames where the user’s tags match at least one tag from the given list.

exists(username)

Returns True if the given username exists.

This function does not actually load a user, so it is the quickest way to find out if a user exists. It should be used if you don’t care about finding out anything about the user.

by_id(id)

Returns the user by the internal id.

Use this if you need to refer to a user by path. Usernames are not the correct way, since they allow for user enumeration.

by_username(username)

Returns the user by username.

by_source_id(source, source_id)

Returns the user by source and source_id.

by_username_and_password(username, password)

Returns the user by username and password.

Note that although the password can be empty on the user, this function will not query for empty passwords as an added security measure.

Apart from that everything is fair game though, as it is not the job of onegov.user to enforce a password policy.

by_roles(role, *roles)

Queries the users by roles.

register(username, password, request, role='member', signup_token=None)

Registers a new user.

The so created user needs to activated with a token before it becomes active. Use the activation_token in the data dictionary together with the activate_with_token() function.

You probably want to use the provided RegistrationForm in conjunction with Auth as it includes a lot of extras like signup links and robots protection.

activate_with_token(username, token)

Activates the user if the given token matches the verification token stored in the data dictionary.

by_yubikey(token, active_only=True)

Returns the user with the given yubikey token.

Only considers active users by default.

delete(username)

Deletes the user if it exists.

If the user does not exist, an onegov.user.errors.UnknownUserError is raised.

class onegov.user.collections.UserGroupCollection(session, type='*')

Manages a list of user groups.

Use it like this:

from onegov.user import UserGroupCollection
groups = UserGroupCollection(session)

Commandline Interface

Provides commands used to manage users.

Examples:

To add a user called admin@example.org to the towns-govikon schema, with the role ‘admin’:

dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema add admin admin@example.org

This command will ask for a password if none was provided with --password.

To delete a user:

dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema delete admin@example.org

To check if a user exists:

dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema exists admin@example.org

To change a users password:

dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema change-password admin@example.org

This command will also ask for a password if none was provided with --password.

Forms

class onegov.user.forms.LoginForm(*args, **kwargs)

A generic login form for onegov.user

property login_data

Returns the data required to be passed to the onegov.user.auth.Auth methods.

class onegov.user.forms.PasswordResetForm(*args, **kwargs)

A generic password reset form for onegov.user.

update_password(request)

Updates the password using the form data (if permitted to do so).

Returns True if successful, False if not successful.

class onegov.user.forms.RegistrationForm(*args, **kwargs)

A generic registration form for onegov.user

class onegov.user.forms.RequestPasswordResetForm(*args, **kwargs)

A generic password reset request form for onegov.user.

class onegov.user.forms.SignupLinkForm(*args, **kwargs)

A form to generate signup links for specific roles.

class onegov.user.forms.UserGroupForm(*args, **kwargs)

A generic user group form for onegov.user

Errors

exception onegov.user.errors.OnegovUserError(message)

Base class for all errors raised by onegov.user.

exception onegov.user.errors.UnknownUserError(message)

Raised when a user was not found.

exception onegov.user.errors.InvalidActivationTokenError(message)

Raised when the given activation token doesn’t match.

exception onegov.user.errors.ExistingUserError(message)

Raised when a new user already exists.

exception onegov.user.errors.AlreadyActivatedError(message)

Raised when a user was already activated.

exception onegov.user.errors.ExpiredSignupLinkError

Raised when the signup link in use has expired.

exception onegov.user.errors.InsecurePasswordError

Raised when a user’s password is not secure enough.