Roles and permissions

Roles and permissions are the basic building blocks to ensure that people only have access to what they are allowed to see. The two concepts are extremely simple:

• Permission: the atomic right to do a specific task. (eg: createUser, viewIntranet, updateContent, previewContent, publishContent, deleteContent…)
• Role: aggregation of permissions. The role 'contentAuthor' grants permissions 'updateContent', 'publishContent' and 'previewContent'

In Jahia, permissions cannot be granted to users directly. Instead, permissions are assigned to roles, and roles are assigned to users.

Before you begin

Jahia modules rely on Java and Maven. The key requirements are as follows:

• Access to a local Jahia system or the free cloud trial from Jahia
• Oracle JDK 11 or OpenJDK 11
• Maven 3.3+
• Completion of the following tutorials:
  •  Module Management
  • Content Type Definition
  • Rendering content
• The IDE of your choice
• Access to the Jahia administration console

What you will learn

In this tutorial, we will create specific permissions and roles and use those to protect privileged features and displays.

We will use the following content type definition:

[jnt:intranetDashboard] > jnt:content, jmix:structuredContent
 - welcomeMessage (string) i18n

And the following view:

<%@ page language="java" contentType="text/html;charset=UTF-8" %>
<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
<%@ taglib prefix="jcr" uri="http://www.jahia.org/tags/jcr" %>
<%@ taglib prefix="ui" uri="http://www.jahia.org/tags/uiComponentsLib" %>
<%@ taglib prefix="functions" uri="http://www.jahia.org/tags/functions" %>
<%@ taglib prefix="query" uri="http://www.jahia.org/tags/queryLib" %>
<%@ taglib prefix="utility" uri="http://www.jahia.org/tags/utilityLib" %>
<%@ taglib prefix="s" uri="http://www.jahia.org/tags/search" %>

<div class="intranet-welcome">${currentNode.properties.welcomeMessage.string}</div>

Shortcuts:
<ul>
   <li><a href="/cms/news">Read the latest corporate news</a></li>
   <li><a href="/cms/profile/update">Manage your corporate profile</a></li>
   <li><a href="/cms/intranet/administration">Access the administration console</a></li>
</ul>

Create a permission

Permissions are created in a Jahia module (link to the Module creation tutorial) under the folder src/main/imports as XML files. The name of the file is permissions.xml

<?xml version="1.0" encoding="UTF-8"?>
<permissions jcr:primaryType="jnt:permission"
            xmlns:jcr="http://www.jcp.org/jcr/1.0"
            xmlns:j="http://www.jahia.org/jahia/1.0"
            xmlns:jnt="http://www.jahia.org/jahia/nt/1.0">
       <canViewIntranetAdmin jcr:primaryType="jnt:permission"/>
</permissions>

We have just defined a new permission: canViewIntranetAdmin. 

Create a role

Role management is very similar to permission management, except that it also has a management UI. This tutorial will focus on the role creation via a Jahia Module. Under the folder src/main/imports create a file roles.xml

<?xml version="1.0" encoding="UTF-8"?>
<roles jcr:primaryType="jnt:roles"
      xmlns:jcr="http://www.jcp.org/jcr/1.0"
      xmlns:j="http://www.jahia.org/jahia/1.0"
      xmlns:jnt="http://www.jahia.org/jahia/nt/1.0">
       <intranetAdministrator jcr:primaryType="jnt:role" j:roleGroup="edit-role"
                              j:permissions="/permissions/canViewIntranetAdmin"

       />
</roles>

This file creates a new role intranetAdministrator. This new role grants the permission canViewIntranetAdmin.

Assign a role to a user

Roles are assigned on a piece of content, and inherited by all contents below. A role 'Editor in Chief' configured on the homepage will apply to all subpages, unless the inheritance is broken. When editing a piece of content, click "Live role" or 'Edit role', depending on whether the role should apply on edit mode or on the live site.

Edit > Advanced Options > Live Roles > Add user to the intranetAdministrator role        

How to use a permission in a JSP

The JSTL taglib jcr provides a hasPermission method. In our previous example, the following code would only display the link to the administration console to those with the permission canViewIntranetAdmin.

<%@ page language="java" contentType="text/html;charset=UTF-8" %>
<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
<%@ taglib prefix="jcr" uri="http://www.jahia.org/tags/jcr" %>
<%@ taglib prefix="ui" uri="http://www.jahia.org/tags/uiComponentsLib" %>
<%@ taglib prefix="functions" uri="http://www.jahia.org/tags/functions" %>
<%@ taglib prefix="query" uri="http://www.jahia.org/tags/queryLib" %>
<%@ taglib prefix="utility" uri="http://www.jahia.org/tags/utilityLib" %>
<%@ taglib prefix="s" uri="http://www.jahia.org/tags/search" %>

<c:if test="${jcr:hasPermission[c][d][e][f](currentNode, 'canViewIntranetAdmin')}">
   <li><a href="/cms/intranet/administration">Access the administration console</a></li>
</c:if>

How to use a permission in Java

The Java-based permission usage is very similar to the JSP approach:

JCRNodeWrapper page = jcrSessionWrapper.getNode("/sites/mySite/home");
if (page.hasPermission("canViewIntranetAdmin")) {
      // restricted action
}

This piece of code will make sure that the currently logged-in user has the permission canViewIntranetAdmin on the page before executing some logic.