S2 Accessing the User Management

This article describes how to programmatically access the user and rights management that is part of the Automation Platform.

The following example shows how to perform the following tasks:

  • Create a new group and add it to the group list of a project.
  • Create a new user, add it to the user list of a project, set the password, and make the user a member of the group created before.
  • Adjust the modification rights for any object in the project, so that only members of the newly created group are allowed to edit the objects.

How to access the user management

The user management is a system instance that implements one of the _3S.CoDeSys.UserManagement.IUserManagementXXX interfaces. To access it, use the following code:

IUserManagement userMgmt = (IUserManagement)ComponentManager.Singleton.InstanceFactory.GetSystemInstance(typeof(IUserManagement).FullName);

Starting from that point, you have got access to the user list, the group list, the password system ("authentication"), and the currently logged on users ("session").

Creating new groups and users and modifying their properties

Performing those tasks is quite easy with the interfaces that are provided. The commented code snippet should be self-explanatory.

try 
{
 if (UserMgmt is IUserManagement2)
 ((IUserManagement2)UserMgmt).BeginTransaction();

 // Create a new group "Developers", if not existing.
 groupList = UserMgmt.GetGroups(project.Handle);
 developersGroup = groupList["Developers"];
 if (developersGroup == null)
 developersGroup = groupList.Create("Developers");

 // Create a new user "John Doe" with password "JDoe" and make him a member of the
 // "Developers" group.
 IUserList userList = UserMgmt.GetUsers(project.Handle);
 IUser johnDoeUser = userList["John Doe"];
 if (johnDoeUser == null)
 johnDoeUser = userList.Create("John Doe");
 UserMgmt.GetAuthentication(project.Handle).SetPassword(johnDoeUser.Id, "JDoe");
 if (!developersGroup.IsMember(johnDoeUser.Id))
 developersGroup.AddMember(johnDoeUser.Id);
}
catch
{
 SystemInstances.Engine.MessageService.Error(Resources.CannotAccessTheWorkspaceObject);
 return;
}
finally
{
 if (UserMgmt is IUserManagement2)
 ((IUserManagement2)UserMgmt).EndTransaction();
}

Special groups

There are two groups in the user management system that are predefined and cannot be deleted:

  • Owner: This group has got at least one member (by default a user called Owner with an empty password). The last member cannot be deleted, so it is assured that there at least one at a time. Members of the Owner group have unrestricted rights on the project.
  • Everyone: Every user is implicitly a member of the Everyone group, so the member list of this group cannot be edited.

If you need access to the Everyone group, use the following code pattern:

IGroup everyoneGroup = null;

foreach (IGroup group in groupList.GetAll())
{
 if (group.IsEveryoneGroup)
 {
 everyoneGroup = group;
 break;
 }
}

Debug.Assert(everyoneGroup != null); // There is always one!

Likewise for the Owner group; just replace group.IsEveryoneGroup by group.IsOwnerGroup.

Controlling object access

Every object in a CoDeSys project is controlled by the user management. There are four permissions on each object:

  • View
  • Modify
  • Remove
  • AddRemoveChildren

The information, which user group is allowed to execute each of those actions on a particular object are stored at the object itself, namely in a _3S.CoDeSys.Core.Objects.IObjectAccessProperty property associated with the meta object. So if you want to adjust those permission settings, you have to modify (or create) this property. Take a look at the following code snippet, which explicitly denies the modification right for the Everyone group, and which explicitly grants the modification right for the newly created Developers group.

IMetaObjectStub mos = SystemInstances.ObjectMgr.GetMetaObjectStub(project.Handle, objectGuid);
bool bNeedToModifyObject = false;
callback.TaskProgress(mos.Name);

// Read the object access property from the object. If it does not yet exist,
// create one.
IObjectAccessProperty accessProperty = mos.GetProperty(GUID_OBJECTACCESSPROPERTY) as IObjectAccessProperty;
if (accessProperty == null)
{
 accessProperty = (IObjectAccessProperty)ComponentManager.Singleton.CreateInstance(GUID_OBJECTACCESSPROPERTY);
 bNeedToModifyObject = true;
}

// Does a permission for the "Modify" access already exist? If not, create it.
Guid permissionId = accessProperty.GetPermissionId("Modify");
if (permissionId == Guid.Empty)
{
 permissionId = Guid.NewGuid();
 accessProperty.SetPermissionId("Modify", permissionId);
 bNeedToModifyObject = true;
}

// Is the "Modify" access for the "Everyone" group already specified, and is it
// denied? If not, do so.
if (!accessProperty.IsPermissionSpecified(everyoneGroup.Id, permissionId) ||
 accessProperty.IsPermissionGranted(everyoneGroup.Id, permissionId))
{
 accessProperty.DenyPermission(everyoneGroup.Id, permissionId);
 bNeedToModifyObject = true;
}

// Is the "Modify" access for the "Developers" group already specified, and is
// it granted? If not, do so.
if (!accessProperty.IsPermissionSpecified(developersGroup.Id, permissionId) ||
 !accessProperty.IsPermissionGranted(developersGroup.Id, permissionId))
{
 accessProperty.GrantPermission(developersGroup.Id, permissionId);
 bNeedToModifyObject = true;
}

// If we modified anything above, make it persistent.
if (bNeedToModifyObject)
{
 IMetaObject mo = null;
 try
 {
 mo = SystemInstances.ObjectMgr.GetObjectToModify(project.Handle, objectGuid);
 mo.AddProperty(accessProperty);
 }
 catch
 {
 SystemInstances.Engine.MessageService.Error(string.Format(Resources.CannotAccessObject, mos.Name));
 }
 finally
 {
 if (mo != null && mo.IsToModify)
 SystemInstances.ObjectMgr.SetObject(mo, true, null);
 }
}

Running the sample

  1. Download the attached sources.
  2. If not already done, set the environment variable %APCOMMON% to the Common directory of your CoDeSys installation. (This is the directory where CoDeSys.exe, IPMCLI.exe, and IPM.exe are installed.)
  3. Start Visual Studio and open the solution SampleUserManagement.sln.
  4. Depending on your installation, you must correct some references to interface components, so that they point into the Interface Binaries folder in your Automation Platform SDK installation.
  5. Build the sample. The plug-in will be automatically installed.
  6. Use IPM.exe in order to add the plug-in Sample: User Management to one of your version profiles.
  7. Start CoDeSys, ignore the message about the missing plug-in key.
  8. Add the menu command Setup User Management... to your menu configuration using the Tools :: Customize... functionality (the command can be found in the User Management category).

When you open an arbitrary project and execute the Setup User Management... command, then the following things will happen:

  • If not existing, a new group Developers will be created.
  • If not existing, a new user John Doe will be created, added to the Developers, and his password will be set to JDoe.
  • For all objects in the project, the modification permission will be explicitly denied for the Everyone group, and explictly granted for the Developers group.

During the execution of the command, you typically must login as an Owner (just use username Owner and empty password to continue). Read the next section what that is the case.

User rights promotion

When making access right changes programmatically, the code is executing within the context of the currently logged on user. But what if that user has got restricted rights? Then your code will not work unless another user with sufficient rights exeuctes the code. This is typically not the desired behavior: the programmatic changes should work no matter which user is currently logged on. To achieve that goal, the user management system has implemented the concept of "user promotion". See the following code snippet:

ISession4 session = UserMgmt.GetSession(project.Handle) as ISession4;
if (session != null)
 try
 {
 session.Promote("Owner");
 // This code is executed within the context of the almighty Owner user, so every action is allowed.
 // The user does not see this in the user interface.
 }
 finally
 {
 session.Demote();
 }

However, in order to call the Promote method, your plug-in must have special code access security rights. That is the reason why we don't have that code in our download sample: our public samples do not contain a plug-in key and thus no special plug-in flags. If you need to get this code running, please contact us directly. If you run this code without CAS rights, CODESYS will terminate immediately.

SampleUserManagement.zip

8 KB