Onegov User API


class onegov.user.models.RoleMapping(**kwargs)[source]

Defines a generic role mapping between user and/or group and any other model (content).

The model does not define the relationship to the content. Instead, the realtionship should be defined in the content model when needed:

role_mappings = relationship(
        "foreign(RoleMapping.content_id) == cast(, TEXT),"
        "RoleMapping.content_type == 'my_models'"

the type of the item, this can be used to create custom polymorphic subclasses of this class. See orm/extensions/declarative/inheritance.html.


the id of the role mapping


the role is relevant for security in onegov.core


the group this mapping belongs to


the user this mapping belongs to


the content this mapping belongs to


the content type (table name) this mapping belongs to

class onegov.user.models.User(**kwargs)[source]

Defines a generic user.


the type of the item, this can be used to create custom polymorphic subclasses of this class. See 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)


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


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


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


the role is relevant for security in onegov.core


the group this user belongs to


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


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:


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.


    'type': 'yubikey',
    'data': 'ccccccbcgujh'

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


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


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.


true if the user is active


the signup token used by the user


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


An alias for password_hash.


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

classmethod get_initials(username, realname=None)[source]

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


admin => A => 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


Removes stored sessions not valid anymore.


Stores the current browser session.


Removes the current browser session.


Terminates all open browser sessions.

class onegov.user.models.UserGroup(**kwargs)[source]

Defines a generic user group.


the type of the item, this can be used to create custom polymorphic subclasses of this class. See orm/extensions/declarative/inheritance.html.


the id of the user group


the name of this group


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

Manages a list of users.

Use it like this:

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

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

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 sources

All available sources.

property usernames

All available usernames.


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


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.


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.


Returns the user by username.

by_source_id(source, source_id)[source]

Returns the user by source and source_id.

by_username_and_password(username, password)[source]

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

Queries the users by roles.

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

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

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

by_yubikey(token, active_only=True)[source]

Returns the user with the given yubikey token.

Only considers active users by default.


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='*')[source]

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.


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

onegov-user --dsn $dsn --schema $schema add admin

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

To delete a user:

onegov-user --dsn $dsn --schema $schema delete

To check if a user exists:

onegov-user --dsn $dsn --schema $schema exists

To change a users password:

onegov-user --dsn $dsn --schema $schema change-password

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


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

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

A generic password reset form for onegov.user.


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

A generic registration form for onegov.user

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

A generic password reset request form for onegov.user.

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

A form to generate signup links for specific roles.

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

A generic user group form for onegov.user


exception onegov.user.errors.OnegovUserError(message)[source]

Base class for all errors raised by onegov.user.

exception onegov.user.errors.UnknownUserError(message)[source]

Raised when a user was not found.

exception onegov.user.errors.InvalidActivationTokenError(message)[source]

Raised when the given activation token doesn’t match.

exception onegov.user.errors.ExistingUserError(message)[source]

Raised when a new user already exists.

exception onegov.user.errors.AlreadyActivatedError(message)[source]

Raised when a user was already activated.

exception onegov.user.errors.ExpiredSignupLinkError[source]

Raised when the signup link in use has expired.

exception onegov.user.errors.InsecurePasswordError[source]

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