Search the documentation
 Show GitHub edit links  Hide GitHub edit links
Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.2

OpenCms manages rights in organizational units (OUs). Users can have different rights, group memberships and roles in different OUs. We discuss what OUs are and what is the difference between roles and groups.

Users in OpenCms

You are free to define as many users as you need in OpenCms, assign roles to them and add them to groups. But there are some predefined users in the root OU that should not be deleted (or deleted only in rare cases).

Do not delete any predefined users!
Predefined users in OpenCms

The Admin user has the role "Root Administrator" assigned and has all rights inside OpenCms. This user's data can be altered but be sure to always have a root administrator in your system!


The export user is used internally by OpenCms for static export (of JSP-output for example). This user is in the Guests group and does not have to log in. If you want to get files statically exported, the user needs read permissions on the files. By the separation of Export user and Guest user you can block access to files for visitors of your website that are not logged in, but still have files exported. This may for example be useful in an intranet.


Users not logged in are treated as the Guest user.

Groups and roles

In OpenCms you can define groups and add users to groups. Furthermore, each user has roles in OpenCms. Both, groups and roles are used to set the permissions of a user. But, the permissions of groups and roles are given with different focus:

  • Groups are used to control access to resources in the VFS.
  • Roles are used to control access to the system's functions according to the requirements of the respective role, e.g., control over whether the workplace can be accessed, whether resources can be published, whether user accounts can be managed, ...

The different focus of groups and roles also implies differences in their handling:

  • Roles are fixed while groups can be created or deleted
  • Group permissions can be set on all resources, role permissions are typically not added to resources, except in some /system/ folders.
  • Roles may override permissions set on groups or users, e.g., for the root administrator all permission settings are ignored, he always has all permissions.

Thus, when you think of designing your permission system in OpenCms:

  • Have a look at what a user should be able to do and assign their role according to those tasks. An overview of the available roles is found here.
  • Think about which users should have access to which resources and use groups to allow or deny access.

Predefined groups in OpenCms

A default OpenCms installation ships with three predefined groups. They are special compared to user-defined groups and used internally by OpenCms.

Do not delete any of the predefined groups!
Predefined groups in OpenCms and their pecularities

All members of the Administrators group are automatically root administrators.


Whenever you assign a role to a user, that user is added to the Users group. If you remove the role, they will also lose their group membership (even if you explicitly added them to the group before). Typically, all users should be in the Users group. For example, the rights to read, view and write content in the default site is granted to members of the Users group. The same holds for the /shared/ folder.


Guest and Export user are in this group. It is used in particular for all users who do not log in.

Organizational units for user management

Organizational units (OUs) are meant to make rights management in complex systems easier. All user management in OpenCms is performed in OUs. By default, OpenCms has just one OU: The root OU, where all resources of the VFS belong to. Typically, you do not need to add more OUs.

If you do not need to equip a user with a special role only for special (sub-)sites of your OpenCms installation, stick to the one root OU and do not care about OUs at all. Only when you use OpenCms to handle, for example, many sites, or various subsites that should be managed by different users, will setting up several sub OUs be your choice.

For each sub OU you can specify users and groups and assign roles to users. Furthermore, you can restrict the resources that belong to an OU.

In essence, OUs allow you to:

  • assign roles to users for only parts of your website(s)
  • decentralize user management

But how do users choose their OU? If you have more than one OU, the login dialog changes and users have to select the OU on login.

Root vs. sub OUs

The root OU differs from sub OUs wrt. the available roles. OpenCms system management is always tied to the root OU, thus the respective roles are only available in this OU. In particular, in sub OUs you can not assign the roles:

  • Root administrator
  • Database manager
  • Workplace manager

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.