User and USER_MASTER - users and access control FAQ

User and USER_MASTER - users and access control FAQ



Enterprise Manager introduces the USER_MASTER entity as an abstraction of the User entity, allowing advanced user management by adding configurable fields and advanced privilege management, among other features. The USER_MASTER entity is closely tied to the User entity, since it is the latter that is used for login and authentication in applications, using OutSystems Agile Platform built-in mechanisms, while the former is the one that is handled at Enterprise Manager level, and inconsistent use of these two entities may turn your application confusing and lead to numerous errors.


As stated in the introduction, USER_MASTER is closely tied to User. Each USER_MASTER entry (i.e. each Enterprise Manager user) is associated with at least one User entry (OutSystems user). When using Enterprise Manager 4.1 or above, it is expected that there is exactly one User object for each USER_MASTER object. In older Enterprise Manager versions, it is expected that you have several User objects (one for each tenant) associated with a single USER_MASTER object.

The connection between USER_MASTER and User is made in the User entity. The User entity stores the USER_MASTER identifier in the ExternalID attribute.

Obtaining your user identifier in runtime

When you need to obtain the user identifier in runtime, it will depend on whether you want to obtain the USER_MASTER identifier or the User identifier. Assuming that the user is already loggin in, there are two ways to get that:

  •   To get the identifier for the User entity, you can use Session.UserID;
  •   To get the idenfier for the USER_MASTER entity, you can use Login_GetUserMasterId();

Validating permissions

As you must be familiar, you can create permission areas and associate users to it (using the User entity). This is done with the built-in actions Check<>, Revoke<> and Grant<>. These actions can be used against a User identifier - e.g. Session.UserID.

Also, when using Enterprise Manager, you speak in terms of Privileges (which map directly to Permission Areas) and Roles as groups of Privileges. Validating if a user has a given Privilege or belongs to a given Role is done using EnterpriseManager public actions CheckPrivilege and CheckRole. In this case, you need to use a USER_MASTER identifier - e.g. Login_GetUserMasterId().


Always make sure that you are using the correct user identifier type - User or USER_MASTER. Consequences of not doing so can be:

  •   Inability to access a given screen and/or action;
  •   Possibility to access certain resources without being supposed;
  •   Corrupted information (information about the wrong user in entities);
  •   Runtime errors.

Above all, you should make an initial choice and use it throughout your application:

  •   If you do not want to use Enterprise Manager, you should focus on the User entity, and in Permission Areas (Check<>, Revoke<>, Grant<>);
  •   If you will be using Enterprise Manager, you should only use the USER_MASTER entity, and actions CheckPrivilege and CheckRole.

Feel free to correct or add anything to this post. Also, you can describe your own experiences and common errors you have observed regarding these two concepts - OutSystems User entity and Enterprise Manager USER_MASTER entity.


1 - How does the EnterpriseManager store user credentials: in the USER entity or in the USER MASTER entity?
2 - Is the USER_MASTER entity an extension of the USER entity? (If so, this is rather confusing since USER_MASTER also contains a lot of common attributes found in the USER entity, example - username/password/email etc) OR
3 - does USER_MASTER store it's own set of User credentials, then copy it over to the USER entity (hence there are two copies of
the user's credentials - username/password etc (1 in USER entity, 1 in USER_MASTER)).
4 - How are the two eSpaces related "Enterprise" and "EnterpriseManager"?

1,2,3 - When using Enterprise Manager you should only use the USER_MASTER table and the EM actions like Login_GetUserMasterId() action

4 - Enterprise is the front office of EnterpriseManager that could be used for customizing the UI
To learn more you can check out the EnterpriseManager and StyleGuide training videos in the Academy.
Hello, I'm using 
Permission Areas built-in functions (Check<>, Revoke<>, Grant<>), but i'm not having success. If i put a check permission after the grant and it's correct, but when i list the permissions from the tables, they are not there. The query that i use is this one:

Inner JOIN {User} ENUSER ON ENUSER.[username] = ENUSER_MASTER.[username]
thanks in advance
You really should not try to work around the platform system.
But anyway, since I know the person that developed the original USER_MASTER thingy, here goes:

Note: this may or may not apply to 6.0 -- I haven't checked.

The USER_MASTER table is where the users are stored. When a user is created in EnterpriseManager, that's where it's created. One user only has one entry on this table.

The User table is where the eSpace users are stored (actually it's the tenants users, but on a single tenant eSpace is pretty much the same and I'll not get into that now). Note that the same user (identified by the username) can (and usually does) show up many times on this table, because there is one entry per user per eSpace. If a user has access to, say, 10 eSpaces, he'll have 10 entries on this table. This table is loaded when you assign roles (or direct permissions) to users in EnterpriseManager. The data used to load this table comes from USER_MASTER (thus the name!) and the External_ID column contains the USER_MASTER Id of that user.

The Permission_Area table is where all the permissions from all eSpaces are stored. When you create a Permission Area in Service Studio, it ends up here when you publish the eSpace.

The User_Permission table is where the persistent permissions users have are stored. This table maps permission from Permission_Area with users from User, not USER_MASTER. This tables is loaded when you call the Grant actions directly (with the Persistent parameter set to true), or when you assign roles to users.

Also, Service Center users are completely different, they're created directly by the Service Center on the User table, they don't come from USER_MASTER (and don't have a External_ID value)

Hope this helps.