Roles in Sakai sites

This question comes up on the lists often enough it warrants an article:

“How do I add a new role to all sites in Sakai?”


A role is assigned to a participant in a site. There are a few defaults, like access and maintain for project sites, and various others for course and portfolio sites.
These roles have a set of permissions attached to them which various tools use to allow/hide access to certain features of tools.
For example the annc.newpermission controls what users can create announcements. If you are a participant of a site and are assigned the role that has this permission enabled, you can create announcements.

How sites get their roles

Sites in Sakai get their list of roles at creation time, copied from the appropriate ! realm, where xxx is the type of site.
For example, if I was to create a site of type project, then that site will get a copy of the roles defined in the !site.template.project realm.

You can see what roles are defined for the appropriate site types in the Admin Realms tool:

Caveat: In the Admin realms tool, note the !site.template realm (ie no .xxx after it). If you create a site with no type, or of a type that doesn’t match any of the other !’s, then it will use this template instead.

You’ll also note that out-of-the-box there is no !site.template.project realm. Hence, project sites, by default, get their roles from the !site.template realm.

You can either create a !site.template.project realm, or just use the !site.template realm.

So, now we know that sites take a copy of the roles from their template and they are not inherited, i.e you cannot make a change in the template realm and expect it to propagate to the appropriate sites automatically.

Creating a new role

Suppose you want to create a new role called readonly. You want this role in project sites so that you can assign users this role and they can only read things not add, edit or delete.

In the Admin Realms tools, navigate to !site.template or !site.template.project (see paragraph above), and choose ‘Add Role’. You can also select an existing role and choose ‘Copy Role’ to create a new role based on the permissions in the existing role. Give the role an id, ‘readonly’ might be a good choice, perhaps a description, choose the relevant permissions then click ‘Done’.

You’ll see the new role in your realm. Click ‘Save’ to save your changes to that realm.

Now, any site that you create with the matching type (in this case ‘project’) will have this new role available to assign users to.

Existing sites however, will be unchanged.

Modifying an existing role

To modify an existing role, follow the same process as for creating, but this time select the role, adjust the permissions and save.

The !site.helper realm

This is a special realm whereby you can make temporary changes to all roles in all sites. For example, suppose I need to quickly give every maintain user the ‘’ permission. I could adjust the permissions in the !site.helper realm for that role, and then every site with that role will have the new permission.

Caveat: the roles that you want to adjust must first exist in both the !site.helper realm AND the target site, i.e. you can’t create a new role in the !site.helper realm and have it available in all sites.

Populating new/updated roles to existing sites

So if the !site.helper realm doesn’t cascade new roles and creating new roles in the template doesn’t cascade them either, how do we get new or updated roles into every site? The answer is you need to adjust the realm for every site. And let me tell you, you do not want to do this if you have hundreds or thousands of sites.

So fear not! For I have already challenged and defeated this horrific beast.

The solution might come as a surprise to some who didn’t know this beautiful gem was in the Sakai distribution, the web services!
See my earlier post about how to enable the web services in Sakai and secure them, then read on.
Once you have them enabled, you need to install a web service of mine called copyRole [1].
This is as simple as editing:SAKAI-SRC/webservices/axis/src/webapp/SakaiScript.jws, putting the copyRole method in, saving and rebuilding the webservices project.

You can even edit the deployed SakaiScript.jws (TOMCAT/webapps/sakai-axis/SakaiScript.jws) but you’ll lose your changes if you redeploy.

Then, get the Perl script [2]. This is a simple script I wrote to take care of iterating over many sites and adding/updating a role or many roles from a template realm, e.g. !site.template to the given sites. Note that the realm for a site is /site/siteid. You’ll see that in the script.

So, open up the script and take a look. You need to set the username and password, urls to your web services (there are two), the template realm, the list of roles and the target sites. It’s all documented.

You’ll also need the Perl module SOAP::Lite which you can get automatically by running:
perl -MCPAN -e 'install SOAP::Lite

You might want to take a look at [3] before running the sync script, as it will check if your web services are working ok.
Then it’s simply a matter of running the script and watching as your roles and permissions are synchronised!


  1. copyRole.txt

10 thoughts on “Roles in Sakai sites

  1. >Big wet sloppy kisses for this. 🙂 May the bird of paradise lay an egg in your soup.Fits in nicely with my mantra "more webservices, then more webservices!"Thanks!

  2. Hey Will,
    do you also think that the permissions in the target role should all be zapped (ie toRole.disallowAll()) then only get the ones from the template role? This is my new line of thinking as well so might do an update to the method.

    This is because if the target role has 'some.perm' and the template role doesn't have it, the target role will keep that permission since it only checks the ones from the template.


  3. kurosch says:

    Hey Steve,
    thanks for this awesome tutorial / explanation of Sakai’ RBAC model.
    Just a note I think syncing roles can be made even easier than this, there is a tool called “umusync” where tasks can be created to sync sites together e.g. !site.template.course with course sites.
    Also do you happen to follow any mailing list loosely as I would really like to ask some specifics there and would love to have you in the loop!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s