User management

Heads up! These docs are for Portofino 3, which is a legacy product. Check out Portofino 4!

Purpose

User management is important in public and enterprise information systems. It allows:

the authentication of users through a login screen
password changes
administrative functions to add/remove users and manage their associations to user groups.
single sign-on and centralized user management (LDAP, etc). See chapter Single sign-on for more details on this.

ManyDesigns Portofino's basic configuration has user management switched off. This means that, when you start, there is no authentication and any user who knows the system's url can access it. This situation is desirable only in the very early stages of development. Very soon you will want to have user management in your system not only for security reasons but also for features such as roles and responsibilities within workflows, notifications, personalized portlets, etc.

Furthermore, since version 3.0 Portofino has an advanced new architecture for user management that introduces:

Encrypted password through SHA-1 algorithm
User account state
Password reset
Password expiration
Password recovery
Inactive account management
Self registration
e-mail verification
email bounce check

1 Purpose
2 Creating the user data model
3 Email messaging
4 User life cycle
5 Configuration
6 User management use cases
7 Changing the user model for languages other than English
8 Enabling user management for the upstairs level

Creating the user data model

Before you can let user log onto your systems, you need to create some classes for the user management. Portofino let you to create your owns but, you can simply click on the Meta user groups tab, then on thecreate user model link and Portofino will create the following classes and set the necessary permissions :

User
This class manage users accounts.

Attributes:

login
password
email
creation date
last login date
last pwd change date
must change pwd
failed attempts
state
token
bouncing

UserGrp
This class manage User groups.
Attributes:

name

User_UserGrp
This class manage the association between users and groups
Attributes:

user
user group

EmailQueue
This class is used to store emails sent by the application.
Attributes:

subject
body
addressee
sender
date
state

oldPwd
This class stores the user old passwords (crypted) to avoid users the reuse of the sames.
Attributes:

date
password
user

Email messaging

Since 3.0, User Management is strongly integrated with email messaging. Portofino uses emails to:

send system generated passwords
verify email addresses provided in self registration
manage password recovery

The Portofino messaging architecture is aware of bounce messages. A bounce is an automated message from an email system informing the sender of another message about a delivery problem. Often this is due to misspelled addresses, full mailboxes or spam filters (read more on wikipedia). In this cases, Portofino warns the user, after a login, that it has problems in sending emails to his address.

User life cycle

A user has a workflow associated trough the attribute state. The workflow is showed in the following picture.

The workflow states are explained below.

Registered

After a self registration a user is in the "registered" state. This user cannot still log in. Before, he has to verify his email address, and, if required, he needs the administrator approval.

Verified

This state is for self registered users, that verified their email address and still need administrator approval.

Active

This state is for active users that can log into Portofino. Users created by administrators begin from this state. Self registered users arrive in this state after an email verification (if self registration is not moderated) or activated by an administrator.

Suspended

User are in the "suspended" state for :

log in failures
a too long inactive period

Suspended users can be activated again from administrators.

Banned

This state is for users banned by administrators from Portofino. Users banned cannot log in anymore.

Deleted

This state is for users deleted from Portofino

Configuration

Enabling user management parameters

Once you've create the user data model, you still have to tell the system to use it.
Locate the portofino-custom.propeties file you used during the installation. Then add or edit the following line:

model.users.enabled=true

As an optional configuration you may want to disable anonymous access o the system:

model.users.anonymous.enabled=false

This will force users to log onto the system before they can start using it.

Save the file, then restart the application server to make the changes effective.

Security parameters

This set of parameters is used to configure the desired level of security for accounts, passwords and registration.

model.users.pwd.expiry.days
Number of days after that password expires and the user have to change it. Default: passwords without end.

model.users.pwd.minlength
The minimum length of the passwords. Default: 6 characters.

model.users.pwd.inactivity.maxdays
Number of days without login afterwards the user is suspended and need to be activated by a user administrator. Default: infinite inactivity period.

model.users.pwd.attempts.maxnumber
Max number of failed attempts for login, with a further attempt, user is suspended and need to be activated by a user administrator. Default: infinite attempts.

model.users.pwd.keep.old.number
Count of store old passwords. In this way, passwords cannot be reused too frequently. Default: no old password is stored.

model.users.registration.auto.enabled
Self registration enabled. Default: false.

model.users.registration.moderated.enabled
A self registrated user needs the administrator approval before he can log in.

Email parameters

This set of parameters configures the properties for sending and receiving emails.

mail.sender
The email address of the sender

mail.pop3.host
Pop3 mail server host name, this property is needed for checking email bouncing.

mail.pop3.port
Pop3 mail server port. Default: 110.

mail.pop3.login
Login for pop3.

mail.pop3.password
Password for pop3.

mail.pop3.ssl.enabled
enable SSL

mail.smtp.host 

		Smtp mail server host name, this property is

mandatory

 for sending emails (e.g. password generation, forgotten passwords, email verification). 

		

		mail.smtp.port 

		Smtp mail server port. Default: 25. 

		

		mail.smtp.login 

		Login for smtp. 

		

		mail.smtp.password 

		Password for smtp.

mail.smtp.ssl.enabled
enable SSL

model.mail.bounce.enabled
Check email bounce.

User management use cases

The following picture shows all the possible use cases for User and User Administrators. In the next paragraphs, the most important ones are detailed.

Creating a user

Go downstairs. If you have already enabled user management, log on to the system as a member of theUser Administrators group. If you have followed the standard procedure described above, log in as admin(password: admin).

Click on the Users tab, then on the create link. Enter the new user's details as required: login and email. Click on the Create button to save.

If you have enabled email parameters, an email will be send to the user with his passwords, otherwise you can reset the user password and read the system generated.
Creating a user automatically associate him to the User group.

Reset user password

Go downstairs. As a "User Administrator", click on the Users tab and select the desired user. Click on "Reset Password" button. If you have enabled email parameters, an email will be send to the user with his new password, otherwise you can read the system generated.

Self Registration

Go downstairs. Click on "Self Registration" in the login page. Now you have to compile all the required fields from the "User" class. After the registration an email will be sent to your address to confirm your registration. If registration is moderated you will need the administration approval.

Password recovery

Go downstairs. Click on "Forgotten password" in the login page. Now you have to insert your email and confirm. A mail with the instruction to reset your password will be sent to your email address.

Creating a user group

Go upstairs. Click on the Meta user groups tab, then on the create link. In the form, enter the group's name and click on the Create button to save. When you do this, two things happen:

upstairs, a meta user group is created (you have just done this);
downstairs, a user group is created (Portofino does this automatically for you).

Notice that Portofino keeps the meta user groups upstairs in sync with the user group downstairs. Whatever you do to one (create, update, delete) is reflected on the other.

Associating a user to a user group

Go downstairs. Click on the Users tab, then select the user you want to associate. In its details page, locate the Belongs to user groups section and click on the Connect to user groups. In the form, select the a group from the pick list. Finally click on the Create button.

Changing the user model for languages other than English

You may have noticed that the user model requires a number of classes and attributes that use English names. This may be a problem if English is not the target language of your system. You can change the user model to fit your language, but keep these two rules in mind:

The name of classes and attributes must be strictly as specified in the section Creating the user model, i.e., with the English names.
The pretty name and pretty plural of classes and attributes (as well as the opposite end name of relationship attributes) can be anything you like in the language you want.

Enabling user management for the upstairs level

The upstairs level has user management and permissions exactly like the downstairs level. Their purpose is to prevent regular users from accessing and modifying the application model.

By default, upstairs user management is disabled. To enable it add the following lines in the portofino-custom.properties file:

meta.users.enabled=true
meta.users.anonymous.enabled=false

Save the file, then restart the application server. From now on, you must authenticate to use the upstairs level. Portofino comes with a default user admin (password: admin). Change its password as soon as possible.

Notice that the upstairs and downstairs level have separate user management. That means you can't use an upstairs user to log in downstairs and vice versa. This may create confusion at times, but keeps a better separation between the two levels.

Previous: Relationships
Next: Permissions