DE EN EN (Google)

User

The user is the central entity for security management. It defines the authentication method (currently login+password) and keeps track of its status. Users can belong to several groups. Users and groups can be granted permissions using access control lists.

Easydb creates automatically system and anonymous users. See below for a description.

There are different formats to present a user: full, short and contact.

Full format

This format is used by /api/user and contains all attributes that can be set for a user.

Name Description
_basetype Name of the base type (string, r): user
_owner Owner of this user (group (short) or user (short), rw): see below
_acl ACL (array of acl entries, rw, optional)
_system_rights System rights (rights specification, rw, optional)
_groups Groups this user belongs to (array of groups (short), r)
_has_acl Whether this user has a non-empty ACL (boolean, r)
_password Password for login (string, true or false, optional, w). When true a new password is generated and send by email, when false the current password is archived (disabled).
_password_insecure_hash Password hash to be used for authentication (string, w). Format depends on hash method used (_password_insecure_hash_method). It is strongly recommended to use it only for migration and in conjunction with require_password_change (see below). This value can be read by requesting the password hash for user explicitely (see “Returning password hashes”)
_password_insecure_hash_method hash method of the password hash supplied by _password_insecure_hash (string, w), mandatory if _password_insecure_hash is used. Currently only “md5” is supported, the password hash has to be the hexadecimal, lowercase representation of an MD5 hash, e.g. 1a79a4d60de6718e8e5b326e338ae533. It is discouraged to use these methods for other reasons than migrating passwords from easydb version 4.
_password_insecure_hash_salt salt value used for password hashing. It depends on the hash method whether this value is present, also see “Returning password hashes” for more information.
_generated_rights Rights that the session user has for the user (rights specification): read, write, delete
_collection_pin_codes List of stored collection PIN codes (see below)
user User attributes:
↦ _id User ID (integer, unique, r*)
↦ lookup:_id Lookup for user ID
↦ _version User version (integer, rw)
↦ _generated_displayname Name to display for this user (string, r): see below
↦ type User type (string, rw): see below
↦ login_disabled Whether the authentication method “easydb” is disabled for the user (boolean, optional, rw): defaults to false
↦ login_valid_from If set, the authentication method “easydb” is only valid from this timestamp on, inclusively (timestamp, optional, rw)
↦ login_valid_to If set, the authentication method “easydb” is only valid until this timestamp, exclusively (timestamp, optional, rw)
↦ login Username for login (string, unique, optional, rw): unique if set
↦ first_name First name (string, optional, rw)
↦ last_name Last name (string, optional, rw)
↦ displayname Displayname (string, rw)
↦ remarks Remarks (string, rw)
↦ frontend_language Frontend language (string, rw): language to be used when applying l10n to the frontend: defaults to the first frontend language
↦ database_languages Database languages (array of strings, rw, nullable): subset of backend languages to be considered for the user (*)
↦ search_languages Search languages (array of strings, rw, nullable): subset of backend languages to be used by search (*)
↦ picture User avatar (Asset, optional, rw)
↦ frontend_prefs Extra properties that the frontend can set and retrieve (object, optional, rw)
↦ company Company (string, optional, rw)
↦ department Department (string, optional, rw)
↦ phone Phone (string, optional, rw)
↦ street Street (string, optional, rw)
↦ house_number House number (string, optional, rw)
↦ address_supplement Address supplement (string, optional, rw)
↦ postal_code Postal code (string, optional, rw)
↦ town Town or city (string, optional, rw)
↦ country Country (string, optional, rw)
↦ mail_schedule Mail schedule preferences for the user (schedule, optional, rw): defaults to {} (once a day)
↦ _primary_email User primary e-mail (string, optional, r)
↦ _new_primary_email New primary e-mail requested (string, optional, rw)
↦ require_password_change user is requested to change or set his password by a pending task the next time he logs in (bool, optional, rw)
↦ created_timestamp timestamp of creation of this user (timestamp, r)
↦ last_updated_timestamp timestamp of the last update of this user (timestamp, r)
_emails list of email addresses, each of them may contain the following attributes:
↦ email actual email address (string, rw)
↦ needs_confirmation request email address to get confirmed by sending out an email (true, optional, rw)
↦ cancel_confirmation cancel a previous confirmation request (true, optional, w)
↦ send_email_include_password When set to true, an email is sent to user containing the generated password. (boolean, optional, rw, default false)
↦ requested_confirmation_date date of confirmation request sent by email (date, r)
↦ confirmed_date date of email confirmation (date, r)
↦ use_for_login use this email address for login (identification of user; boolean, rw, default false)
↦ use_for_email use this email address for sending informational emails (boolean, rw, default false)
↦ send_email send emails to this address (boolean, rw, default true)
↦ send_email_include_password include plain text passwords when sending emails to this address (if applicable; boolean, rw, default true)
↦ is_primary whether this is the current primary e-mail (bool, rw)
↦ intended_primary whether this e-mail is intended as the new primary e-mail (bool, rw)
↦ reference User reference (string, unique, optional, rw): can be used for lookups for _id
↦ shortname User short name (string, unique, optional, rw): can be used for lookups for _id

Remarks:

Collection PINs

Each user stores a list of collection PINs to access protected collections. When the user tries to access the protected collections, the server checks if the user has the correct pin for this collection.

The collection PINs are stored in an array at _collection_pin_codes, where each element has the following structure:

{
    "collection_id": 1,
    "pin_code": "1234"
}

The collection is identified by the collection_id and the pin_code is a string that saves the PIN code that was saved for the collection.

Search format

This format is returned when searching users. The column “Search” specifies the search type that can be used (see /api/search).

Name Description Search
_basetype
_groups
↦ group
↦ ↦ _id Number
user
↦ _generated_displayname Text
↦ _id Number
↦ _version Number
↦ type NotAnalyzed
↦ login String (all)
↦ last_name Text (all)
↦ first_name Text (all)
↦ company Text (all)
↦ department Text (all)
↦ street Text (all)
↦ address_supplement Text (all)
↦ postal_code Text (all)
↦ town Text (all)
↦ country Text (all)
↦ displayname Text (all)
↦ phone String (all)
↦ house_number String (all)
↦ _primary_email String (only in all)
↦ created_timestamp Timestamp
↦ last_updated_timestamp Timestamp

Short format

This is a short format that is used when specifying users inside other types (i.e. “who” in ACL entries). For fields that are already present in the full format a description is not provided.

Name Description
_basetype
_groups
↦ group
↦ ↦ _id
user
↦ _generated_displayname
↦ _id
↦ _version
↦ type
↦ login
↦ _primary_email
↦ frontend_language writable when creating ad-hoc users

When creating an ad-hoc user inside a collection ACL, the _id is not provided; the type is set to the kind of user and the login contains the e-mail or secret (depending on the user type).

Contact format

This format is used when retrieving a pool or objecttype contact. If the attribute referencing this user is marked as writable, user._id is writable. The other fields are readable-only.

It contains the same attributes as “short”, plus:

Name
_basetype
user
↦ first_name
↦ last_name
↦ company
↦ department
↦ phone

Session format

This format is used inside the session object. It contains the same attributes as “short” plus the following, providing the user has the corresponding system.user.write_self right:

The session format also includes:

User types

There are different kinds of users: regular users (type “easydb”) are created by users with the required authorization; system users (type “system”) are provided by the system. The other types are created ad-hoc during different interactions with the system.

Type Creation Comments
easydb PUT /api/user regular users
easydb_self_register PUT /api/user users created via system.user.create_new when this type is selected
system automatically created on system start-up only the following attributes can be modified: login, _acl, _system_rights and _groups
anonymous POST /api/session/authenticate with authentication type “anonymous” cannot be modified
email POST /api/collection with an ACL containing an “email” user cannot be modified
collection POST /api/collection with an ACL containing a “collection” user cannot be modified
sso GET /api/session/sso/authenticate when the user does not already exist
custom-{custom_type} PUT /api/user with “create_new” and custom type custom type

There is currently only one system user: root.

Users of type “email” and “collection” belong in the system group “:collection”.

Currently, only the following type conversions are allowed:

Owner

The user always has an owner. On creation, it is set automatically by the server to the user’s creator, but the API won’t complain if it is explicitly set. It will return an error if it is set to something different. The owner cannot be set to null but can always be left out, meaning that it should not be changed.

System users have the system user “root” as owner.

Generated display name

from one of the following sources: