Usermanagement

Easydb session management

In order to work with the Easydb, the first requirement is to have a session. For most calls, the session has to be authenticated. The authenticated user may be requested to confirm some messages before having full access to the API.

These are the states of a client from the point of view of Easydb:

1. No session

A client without session can only call this method:

• GET /api/session creates a session and returns it to the client, containing a session identifier (token) and the allowed authentication methods, along with other information.

This method is in fact always allowed. A client may use different sessions. Other calls require the provided token to identify the session.

Trying to call another method without a token will result in a Not Authenticated error.

2. Unauthenticated session

If the client’s session is not authenticated, little interaction with the server is allowed:

• POST /api/session/authenticate authenticates the session. This attaches a user to the session.
• POST /api/session/deauthenticate is allowed, although it does nothing.
• POST /api/session/forgot_password: see “Login” below
• POST /api/session/task: see “E-mail management” and “Login” below

Trying to call another method with an unauthenticated token will result in a Not Authenticated error.

After authenticating, the server checks whether the associated user has pending tasks. Depending on this information, the client will be in state (3) or (4).

3. User with pending tasks

If the user has pending tasks, they can be confirmed using:

• POST /api/session/messages_confirm

The methods from state (2) are allowed as well.

Trying to call another method will result in a Tasks Not Confirmed error.

4. User ready

In this state, all API methods are allowed, provided the user has the required rights. See the “Permissions” section in each call and the general description about rights management.

Login

Standard login (“easydb”)

Users can login using either their login or an email address:

• in order to use the login name for authentication, it must be set; this is never true for “email” users
• in order to use an e-mail address for authentication, it must be active and enabled for use_for_login (see below “E-mail management”)
• the administrator can deactivate login altogether using the login_disabled flag
• the administrator can enable login between two tmiestamps: login_valid_from (inclusive) and login_valid_to (exclusive)

In order to login, the user needs a password. If there is no active password yet or if the administrator specifically required the user to change the password (require_password_change flag), an e-mail will be sent to the user with a link containing the required information to perform a POST /api/session/set_password API call.

The administrator can also set directly a password for a user: this password can be provided directly or generated by the server (_password attribute). Depending on the e-mail setting send_email_include_password, the password will be directly mailed to the user, or an e-mail will be sent, so that the user calls the administrator.

The authentication is performed using POST /api/session/authenticate?method=easydb.

If the user forgets the password, [POST /api/session/forgot_password] can be used to reset it. This only works if the administrator has allowed it in the Base Configuration (system.login.forgotten_password_process). An e-mail is sent to the user with a link containing the required information to call POST /api/session/authenticate?method=task.

Single Sign-On (“sso”)

…

Anonymous access (“anonymous”)

…

Shared collection access (“email” and “collection”)

…

Keep logged in with cookie (“easydb_cookie”)

…

E-mail management

Users have a list of e-mail addresses. An address can be active or inactive. One of the active addresses can be chosen as “primary”.

Active vs. inactive

Inactive e-mails require a confirmation by the user. There are two ways of generating an inactive e-mail address:

• the user may call POST /api/user and pass a _new_primary_email (this e-mail is marked as intended_primary
• an administrator may call POST /api/user and add a new e-mail address to _emails and set needs_confirmation

Either way, a message will be sent to the user requesting confirmation. The e-mail contains the required information to call POST /api/session/authenticate?method=task. Upon successful completion of the confirmation process, the e-mail will become active.

It is also possible to create an active e-mail directly using _emails (needs_confirmation set to false), and it is also possible to revert the active status of an e-mail by setting needs_confirmation to true.

The confirmation request e-mail is resent in the following cases:

• POST /api/user from administrator when e-mails are pending confirmation
• POST /api/user _new_primary_email from user when the provided e-mail is an unconfirmed e-mail
• POST /api/session/forgot_password when the provided identifier is an unconfirmed e-mail

The confirmation codes have a certain expiration date, after which e-mails are deleted.

A requested confirmation for an email address can be cancelled by setting the write-only parameter cancel_confirmation to true. This overrules needs_confirmation.

Primary e-mail

One e-mail can be chosen as primary e-mail. This is the visible e-mail for the user. The user can set the primary e-mail using POST /api/user _new_primary_email. If the e-mail exists and is active, it will be set to be the primary; if it exists and is inactive, it will be marked to become primary when confirmed.

The administrator can change these parameters directly (is_primary, intended_primary).

When using the _new_primary_email option, the E-Mail attributes (see below) are copied from the old primary e-mail. If there is no primary e-mail, they are set as follows:

• use_for_login: true if the user is new (that includes users created using “register”)
• use_for_email: true
• send_email: true
• send_email_include_password: false
• send_email_welcome_now: false

E-mail attributes

• use_for_login is a flag that indicates whether an e-mail can be used as identifier for login purposes (see above “Login”)
• use_for_email is a flag that indicates whether the e-mail address is used when sending digest e-mails
• send_email is a flag that indicates whether an e-mail should be sent to this address to inform the user of changes relating to its account
• send_email_include_password controls whether the update e-mails may include a plain password
• send_email_welcome_now send a welcome e-mail to this address right after saving. the flag will then be set to false. this option can be used repeatedly to send another welcome e-mail later.

Sending e-mails

There are different kinds of e-mails:

Profile e-mails

These e-mails are sent to the primary e-mail address, if set:

• send password: triggered by an administrator who sets a password for a user, only sent if send_email_include_password is set
• forgot password: triggered by user

Confirmation e-mails

These e-mails are sent to the e-mail address that requires confirmation

User management e-mails

These e-mails are sent to all e-mail addresses that are send_email:

• login disabled: triggered by administrator
• require password change: triggered by administrator
• welcome new user: on user creation
• updated self service: triggered by user
• updated record: triggered by administrator

Action e-mails

These e-mails are sent to the all e-mail addresses that are use_for_email:

• export
• transition