WebGUI is a user-oriented application. Although it can be used to publish static content, WebGUI is the most powerful when used for user-driven applications. In order to facilitate rich user-driven applications, WebGUI has powerful user subsystems. This chapter will show you how to maximize the power WebGUI provides you for user management.

Adding a User

Follow these steps to add a user.

1. Log in and go into admin mode.

2. Select “Users” from the admin bar. The Users screen will open, on which you will either see a list of existing users on the site, or a Search field from which to search for users (displayed if there are a high number of users).

3. Select “Add a new user” from the context menu on the right side of the screen.

4. You’ll now see the add user screen. From here the important fields for you to fill out are “Username” and the “Password” field under the “WebGUI” section.
   
   

 

5. Click “save” when you’re done.

 

Note that there are, by default, two authentication methods, and therefore two authentication sections. They are “WebGUI” and “LDAP”. See the LDAP chapter for more information about configuring LDAP as an authentication source.

There are lots of other things you can set about a user from this screen. From the “Profile” tab you can set all the users' demographics and contact information, as well as their preferences. The Profile tab is covered in more detail later in this chapter under the headings User Profiling and UI Levels. From the “Groups” tab you can add and remove users from as many groups as you like. Groups are covered in more detail in the chapter called Groups.

 

Editing A User

To edit a user follow these steps:

1. Log in and go into admin mode.

2. Select “Users” from the admin bar.

3. Now you will see the user list. From here either select a user, or search for a user to edit. You may search on any part of the username, alias, or email address.



4. Once you’ve selected a user the editing process works the same as adding a user. See Adding A User for details.

 

Configuring Authentication

WebGUI has a pluggable authentication system allowing you to expand it to allow your users to authenticate in whatever fashion they are accustomed to. Out of the box WebGUI supports two authentication methods: WebGUI and LDAP.

 

WebGUI

The WebGUI authentication method allows you to store all your users' authentication information in WebGUI directly, without having to connect to any external resources. Because it has no external dependencies, it is the easiest to use and is therefore the default option.

To access the WebGUI authentication configuration settings follow these steps:

1. Log in and go into admin mode.

2. Select “Settings” from the admin bar.

3. From Settings screen choose the “Authentication” tab.
   
   

4. Now you’ll see the WebGUI authentication properties. 



WebGUI allows for multiple simultaneous authentication methods, thusly allowing one user to authenticate against one method, and another user to authenticate a different way.
   
   

 

5. There are several password options that allow you to control how your users create and change their passwords.

6. You’re also able to set up the templates for account related functions.

7. Click “save” when you’re done.

LDAP

WebGUI also allows your users to authenticate against a directory server like Microsoft Windows Active Directory, Novell eDirectory, OpenLDAP, or Fedora Directory Server via the LDAP protocol. More information about this can be found in the chapter called LDAP.

 

User Profiling

The user profile system allows you to create an unlimited number of fields and categories of fields for your users' accounts. In this way you can attach arbitrary data to your users. It can also be used to gather information from your users, as you can make some fields a requirement of registration.

 

Creating Fields

Fields are created under a User Profiling Category. Each category corresponds to a tab in the User Account system, and to a category in the profile tab of a user's account when accessed through Admin>Users. To create a field follow these steps:

1. Log in and go into admin mode.

2. Select “User Profiling” from the admin bar.

3. Now you will be presented with a list of the fields and categories already configured in the system. Note that many common fields and categories are configured out of the box so that you don’t have to do it yourself.



   

4. To add a field select “Add a profile field.” on the right side of this screen.

5. You will now be presented with a list of options for creating this new field. The fields are all documented in the online help, but we’ll cover a few here specifically that people struggle with.

   

6. The “Field Name” field is what the field will be called behind the scenes. It should only contain letters and numbers with no spaces or special formatting.


7. The “Label” field is expecting a little bit of Perl code, which you can either give it a string like:

‘My Custom Field’



8. Or if you’re using the internationalization system to translate the label you can put in a call to it like this:

WebGUI::International::get(‘my custom field’,’MyCustomModule’);

9. The “Possible Values” field is only used for list field types like “Select List”. In this field you provide a Perl hash reference of the possible values. Here’s an example of part numbers and product names for example, if the profile field was favorite shoe:

{
 ‘shoe001’ => ‘Reebok’,
 ‘shoe002’ => ‘Nike’,
 ‘shoe003’ => ‘Wolverine’,
 ‘shoe004’ => ‘Doctor Martins’
}

10. The “Default Value(s)” field is also expecting a little Perl code. But it depends upon what type of field is selected as to what the Perl code should look like. On most field types it’s expecting a string like:



‘Chicago’



However, if the field type is a list as in the example above, then it will be expecting an array reference like:



[‘shoe001’]



And if the field is capable of multiple values, then you can even give it multiple values in the array reference like this:



[‘shoe001’, ‘shoe003’]

Note that if you enter invalid code into these fields that you can cause the user management functions of WebGUI to stop working. Therefore you are only recommended to add or modify profile fields if you understand Perl. Seek professional Perl help if you have questions.

 

Creating Categories

Categories are used to subdivide the list of profile fields into manageable segments. When users view their user profiles in the User Account system the categories appear as tabs. These also create categories on the Profile tab of WebGUI's user system when a user account is accessed through Admin>Users.

 

When you enter the User Profile screen, the categories appear in bold print.

 

To create a category follow these steps:

1. Log in and go into admin mode.

2. Select “User Profiling” from the admin bar.

3. Now you will be presented with a list of the fields and categories already configured in the system. Note that many common fields and categories are configured out of the box so that you don’t have to do it yourself.

4. To add a category select “Add a profile category.” on the right side of this screen.
   
   

 

5. Enter a Category Name and a Category Short Name, and indicate if this category is visible and editable by users.

6. Click save to create the category.

 

Setting Defaults

It is common and logical to think that setting the “Default Value(s)” field when creating a field will actually set the default value of that field site wide for all users. However, in reality if a user doesn’t have a profile property set, then WebGUI inherits this property from the “Visitor” user. All users are based upon the Visitor user. Therefore to set the default value for a given profile field, you need to edit the value in the Visitor user’s profile. See Editing A User earlier in this chapter for details.

UI Levels

The User Interface (UI) level in WebGUI allows you to customize the user interface appearance and functionality on a per user basis. This is convenient if you have users who will be managing content on the site, but should not have privileges to set viewing and editing prvivileges or assign metadata. It's also a useful way to slowly grant users more editing power as s/he becomes more acquainted with WebGUI.

 

Setting A User’s UI Level

A user's UI level is set in the user profile screen.

1. in the Admin Console, select Users.

2. The Users screen will open. In this screen, perform a search for the user whose UI level you'd like to set.

3. Click on the user's username in the main Users screen to enter that user's user profile. The Edit User screen will open.

4. In the Edit User screen, click on the Profile tab.

5. Near the bottom of the Profile tab is the Preferences area which contains the UI Level field.

    

   

6. In the UI Level dropdown menu, select the UI Level you'd like to assign to this user, based on the users WebGUI expertise. Level 9, Guru, will grant the user full functionality, while a lower level will offer less functionality.

7. Click save.

See examples below of sample UI Levels and how they alter the view of WebGUI in Admin Mode. The users in the sample screenshots have the ability to turn admin on and manage content.

 

UI Level 9: Guru

View of webpage in Admin Mode:

 

 

All options in the Admin Bar and the asset toolbars are made available. When adding an asset, all tabs are present:

 

UI Level 5: Adept

A view of a web page in admin mode:

 

In UI Level 5 you can see that many of the options available in the Admin Console have been removed. If this user attempts to add a new asset to the site through the New Content menu, s/he will be shown an error stating that s/he doesn't have the appropriate privileges. The user is allowed to edit an existing asset, however, the Security tab has been removed from the user interface.

 

UI Level 1: Novice

Once again, you can see many options from the Admin Console have been removed; upon reviewing the New Content menu you would also find that some assets, such as Folder, have been removed. The shortcut arrow has also been removed from the asset toolbar.

 

This user can edit an existing asset by clicking on the Edit button of an asset toolbar; however, the only tab available is the Properties tab.

 

Overriding UI Levels

Though the assets in WebGUI have predefined UI levels set by the developer, you as an administrator can override the UI levels all the way down to the field level. You do this in the config file for each site.

Using the assetToolbarUiLevel directive you can set the UI level for each item in the asset toolbar. So if you wanted all but the most basic functions to be hidden from view for most users you could set it like this:

 

"assetToolbarUiLevel" : {

"edit" : 1,

"delete" : 1,

"cut" : 1,

"copy" : 1,

"shortcut" : 9,

"editBranch" : 9,

"lock" : 9,

"export" : 9,

"changeUrl" : 9,

"promote" : 9,

"demote" : 9,

"manage" : 9,

"revisions" : 9,

"view" : 1

},

 

Though the highest UI level is 9, you can actually set these values higher than that. So if you set something to 10, it will never be seen by any user at all.

Using the assetUiLevel directive you can set the UI level for an entire asset type. Therefore the user won't see the asset in the list of assets they can add unless they have the requisite UI level. Here's an example:

 

"assetUiLevel" : {

"WebGUI::Asset::Wobject::WSClient" : 9,

"WebGUI::Asset::Wobject::SQLReport" : 7,

"WebGUI::Asset::Wobject::SQLForm" : 9,

"WebGUI::Asset::RichEdit" : 4

},

 

You can also set the UI level of an individual field. This is a somewhat clumsy process that will likely be replaced with something better in the future. Here's an example:

 

"WebGUI_Asset_Wobject_Article_uiLevel" : { "menuTitle" : 9, "url" : 8 },

"WebGUI_Asset_RichEdit_uiLevel" : { "askAboutRichEdit" : 7, "preformatted" : 3 },

 

What you see here is the class name of the asset followed by the keyword “uiLevel”, only instead of double colons separating the namespaces, we use an underscore. Then in the value part of the field we have the individual field names and their new UI levels.

 

Login History

The Login History provides a list of users who have logged into your site, listed from most recent to oldest. To view your login history, select Login History from the Admin Console. This will open the Login History screen.

 

Listed on this screen are the usernames of users who logged in, as well as an indication of if the login in attempt was successful. The time and date of the login is recorded as well as the IP Address of the user. In the far right hand column is the User Agent used to view the website.

 

Active Sessions

The Active Sessions screen displays currently active sessions on your site and allows you to kill sessions with a simple click.

1. To view active sessions, click on Active Sessions in the Admin Console.

2. The Active Sessions screen will open, listing all currently active sessions on the site. Included on this screen are the usernames of logged in users, a unique session signature, a date and time at which the users session will expire, the date and time an active user last viewed a page, the user's IP Address, and an icon to kill a session.
   
   

 

3. To kill a user's session, simply click on the red X to the far right of the username whose session you would like to end.
   
   

Importing Users

Unless you're building a brand new site you probably will have a list of users you want to migrate from an old site. Even if you are creating a new site, you may have a list of users you'd like to bring in from some other system. Luckily WebGUI comes with a command line utility to help you out. To access this utility type:

cd /data/WebGUI/sbin
perl userImport.pl --help

Usage: perl userImport.pl --usersfile=<pathToFile> --configfile=<webguiConfig>

--usersFile File (and path) containing import information.

--configFile WebGUI config file (with no path info).

Options:

--authMethod The authentication method to be used for

each user. Defaults to 'WebGUI'. Can be

overridden in the import file.

--canChangePass If this flag is set users will be able to change

their passwords. Otherwise not.

--delimiter The string that separates each field in the

import file. Defaults to tab.

--expireOffset The the amount of time before the user will

be expired from the groups they are added

to. Defaults to the expire offset set in

the group definition within WebGUI. May be

overridden in the import file.

--expireUnits Valid values are "seconds", "minutes",

"hours", "days", "weeks", "months", "years",

"epoch", or "fixed". Defaults to "seconds". This is

the units of the expire offset. If set to

"epoch" the system will assume that the

expire offset is an epoch date rather than

an interval. If set to "fixed" the

system will assume that the expireDate is

a fixed date.

--groups A comma separated list of group ids that

each user in the import file will be set

to. Can be overridden in the import file.

--help Display this help message.

--identifier Alias for --password.

--ldapUrl The URL used to connect to the LDAP server

for authentication. Can be overridden in

the import file.

--override This utility is designed to be run as

a privileged user on Linux style systems.

If you wish to run this utility without

being the super user, then use this flag,

but note that it may not work as

intended.

--password The default password to use when none is

specified with the user. Defaults to

'123qwe'. Can be overridden in the import

file.

--quiet Disable output unless there's an error.

--status The user's account status. Defaults to

'Active'. Other valid value is 'Deactivated'.

--update looks up all the users from the file in the database

and updates all the given fields for each user that

exists in the database. users that are in the file

and not in the database are ignored.

--updateAdd looks up the users from the file in the database

and updates all the given fields for each user that

exists in the database. users who do not exist in the

database are added as new users.

--replaceGroups when updating, if the user already belongs to some group

this flag will delete all the user's existing groups and

and the new groups to him/her

User File Format:

-Tab delimited fields (unless overridden with --delimiter).

-First row contains field names.

-Valid field names:

username password authMethod status

ldapUrl connectDN groups expireOffset

-In addition to the field names above, you may use any

valid profile field name.

-The special field name 'groups' should contain a comma

separated list of group ids.

Special Cases:

-If no username is specified it will default to

'firstName.lastName'.

-If firstName and lastName or username are not specified,

the user will be skipped.

-Invalid field names will be ignored.

-Blank lines will be ignored.

-If userId is specified for an import record, that userId

be used instead of generating one.

 

Using this utility you can import users, assign profile fields, assign users to groups, and update the settings of existing users. To use it you first need a file that contains users you wish to import. Here's an example:

 

username identifier groups email
bob blue42 3 bob@bob.com
jane blue43 a3j3sk3sk4k3jDJjs_s3Ex,i1xn3sj43Kjesl5sy7Bx3 jane@bob.com
joe joe@bob.com

 

The first row contains the field we're going to import. Each field name separated by a tab.

The second row describes a user named “bob” that has a password of “blue42”. Bob must be the boss because he's being added to a group with an id of “3”, which is the “Admins” group. And finally we have Bob's email address. Note that these parameters don't necessarily line up with the column headings. That's ok, because they aren't columns, they're tab separated fields.

The third row describes a user named “jane” that has a password of “blue43”. Jane is being added to two groups. We can see a comma separating the two group IDs. And finally we have Jane's email address.

The fourth row describes a user named “joe”. There is no password defined for Joe, which means we can either specify one on the command line, or his password will default to “123qwe”. There are also no groups specified for Joe, so he won't have any specific privileges initially. Finally, we do have Joe's email address.

Now to import this group of users we simply type the following command:

 

perl userImport.pl --conf=www.example.com.conf --users=/path/to/users.txt

 

We'll then see some output as the import process proceeds.

 

Starting up...OK
Adding user bob
Adding user jane
Adding user joe
Cleaning up...OK

 

If we run the command a second time we'll get some output noting that we've already imported these users.

 

Starting up...OK
User bob already exists. Skipping.
User jane already exists. Skipping.
User joe already exists. Skipping.
Cleaning up...OK

 

We could also use the --update or --updateAdd command line arguments if we wanted to update something about our users, rather than skipping over them.

 

Locked Out?

Since the early days of WebGUI we've gotten support questions from our users who have locked themselves out of WebGUI. They've forgotten the password to their admin account.

It should be said, that you should create an extra account with admin access. This leaves a back door for yourself should you ever accidentally do something to lose access on the first account. Prepare for disaster before disaster strikes.

The good news is that you can get in even if you haven't done this, by following these simple steps.

 

Forgot Admin Username

If you've changed your admin account username and forgotten what you've changed it to, then log in to the MySQL command line like this:

 

mysql -uUSERNAME -pPASSWORD www_example_com

 

You can get your username and password from your WebGUI config file.

Then type this command.

 

select username from users where userId='3';

 

That will return output of your username.

 

BigAdminDude

 

If you wish you could just change it back to “Admin” like this:

 

update users set username='Admin' where userId='3';

 

Forgot Admin Password

You cannot recover a lost password because WebGUI uses a one way encryption technique to store passwords. This ensures that if anyone were able to view your stored password in the database, it would be useless to them. However, if you've forgotten your admin password, you can easily reset it to the default “123qwe”. Log in to MySQL as described above, and then type this command:

 

update authentication set fieldData='RvlMjeFPs2aAhQdo/xt/Kg' where userId=3 and authMethod='WebGUI' and fieldName='identifier';

 

Be sure to set it to something more secure after you log in.

 

Page/Style Template Broken

Another way you might get locked out of WebGUI is if you break a page or style template. For instance, in the style template you might forget to place the template variable that puts content onto the page. The good news is that you can log in and do other admin functions using only some simple URLs.

To log in, use this URL:

 

http://example.com/?op=auth;method=login;username=admin;identifier=123qwe

 

To turn admin on use this URL:

 

http://example.com/?op=switchOnAdmin

 

And to view the admin console go to:

 

http://example.com/?op=adminConsole