Notes on the documentation

This description is only intended for the use of trained specialists in control and automation engineering who are familiar with the applicable national standards.
It is essential that the following notes and explanations are followed when installing and commissioning these components.

The responsible staff must ensure that the application or use of the products described satisfy all the requirements for safety, including all the relevant laws, regulations, guidelines and standards.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development.
For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics.
In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning.
No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The TwinCAT Technology is covered, including but not limited to the following patent applications and patents:
EP0851348, US6167425 with corresponding applications or registrations in various other countries.

Copyright

© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.


Common

General

TwinCAT is a general automation system (or suite of automation modules) whose components can be added or removed in various configurations. Since TwinCAT is constructed in a very modular fashion and the modules are independent of each other, the User Manager can be implemented independently of the other modules. The PC operating system (Windows NT/2000, Windows CE) is also a part of the TwinCAT automation system and must therefore be included in the user administration.

For the deployment of TwinCAT under Windows NT*/2000 the user administration is based on the security system of Windows NT, i.e. an NT administrator is also a TwinCAT administrator and users of an NT domain are also recognised in TwinCAT. Thus the total system can (if necessary) be administered using Windows NT tools. The security system of Windows NT can revoke or award access rights for each object of the operating system (partition, directory, file, network, …). Access to the NT security system is unfortunately relatively opaque, since the API is distributed over a number of parts of the operating system. Thus some functions are to be found in the "Lan Manager" API whereas others are in the actual security API. The TwinCAT User Manager collects together the necessary functions in a COM object "TcUserManager". TcUserManager does not of course implement all functions of the NT security system, but only those functions that appear useful in a machine control system. If additional Windows NT functionality should be required in special circumstances, the appropriate Windows NT APIs can also be accessed directly, since Windows NT utilises the same user data bank as the TwinCAT User Manager.

Deployment

Ideally the machine control system starts up without a user having to log in. As a rule a standard user is automatically logged in and the operating interface is started up through TwinCAT. The standard user should only have restricted user privileges (those of a simple Window NT user) since he or she can otherwise execute alterations to the system (e.g. installation of drivers) that can lead to impairments of machine functions. If the execution of privileged functions (deletion of files, alteration of production sequences, alteration of the CNC program) should be necessary when the machine is operating under production conditions, a complete log out and relog into Windows NT must of course be avoided. Instead the operating interface process (in fact this is only one of the threads) can assume the status of a user with higher privileges (ImpersonateUser), or an additional process such as e.g. TwinCAT System Manager can be started from the operating interface using CreateProcessAsUser with the user account of an administrator. Each user in TwinCAT can belong to a number of user groups. In order to protect particular functions of the operating interface, access can be checked using either UserIsMemberOf or UserIsAdmin. At the present time the method UserIsMemberOf checks the user group on the basis of name, which means that problems associated with the language of the country can occur.In order to avoid these problems and moreover to have uniform user groups in the TwinCAT system, standard user groups are defined for TwinCAT.
- TcUsers
- TcPowerUsers
- TcAdministrators
These user groups are added as global Windows NT user groups through the TwinCAT installation to the Windows NT data base (this is yet to be implemented).

Note:

* Only TwinCAT 2.9 runs under Windows NT.


TcUserManager (CoClass)

The TwinCAT User Manager is implemented in the class TcUserManager. TcUserManager stacks directly onto the Windows NT user administration and can therefore offer all the security features of Windows NT. An important feature of the Windows NT security system is the option of either providing or withholding privileges for each operating system object (e.g. hard disk, file, network, …). Furthermore the users, user groups and their privileges can be propagated across the network.

The default interface of TcUserManager is called ITcUserManager, TcUserManager is implemented as "In Process Server" in the DLL "TCATUserMan.dll". For reasons of compatibility part of the functionality can also be attained through exported functions of the DLL. New applications should however use the COM interface ITcUserManager.


ITcUserManager

The interface ITcUserManager allows access to the TwinCAT User Manager. The TwinCAT User Manager is based on the Windows NT security system. An important feature of the Windows NT security system is the option of either providing or withholding privileges for each operating system object (e.g. hard disk, file, network, …). Furthermore the users, user groups and their privileges can be propagated across the network.

Methods in Vtable sequence

IUnknown Methods | Description
QueryInterface | Returns a pointer to the interface requested.
AddRef | Increments the reference counter.
Release | Decrements the reference counter.

IDispatch Methods | Description
GetTypeInfoCount | Supplies the number of "type information" interfaces, that an object offers. (0 or 1).
GetTypeInfo | Gets the type information for an object.
GetIDsOfNames | Connects names of methods with optional arguments with a corresponding set of DISPIDs.
Invoke | Offers access to properties and methods of an object.

ITcUserManager Methods | Description
CreateUserAccount | Creates a new user account.
CreateUserAccountDlg | Dialogue for generation of a new user account.
ImpersonateUser | The invoking thread impersonates the user denoted by name and password.
ImpersonateUserDlg | Dialogue with password query for impersonation of a user.
RevertToSelf | A previous impersonation is cancelled.
UserIsMemberOf | Checks whether the invoking thread is a member of the desired user group.
CreateProcessAsUser | Starts a process with the desired user account.
CreateProcessAsUserDlg | Dialogue for the start of a process with specified user account.
UserIsAdmin | Checks whether the invoking thread belongs to the administrators’ group.
UserName | Property for display of the current user name.
UserEnumLocalGroups | Returns the user groups of a user.
RemoveUserAccount | Removes a user account.
EnumLocalGroups | Returns the locally defined user groups.
EnumLocalUsers | Returns the locally defined users.


TwinCAT User Manager: Reference

ITcUserManager::ImpersonateUser

The invoking thread impersonates the user denoted by name and password.

HRESULT ImpersonateUser(
  BSTR bstrUserName,
  BSTR bstrPassword,
  VARIANT varDomain
);

Parameters

bstrUserName
[in]
Name of the user who is to be impersonated.
bstrPassword
[in]
Password of the user.
varDomain
[in, optional]
If the user belongs to a domain, there is an option here to provide the name of the appropriate domain. The parameter provided must be of BSTR type to be accepted.

Return Values

HRESULT == S_OK
User account has successfully been created.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror) or HRESULT_FROM_WIN32(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

The ImpersonateUser method assigns the „impersonation“ token of the desired user to the invoking thread. For this purpose the user is interactively logged in with user name and password and the created token is used for impersonation. After a successful execution of ImpersonateUser the thread has adopted the identity of the user. This can be reversed by calling the method RevertToSelf .


ITcUserManager::ImpersonateUserDlg

Dialogue to change the user while process is running.

HRESULT ImpersonateUserDlg()

Return Values

HRESULT == S_OK
User account has successfully been created.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

ImpersonateUserDlg calls up the ImpersonateUser method internally.


ITcUserManager::RemoveUserAccount

Removes a user account.

HRESULT RemoveUserAccount(
  BSTR bstrUserName,
  VARIANT serverName
);

Parameters

bstrUserName
[in]
Name of the user account that is to be removed.
varComputerName
[in, optional]
There is an option to provide the name of the computer as a BSTR. If no name is provided, the user account is removed from the local computer.

Return Values

HRESULT == S_OK
Removal executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.


ITcUserManager::RevertToSelf

A previous impersonation is cancelled.

HRESULT RevertToSelf();

Return Values

HRESULT == S_OK
User account has successfully been created.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror) or HRESULT_FROM_WIN32(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

The RevertToSelf method reassigns the „primary token“ of the process to the invoking thread. Thus RevertToSelf does not only cancel the last impersonation, but also after successive impersonations re-establishes the first user of the process.


ITcUserManager::CreateProcessAsUser

Starts a process with the desired user account.

HRESULT CreateProcessAsUser(
  BSTR bstrUserName,
  BSTR bstrPassword,
  BSTR bstrProcessPath,
  VARIANT varDomain
);

Parameters

bstrUserName
[in]
Name of the user account with which the process should be started.
bstrPassword
[in]
Password of the user account.
varDomain
[in, optional]
If the user belongs to a domain, there is an option here to provide the name of the appropriate domain. The parameter provided must be of BSTR type to be accepted.

Return Values

HRESULT == S_OK
Process has successfully been started.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror) or HRESULT_FROM_WIN32(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

The CreateProcessAsUser method starts a process with the privileges of the specified use. The process therefore has access to all objects (partitions, directories, files, networks, etc) that are released for the user in question. A particular feature appears in the case of Windows Explorer. Standard practice is that all Explorer windows belong to the same process. If a new instance of Explorer is started using CreateProcessAsUser, a conflict arises because the Explorer process that is already active belongs to another user account. The instance is shut down again without having been observed by the user. If it is therefore desired to start an instance of Explorer with another user account, the Explorer process that is running must firstly be terminated.


ITcUserManager::CreateProcessAsUserDlg

Dialogue to start a process with the specified user account.

HRESULT CreateProcessAsUserDlg()

Return Values

HRESULT == S_OK
The process has successfully been started.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

CreateProcessAsUserDlg calls up the CreateProcessAsUser method internally.


ITcUserManager::CreateUserAccount

Sets up a new local user account.

HRESULT CreateUserAccount(
  BSTR bstrUserName,
  BSTR bstrPassword,
  VARIANT varUserGroup,
  VARIANT varDomain
);

Parameters

bstrUserName
[in]
Name of the new user account.
bstrPassword
[in]
Character string for the desired password.
varUserGroup
[in, optional]
There is an option to specify a user group to which the new user account is to belong. The parameter provided must be of BSTR type to be accepted.
varDomain
[in, optional]
Similarly there is an option to provide the domain in which the new user account is to be created. The parameter provided must be of BSTR type to be accepted. At the present time this option is not yet supported.

Return Values

HRESULT = S_OK
User account has successfully been created.
HRESULT <> S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

Along with the new user account CreateUserAccount creates additional user privileges, that are required for further functions of the TwinCAT User Manager (e.g. CreateProcessAsUser).
The additional user privileges are:
SE_TCB_NAME "Act as part of the operating system". This privilege is required internally to log in a user.
SE_ASSIGNPRIMARYTOKEN_NAME "Replace process level token", is required for CreateProcessAsUser.
SE_INCREASE_QUOTA_NAME "Increase quotas", is also required for CreateProcessAsUser.


ITcUserManager::CreateUserAccountDlg

Dialogue for generation of a new user account.

HRESULT CreateUserAccountDlg()

Return Values

HRESULT == S_OK
User account has successfully been created.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

CreateUserAccountDlg calls up the CreateUserAccount method internally.


ITcUserManager::EnumLocalUsers

Returns the locally defined users.

HRESULT EnumLocalUsers(
  VARIANT varComputerName,
  SAFEARRAY(BSTR)* ppUsers
);

Parameters

varComputerName
[in, optional]
There is an option to provide the name of the target system as a BSTR. If no name is provided, the users are listed on the local computer.
ppUsers
[out, retval]
Pointer to SAFEARRAY of BSTRs, in which the names of the user groups are stored.

Return Values

HRESULT == S_OK
Query executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.


ITcUserManager::EnumLocalGroups

Returns the locally defined user groups.

HRESULT EnumLocalGroups(
  VARIANT varComputerName,
  SAFEARRAY(BSTR)* ppGroups
);

Parameters

varComputerName
[in, optional]
There is an option to provide the name of the target system as a BSTR. If no name is provided, the users are listed on the local computer.
ppGroups
[out, retval]
Pointer to SAFEARRAY of BSTRs, in which the names of the user groups are stored.

Return Values

HRESULT == S_OK
Query executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.


ITcUserManager::UserEnumLocalGroups

Returns the user groups to which a user belongs.

HRESULT UserEnumLocalGroups(
  VARIANT varUserName,
  SAFEARRAY(BSTR)* ppGroups
);

Parameters

varUserName
[in, optional]
There is an option to provide the name of the user as a BSTR. If no name is provided, the user of the invoking thread is queried.
ppGroups
[out, retval]
Pointer to SAFEARRAY of BSTRs, in which the names of the user groups are stored.

Return Values

HRESULT == S_OK
Query executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.


ITcUserManager::UserIsAdmin

Checks whether the invoking thread belongs to the administrators’ group.

HRESULT UserIsAdmin(
  VARIANT varUserName,
  VARIANT_BOOL* pbResult
);

Parameters

varUserName
[in]
Optional: Name of a user, provided as a BSTR. At the present time this option is not supported. The user status of the invoking thread is checked.
pbResult
[out, retval]
Pointer to a VARIANT_BOOL, in which the result of the query is to be stored.

Return Values

HRESULT == S_OK
Query executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.


ITcUserManager::UserIsMemberOf

Checks whether the invoking thread is a member of the desired user group.

HRESULT UserIsMemberOf(
  BSTR bstrUserGroup,
  VARIANT varUserName,
  VARIANT_BOOL* pbResult
);

Parameters

bstrUserGroup
[in]
Via the pointer pblsMemberOf.
varUserName
[in]
Optional name of a user provided as a BSTR.
pbResultc
[out, retval]
Pointer to a VARIANT_BOOL, in which the result of the query is to be stored.

Return Values

HRESULT == S_OK
Query executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.


ITcUserManager::UserName

Property for display of the current user name.

HRESULT UserName(
  BSTR* bstrUserName,
);

Parameters

bstrUserName
[out, retval]
Name of the user account to which the invoking thread belongs, provided as a pointer to a BSTR object.

Return Values

HRESULT == S_OK
Query executed successfully.
HRESULT != S_OK
If an error occurs an error code generated by Windows NT appears in HRESULT. In order to instigate a COM/OLE error handling sequence, an HRESULT is created from the error code from HRESULT_FROM_NT(nErrror). Here it should be noted that the Windows NT error code is displayed in low-order 16 bit format.

Comments

UserName displays the name of the user account to which the invoking thread belongs. This name can differ from the name of the user who is logged in.