Introducing Users And Permissions


Jump to: navigation, search
Introducing Users and Permissions
Unify Tutorial
Unify Tutorial Series
Series Beginner
Unify Tutorial - Introducing Users and Permissions
Position in series 3
Next in Series Adding Content
Previous in Series Building a Basic Site
Prerequisites Building a Basic Site


Introducing Users and Permissions


This tutorial continues from the previous tutorial and focuses on user management and permissions. We're going to create an area in the public tree for users to register for an account. This register page will create the account but leave it inactive. Then we’ll create a user management area in the admin tree to activate and manage our users. We’ll also add permissions to our admin tree so that only specific users can get access to it and we’ll create an admin login area so authorised users can get access to the admin tree.

Creating the public user registration page

Follow the steps from the previous tutorial and create a page that will be used for registering users. Using the public page template as before make this a top level (root) page, give it a path of "registration" and set it to "Published" so that it’s accessible and will appear in any navigation.

Modify the static code portlet on the public page template footer and add a link so users can navigate to the registration page. For help adding the link, have a look at the one created in the admin page in the previous tutorial. To create users we want to use the User Create portlet, add this to the page in the usual way. The user create portlet is found in the User Portlets menu. You’ll notice that when you add the portlet you are presented with a list of realms. Choose the default realm and save. You’ll now be presented with an edit mode that looks similar to the edit portlet we used in the previous tutorial. Complete the following steps:

  1. Set the redirect page to the home page.
  2. At the bottom of the page, expand the General menu.
  3. Add the following fields – Username, Email Address, Password and Submit button clicking save after each selection.
  4. Save the portlet settings and click view to see the page
  5. As with the Item – Edit portlet in the previous chapter, add the class name "createnews-wrapper" to the portlet so it’s nicely formatted. This is done by clicking the portlet bar and then clicking the properties icon. It should look something like the following:

Try creating a user with the form. Then open the users and groups module and load the list of users. This can be found by expanding the default realm and clicking the Users link.

You’ll notice that most of the users in the system have a green light, but the one you created has a red light. This means that this user is inactive and requires activation before they can log in. In this tutorial site we only want administrators to be able to activate users, so we are now going to create the user management area in the admin tree.

Creating the admin user management area

The admin management area will need three pages: one for listing users and two sub pages for creating and editing users. Create the three pages under the admin page using the admin page template. It should look something like the following:

Note that the edit page has been made "Published but hidden" and as such won’t appear in navigation. This is because in order to edit users we have to pass the id of the user we wish to edit in the URL.

Open the user list page and add a User list portlet portlet to the page. This portlet is similar to the Search Results portlet in that it generates XML which is transformed with a user supplied XSL to create HTML.

  • Set the list mode to "List all users from the realm."
  • Click the pagination tab, and click the "Divide into pages" box, leave the default "Users per page" as 15 and save.

  • As we haven’t created an XSL for this, the User List portlet defaults by outputting an HTML textarea with the resultant XML inside. Select this XML and have look at it in your XML editor.

Like the Search Results portlet XML, the User List XML has a node for pagination named "list" which gives information on the current state of the pages. It then has many "user" nodes for each user returned on this page. Each user node contains all the information available on this user. Most of the nodes are self explanatory but there are a few things worth mentioning:

  • Every user has a user id noted by the id node, and a profile id.
  • The link node is a helper node that can be used to construct URLs to point to an edit page that would edit this user.

Open the file entitled admin_user_list.xsl and complete the TODO sections. This follows a very similar pattern to the admin_news_list XSL. Once complete add this to Unify in the User list section of the XSL storage area. As with the search results XSLs, don’t forget to create a sub folder to further separate the XSLs. Your User List should look something like the following:

Inspect the edit link and you’ll see the URL format Unify requires to be able to edit items.

Now we want to add a User Edit portlet to the user edit page. This is almost identical to the user create portlet we used earlier. Add this to the page, selecting the following attributes:

  • Email address
  • Groups
  • Activation checkbox
  • Submit button

Make sure you set the Type parameter to "Detect user from incoming parameters" so we can use our edit links from the list page. Also, set the redirect page to be the user list page. Note that it’s not possible to change a user’s password with the user edit portlet. There is a special portlet for this called the Change Password portlet.

When you view your page, you’ll see there it displays nothing. This is normal with edit pages: as you haven’t passed any user parameters to the page; it doesn’t know what to edit. Test out the edit links on the user list page. To finish off our user management area we need to add a User create portlet to the admin create user page. It might be quicker to copy the portlet from the public registration page and then edit it with the steps below.

  1. Open the General attributes
  2. Select Groups and save with the default settings
  3. Select the Activation check box and save with the default settings
  4. Using the little up Image:Element_up.png and down Image:Element_down.png arrows, move the newly added fields to a more suitable position as they are currently below the submit button
  5. Add a suitable redirect page and save

Make sure you have an activation check box in this one as we want to allow our admin users to create active users if needed and add the groups attribute so we can add users to groups.

Groups and Permissions

With Unify it is possible to add permissions to many different areas of the system to restrict and allow access to specific sets of users. Generally permissions are added at the group level and users are added to those groups to inherit the permissions. Permissions can be added to individual users but this can be hard to track and maintain, so it’s generally easier to use groups.

So the first task is to create a group which will define the set of users allowed to use the admin branch of our site. Note, we could use the default admin group, but this also grants access to the Unify back end, and we might not want our web admin users to access this area. To create a group:

  1. Open the Users and Groups module, expand the Default realm and click the Groups link
  2. Click "Create" from the top navigation.
  3. Name the group "Web Admin" and add a brief description. Click 'Save'.

Now we have a group for our web administrators, we can restrict the admin tree and grant only the web admin group access.

  1. Open the "admin" page and click the Edit button from the top navigation.
  2. Find the "Access Controlled" radio buttons, set it to "yes" and click 'Save'.
  3. Under the "Settings..." menu select the "Permissions" link.
  4. Tick the check box for the Web Admin group and save.

Note: The default "Admins" group has all permissions so it’s never necessary to grant permissions to the admin group. Notice that the admin page icon now has a gold padlock icon and the child pages have a grey padlock. A gold padlock shows that this page sets its own permissions, a grey padlock mean it inherits permissions from an ancestor.

User Permissions and Listing Users

Since Unify version, non admin users do not, by default have the permission to list users within the default realm. Therefore, we will need to explicitly grant this access.

  1. Navigate to the Users and Groups module, and click the Permissions link.
  2. Select the group or groups that you would like to grant user listing access.
  3. In the "Permission set:" select box, select Realm: Default
  4. Click on the 'Permissions' button in the top nav
  5. Tick the boxes granting Edit User and View User permissions and save.

For more information on global user permissions see User Permissions

Creating a login area

Now that we have restricted areas of the site, we need to provide a login system so that the web admin users can gain access to the system. First create a page with a path called login at the root level and add a User Login portlet to it. You’ll notice the portlet complains there is no realm selected so in the Authentication Realm select box select the Default realm and save the portlet. There are 6 different redirect options available for various results of the user attempting to login. For the purpose of our tutorial we’ll send all unsuccessful login attempts to a single page. In a site for a client we’d provide specific pages for each potential outcome.

  1. Create a child page of the login page for unsuccessful login attempts. Give it a path of "unsuccessful" or similar.
  2. Add a static text portlet to the unsuccessful page and provide some text informing the user that their login attempt was unsuccessful with a link back to the login page to retry.
  3. Go back to the login page and edit the login.
  4. Enter a suitable redirect path for the successful login and enter the path to the unsuccessful page for all the other redirect options.
  5. Now go to your Page Templates folder and modify your Admin Page Template so that you include somewhere a Log Out Portlet. To do this you go to your Publishing Module and then to your Page Templates, choose your Admin Page Template and add a Log Out Portlet (Found under User Portlets and then User - Logout). Select your Home Page as the page that you are redirected after Logging Out.

By default the login portlet will not display if the user is currently logged in, so when you view the login page in the back end, you won’t see anything. If you want to change this, there is an option in the portlet edit mode.

Setting up error pages

In the event of the end user requesting a page for which they do not have permissions, or requesting an invalid page we can set Unify to respond with a predefined page. In this section we’re going to create three new pages to handle the three HTTP error responses – Unauthorized (401), Not Found (404) and Internal Server Error (500).

  1. Create three pages for each of these conditions and add a static code portlet on the page with some text defining the error.
  2. Click the site globe for your tutorial site. You’ll notice that there is the orange alert box explaining that certain pages have not been set. Set these from the "Settings..." menu.
  3. Finally set the login page to your login page.

Make sure you set the error pages to "Published but hidden" as we don’t want these to appear in the navigation

Finishing Up

  1. Deploy all your pages and files. Remember that you can deploy pages and files from their parent page / folder.
  2. Once deployed, open the login page in the front end and login using your admin account.
  3. Navigate to the admin user create page and create a new user placing them in the Web Admin group.
  4. Log out of the system and log back in again with the new web admin account.
  5. Test the permissions by viewing the admin tree with the new account.
  6. Try removing the user from the Web Admin group and see what happens when you attempt to access the admin tree.
  7. Now Log Out from your web admin account by using the Log Out that you created earlier


  • Creating users and groups
  • User list, create and edit portlets
  • Adding access control to pages allowing specific groups access
  • The Login portlet
  • Default error pages
Personal tools