Group management in WebGUI allows you to control access to very specific sections of your website. Users are assigned to a group, and then that group is assigned viewing or editing rights to a page or asset. This is often utilized on subscription sites where paying subscribers are able to access content on a site that is otherwise not visible to the average visitor. You are probably familiar with this concept from the “Security” tab of add/edit asset screens. The “Who can View” field determines the group of users who may view a given asset.

The group management feature is accessed through the Admin Console. Clicking on “Groups” will open the group management screen.

 

Listed on this screen are all the groups currently existing, a brief description of that group, and the number of users currently assigned to each group. Clicking on a group name will open the “Edit Group” screen.

 

• Group Name: a name or title for this group

• Description: a description of the what this group is for.

• Is Editable?: will this group appear in the list of groups to manage? If set to No, you will not have the ability to manage this group again.

• Show in Forms?: will this group appear in fields where you can choose a group, such as in an asset's Security tab?

• Expire Offset: the amount of time that can pass before the group access expires.

• Notify user about expiration?: if set to Yes, WebGUI will contact the user when it is about to expire from this group.

• Expire Notification Offset: determines how much advance notice a group member will receive before group membership expires.

• Expire Notification Message: enter a message the user will receive via email upon group expiration.

• Delete Offset: the number of days that will pass between expiration notification and the group's actual deletion from the system.

• IP Address: If this is specified, any user's visiting the site from that IP range will automatically be a member of this group. This is great for intranets where you want to grant access to some information, but only if the users are inside your network.

 

 

• Scratch Filter: users can be dynamically bound to a group by a scratch variable in their sessions.

• Database Link: if you'd like to have this group validate users using an external database, select the database to use.

• SQL Query: to validate users against an external databasae you may construct an SQL statement that will return a list of WebGUI userids for users in the group.

• The LDAP fields can be used to bind users in a group to an exisiting LDAP directory.

• Cache groups for how long?: large sites using external group data will make many calls to the external database. To help reduce the load, you may select how long you'd like to cache the results of the external database query within the WebGUI database.

 

Create a Group and Add a User

To create a new group, locate the “Add new group” link on the far right hand side of the screen.

 

A blank “Edit Group” screen will open in which you may enter a group name and a brief description of the group’s purpose.

 

 

Click “save” at the top of the screen, and the group will be added to the list on the “Groups” screen (seen here as the fifth group listed).

Managing Users In A Group

Now that the group is created, users will need to be added to it. You can only add users that currently exist in the system to a group. To assign users to a group, begin by clicking on the group’s name in the “Groups” screen. This will open the “Edit Group” screen for the selected group.

 

On the far right hand side of the screen, click on the “Manage the users in this group” link.

 

This will open the “Users in Group: Add Users” screen.

 

From this screen you have a couple options. If users already existed in this group, you would see them listed at the top of the screen. You can search for a user to add if you know its username. You will also see an “Add Users” field with a vertical menu of usernames to the right (currently, the only user is Admin). You can select users from this list and then click save to add them to the user list. If Admin is selected, and save is clicked, Admin is made a user in this group.

To remove a user from the group you would simply click the red X next to the username, or use the checkboxes to select multiple users to delete at one time. Users’ profiles may also be accessed by clicking on the edit button next to their usernames.

Editing a Group

To edit an already existing group, select a group from the Groups screen, and click on the Edit this group link located on the far right hand side of the screen. The Edit Group screen will open, containing the previous information input at the time of creation. Simply update the group information you'd like to edit, and click save.

 

Managing Groups in a Group

Groups can be added to other groups to efficiently include entire groups of users in one step. To do so, select a group from the Groups screen. On the far right hand side of the screen, click on the Manage the Groups in this Group link. This will open the Groups in this Group screen.

 

 

At the bottom of the Groups in this Group screen is a list of all groups already a member of this group. Next to each group is a toolbar. Click on the red X to delete a group from this group, or the Edit button to edit the individual group. To add a group to this group, highlight a group(s) from the “Add Groups” menu and click save. The selected group(s) will be added to the list at the bottom of the screen.

Managing Expirations

One of the more powerful features of the WebGUI groups system is that it allows you to automatically expire users from groups. This is useful for automatically removing privileges from:

• Students at the end of a semester.

• Limited term employees.

• Clients who have purchased a term-based support agreement or subscription-based content access.

There are a number of settings that you can use to deal with group expiration.

 

Expire Offset is the main trigger for group expirations. It determines how long a user should be a member of a group when added to it. The offset is the amount of time that should pass from the time the user is added to the group until they are removed from the group. Don't worry you can set the final expiration date on a per user basis, we'll show that it a bit.

You may optionally notify the user that they are going to be or have been removed from the group by selecting yes on the notify about user expiration setting.

If you chose yes, then you can set the number of days prior to or after the actual expiration date that you'd like to notify the user. For example if you want to notify them two weeks before the expiration, you'd type “-14”. If you wanted to notify them on the day of expiration, then you'd type “0”. And if you wanted to notify them 3 days after they had already been expired then you'd type “3”.

Then you can write a brief message about why they're being removed from the group. This message will then be emailed to the user based upon the notification offset.

The delete offset is when the user will actually be removed from the group. Note that as soon as they have been expired they no longer have any group privileges, but they are still a member of the group. This can be useful if you want to build a report of recently expired users. If expiration removed them from the group you wouldn't know that they were recently expired! In addition, if you plan to notify the users after they've already been expired, then the delete offset should be higher than the notification offset.

As mentioned previously you can also edit the actual expiration date of an individual user in a group. To do this you'll need to edit the grouping relationship. Go to Groups > Manage users in group and then you'll see a list of users in the group:

 

Now click on the “Edit” button to edit the grouping relationship. That will bring you to a screen that looks like the following.

 

Here you can either type in the expire date, or use the calendar helper to chose it.

Special Inclusion

Another powerful feature of WebGUI's group system is special inclusion. Special inclusion means that the user is not directly part of the group, but they can be dynamically added to the group by some special rules.

How long the user remains a part of the group is up to the individual rule, as well as the cache setting. Because in some cases evaluating these rules can be performance intensive, the result is cached.

 

If you set the cache to last for 1 hour (which is the default), then if the special inclusion rules determine that the user is or is not part of the group, that determination will be the same for 1 hour, regardless of whether the rules have changed. If this amount of caching is not acceptable for the rules you're trying to apply, then set the cache to 1 second. On the other hand, if the result of the rule check won't change very often, then set the cache timeout to a higher value like 1 day.

Scratch Variables

A scratch variable is a variable attached to a user's session for the duration of their session. If the user logs out, or if their session times out, then this variable will no longer be set.

We can use scratch variables for special inclusion. The most typical example where this would be used is that we don't want a user to have access to some information until they have accepted a license agreement or a privacy policy. Once they've accepted the agreement, then we'll give them access to whatever they were looking for.

Most of the time scratch variables are set by a programmer, so unless you are the programmer who set the variable, you likely won't know if it exists. However, you can also set scratch variables via a URL. Here's what that looks like:

/page?op=setScratch;scratchName=EULA;scratchValue=1

 

In the above example we have created a variable called “EULA” and assigned it a value of “1”. However, to prevent trampling on scratch variables set by programmers, WebGUI automatically prepends “www_” to scratch variables set via the URL. That means our variable has been renamed to “www_EULA”.

Now that we have a variable set we can use this in a group for special inclusion. We can set what is called a scratch filter in the group. A scratch filter looks like:

www_EULA=1

 

Now if the user has clicked on our URL, they'll automatically be added to the group. However, scratch filters can require more than just a single variable. Perhaps you want them to agree to both an end user license agreement and your privacy policy. In that case we can create a second URL for them to click on like this:

/page?op=setScratch;scratchName=privacy;scratchValue=1

 

And then we can make our scratch filter look like this:

www_EULA=1;www_privacy=1

 

The value doesn't need to always be “1” either. For example, you may want the user to select from a list of options, and then you can display different information based upon their selection. Let's say you have a page that has information that's useful to people from Canada or the United States, but the information is unique to each of them and you don't want to display both. You can then create two groups and two URLs. And assign one group to each page or asset that contains the information related to that group.

On the landing page you'll provide URLs that look like this:

/page?op=setScratch;scratchName=whereFrom;scratchValue=Canada

/page?op=setScratch;scratchName=whereFrom;scratchValue=US

 

Then you'll create your “Canada” and “U.S.” groups. In the Canada group you'll add a scratch filter like this:

www_whereFrom=Canada

 

In the U.S. Group you'll add a scratch filter that looks like this:

www_whereFrom=US

 

Now you've used the same variable to differentiate two distinct groups of users.

Autonomy

You can also allow users to autonomously add and remove themselves from some groups. This is useful for voluntary subscriptions and permanent acceptance of license agreements.

To allow or disallow this you would select “Yes” on these two options in the group settings:

 

 

 

 

You have the option of setting these parameters individually because there are several circumstances where you might want to allow a user to opt in or out, but not vice-versa. For example, once they agree to a license you may not want them to change their mind later. Or you may want to create a group of users to send emails to, and don't want other people to add themselves to that list, but legally in most countries you do need to give them a way to opt out of such emails.

Once you have determined that users can opt-in or out of a group you have to create the links that the users can use to do that. There are two macros you can use to do just that. They are ^GroupAdd(); and ^GroupDelete();. The syntax for both is the same:

^GroupAdd(EULA, Click here to agree to the terms of service.);

^GroupDelete(Customer Email List, Click here to unsubscribe.);

 

Those will create links that look like:

Click here to agree to the terms of service.

Click here to unsubscribe.

 

You can also optionally specify a template ID as the third parameter like this:

^GroupDelete(Customer Email List, Unsubscribe!, Pbtmpl0000000000000041);

 

You can then create a template to lay out your opt-in or opt out. Your only template variables are “group.url” and “group.text”, so it won't make for a very exciting template, other than your own content, but you can do it. In general no template is necessary.

Database

You can tie group membership to a database query as well. Though it's not trivial, this means you could theoretically even tie privileges to applications external to WebGUI. In order to use this option, your database table must either already contain the WebGUI User IDs of the users you wish to include in the group, or you must have an external table that marries the WebGUI User IDs to the data in your other tables.

For the sake of example, let's say you have a fictional accounting system called Megabux. Let's also say that you have set up privileges for accounting department users in Megabux that you want WebGUI to respect, so that when a Bean Counter is promoted to Chief Executive Bean Counter, the new privileges are also transferred to WebGUI. And when a Stub Lackey is fired, his privileges are automatically removed from WebGUI. This is not only a plausible scenario, but one that we hear all the time. The departments, systems, and roles may change, but the problem is the same.

Megabux has some database tables in a database called DB9 that look like this:

 

users			permissions			roles
uid username password given_name sir_name user_defined	integer(11) varchar(20) char(10 varchar(30) varchar(30) text		uid rid	integer(11) integer(11)		rid role	integer(11) varchar(20)

 

The first thing we need to do is create a group in WebGUI for each role that we want to bind to in Megabux. Then we're ready to ponder our inclusion options.

Ultimately what the WebGUI group is looking for is a list of WebGUI user IDs to be returned to it. So we have to find a way to match WebGUI users to Megabux users. Depending upon our needs there are many ways to do this:

• Require that the Megabux “uid” or “username” field be created as a profile field in WebGUI.

• Put the WebGUI “userId” or “username” into the “user_defined” field in Megabux.

• Create an additional table that maps the WebGUI “userId” field to the Megabux “uid” field.

• Make sure that the WebGUI “username” field matches the Megabux “username” field.

• Make sure that the Megabux “given_name” and “sir_name” fields match the “firstName” and “lastName” fields in WebGUI's user profile.

Once we've identified how we want to match WebGUI users to Megabux users then we have one more hurdle to overcome: synchronization. If WebGUI and Megabux both have databases in the same MySQL server then we can just do a cross database query like this:

select

webgui.users.userId

from

webgui.users

left join

megabux.users

on megabux.users.user_defined=webgui.users.userId

left join

megabux.permissions

on megabux.users.uid=megabux.permissions.uid

where

megabux.permissions.rid='133'

 

That last part '133' represents the ID of a role in Megabux that we want to match to a WebGUI group.

However, if WebGUI is in MySQL and Megabux is in DB9, then we're going to have to write some external script that will synchronize the data using the method we chose above. Writing this script is not difficult to do, but it goes beyond the scope of this book. It would be enough to say that the script would simply connect to both databases once per hour or per day (depending upon how often things change) and synchronize the data used to match a WebGUI userId to a Megabux uid.

Once we have all of the above mechanisms sorted out, the actual group settings are easy. The form looks like this:

 

Choose a database link to connect to. See the chapter on Database Links in this book if you're unfamiliar with the topic.

Then type the SQL query into the field. Remember that it needs to return multiple rows of WebGUI userIds and nothing else.

LDAP

Similar to a relational database, you can use LDAP for special inclusion into WebGUI groups.

 

Select an LDAP connection from the list of defined connections. Note that in order for this to work, the user's that you're trying to get a list of must also log in via this LDAP connection. This can get very complicated very quickly if you have users connecting from more than one LDAP server. If you are unfamiliar with LDAP connections see the chapter on LDAP for a better understanding.

In the LDAP Group field type the full distinguished name (DN) of the group, like this:

cn=My Group, ou=groups, dc=example, dc=com

In the Group Property field provide the attribute that the group members are listed under. On most LDAP systems this is “member”.

In the Recursive Group Property field provide the attribute that other groups are listed under that should also be searched recursively for users. Sometimes this is also “member”, as in Group A is a member of Group B. However, this attribute is implemented differently on each system, and not at all on some systems. Consult you LDAP server's documentation for details.

The Recursive Group Filter is a way to speed up the recursive search system by automatically eliminating some results without recursing through them. It's just s simple string matching system, but if your “member” attribute includes both users and groups, but a group will never contain a property called “uid” then it can speed up queries immensely.

IP Address

WebGUI also gives you the ability to use the user's IP address for special inclusion. There are two main instances where this is interesting:

• If you want to give access to your employees to certain things while they are in the office, but not allow anyone to see those things outside the office.

  • A sub case of this is that you only want administrators to be able to access the user management system or groups system while inside the office. See the chapter on “Settings” for details on giving privileges to admin functions.

• You know your user's IP address or IP range, but you do not know which user accounts belong to them. In this way you can give them access to resources on your site while they are coming from the known IP address or IP range.

Note: Be careful with this setting. It is possible for a hacker to spoof an IP address.

Enter an IP address or range using CIDR notation in IP Address field. You may also add multiple addresses if they are separated by commas.

Here's an example:

10.0.0.1/32, 192.168.1.0/24

 

That will add anyone coming from 10.0.0.1 or anyone who's IP address starts with 192.168.1. into the group during the cache period.