In my previous article on OutSystems 11 User Providers, we learned that a User Provider primarily offers logically isolated user accounts for other OutSystems modules. We also discovered that a user account must have a record in the User entity of the (System) module, and the actual login of a user account is performed using its unique identifier with either the Login or LoginPassword server actions of the (System) module.

Our "Most Simple User Provider”, used for demonstration purposes, includes some server actions to create a new user, log in, and log out. This basic setup is enough for a user to log in.

In OutSystems 11, a logged-in user has a default application role called Registered. This built-in role is automatically assigned to a user after a successful login and can be used to protect screens and actions (via Check<Rolename>Role), just like any other manually created application role.

Of course, the Registered role alone is not enough. We need to understand how to work with additional application roles defined in your application modules and how they can be linked to user accounts.

Managing User Permissions with Roles and Groups

In this follow-up article, we will take a closer look at how to programmatically assign application roles to user accounts, both directly and indirectly through group assignments.

💡

I updated the "Most Simple User Provider" in Forge, which you can use as a reference. Please note that this component is not a production-ready implementation.

Besides the User entity, the (System) module includes several other entities that together make up the built-in user management system.

Roles

Roles are a key concept in OutSystems user management. They are the built-in method to authorize a user to access screens. Each defined role also has a Check<Rolename>Role action, which can be used to verify if the current user has a specific roles assigned.

You cannot create roles programmatically; instead, a role must be defined in a module using Service Studio. A role is always linked to exactly one module (Espace), but you can declare it as public, making it available to other users.

Roles can be linked directly to user accounts by creating a record in the User_Role entity or indirectly to groups by creating a record in the Group_Role entity.

💡

Unlike user records in the User entity, roles are not logically isolated to a User Provider.

User Role Assignment

Creating a record in the User_Role entity can be done in two ways:

Entity action - Use the CreateUser_Role or CreateOrUpdateUser_Role entity actions of the User_Role entity.
Role action - Each manually defined role in your module has a default Grant<Rolename>Role action. You can use this action anywhere in your module's action flows to permanently assign a role to a user.

💡

For Traditional Web Applications, you can define a non-permanent role. Granting a user a non-permanent role is not saved to the database; it only applies during the user's session. This feature is not available for Reactive Web or Mobile applications.

Entity actions are best for associating roles with users across different application modules. Your custom User Provider, for example, is the ideal place to have a server action that links a user with an existing role. On the other hand, the role action should only be used within modules of the same application where the role is defined.

➡️ Reference: User_AddRole Server Action in MostSimpleUserProvider module

Groups

Groups, as the name suggests, allow you to group users and roles. Groups can be created programmatically using the Create entity actions of the Group entity in the (System) module.

Groups are logically isolated to the User Provider. Just like with the User entity, OutSystems automatically filters groups to the used User Provider when querying.

➡️ Reference: Group_Create Server Action in MostSimpleUserProvider module

💡

Group has a boolean attribute called Has_Custom_Management, which is considered deprecated and is not used.

Group User Assignment

To associate a user with a group, use the Create actions of the Group_User entity in the (System) module. To create a new association, specify both the Group Identifier and the User Identifier.

Group_User has a unique constraint, which will cause a Database Exception if you try to create a combination of group and user that already exists.

➡️ Reference: Group_AddUser Server Action in MostSimpleUserProvider module

Group Role Assignment

To create an association between a group and a role, use the Create actions of the Group_Role entity in the (System) module. Similar to Group_User, Group_Role has a unique constraint on group and role identifier combination.

➡️ Reference: Group_AddRole Server Action in MostSimpleUserProvider module

Effective Roles

OutSystems provides a read-only entity called User_Effective_Role (technically a view in the database) that shows a combined view of role associations for user accounts. It includes roles assigned directly to users and those assigned indirectly through group associations.

It helps identify a user's permissions across all roles and modules.

➡️ Reference: User_GetRoles Server Action in MostSimpleUserProvider module

Summary

The platform's user management system offers a set of entities in the (System) module to manage:

User - User records
Role - Application roles
Group - Groups, allowing the grouping of users and roles
Group_User - Many-to-many relationship between groups and users
Group_Role - Many-to-many relationship between groups and roles
User_Role - Many-to-many relationship between users and roles

Roles can only be created in a module using Service Studio, while all other entities can be managed using the entity actions.

To check a user's effective role associations, you can query the User_Effective_Role entity. This includes roles directly linked to the user or indirectly through group assignments.

I hope you found this helpful and that I explained the topic well. If not, please let me know by leaving a comment.

OutSystems 11 Users, Groups and Roles

Table of contents