The IdentityCriteriaType UserName requires a local verification of user name and password to be able to assign the corresponding role. Such users can be managed by the operating sytem or by the OPC UA Server.
The chapter defines a standard API for the management of a user list in the OPC UA Server.
Figure 2 depicts the ObjectTypes, Objects and their components used to represent the user management. The ServerConfiguration Object is defined in OPC 10000-12.
Figure 2 – User management overview
The UserManagement Object defined in 5.3 is a UserManagementType which is formally defined in Table 13.
Table 13 – UserManagementType definition
BrowseName |
UserManagementType |
||||
IsAbstract |
False |
||||
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Modelling Rule |
Subtype of BaseObjectType defined in OPC 10000-5 |
|||||
HasProperty |
Variable |
Users |
UserManagementDataType[] |
PropertyType |
Mandatory |
HasProperty |
Variable |
PasswordLength |
Range |
PropertyType |
Mandatory |
HasProperty |
Variable |
PasswordOptions |
PasswordOptionsMask |
PropertyType |
Mandatory |
HasProperty |
Variable |
PasswordRestrictions |
LocalizedText |
PropertyType |
Optional |
HasComponent |
Method |
AddUser |
Defined in 5.2.5. |
Mandatory |
|
HasComponent |
Method |
ModifyUser |
Defined in 5.2.6. |
Mandatory |
|
HasComponent |
Method |
RemoveUser |
Defined in 5.2.7. |
Mandatory |
|
HasComponent |
Method |
ChangePassword |
Defined in 5.2.8. |
Mandatory |
|
Conformance Units |
|||||
Security User Management Server |
The Property Users and the Methods AddUser, ModifyUser and RemoveUser contain sensitive security related information and shall only be readable and callable by authorized administrators through an encrypted channel.
The the ChangePassword Method requires an encrypted channel and can be called by the Session user if the user token type for the Session is not USERNAME.
The Users Property specifies the currently configured users and their settings as array of UserManagementDataType Structure defined in 5.2.4.
The Property PasswordLength defines the minimum and maximum length requirement for setting the password. A value of 0 for low indicates no limit for minimum and 0 for high indicates no limit for maximum password length. The Range DataType is defined in OPC 10000-8.
The Property PasswordOptions defines the password features and requirements for setting a password in a bit mask defined by the PasswordOptionsMask DataType. If the Server does not define any special requirements nor does not support enhanced features for the password management, all bits in the bit mask are set to false.
The Property PasswordRestrictions allows a Server to provide additional explanations about the rules applied to new passwords accepted by the Server.
The DataType PasswordOptionsMask is formally defined in Table 14.
Table 14 – PasswordOptionsMask values
Value |
Bit No. |
Description |
SupportInitialPasswordChange |
0 |
Indicates if the server supports the feature to require a password change after the creation of the user. |
SupportDisableUser |
1 |
Indicates if the server supports to disable a user. |
SupportDisableDeleteForUser |
2 |
Indicates if the server supports the configuration NoDelete for a user. |
SupportNoChangeForUser |
3 |
Indicates if the server supports the configuration NoChangeByUser for a user. |
SupportDescriptionForUser |
4 |
Indicates if the server supports to management of a description for the user. |
RequiresUpperCaseCharacters |
5 |
Indicates if an upper case ASCII character is required in a password. |
RequiresLowerCaseCharacters |
6 |
Indicates if a lower case ASCII character is required in a password. |
RequiresDigitCharacters |
7 |
Indicates if a digit ASCII character is required in a password. |
RequiresSpecialCharacters |
8 |
Indicates if a special character is required in a password. |
The PasswordOptionsMask representation in the AddressSpace is defined in Table 15.
Table 15 – PasswordOptionsMask definition
Attribute |
Value |
||||
BrowseName |
PasswordOptionsMask |
||||
IsAbstract |
False |
||||
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Others |
Subtype of UInt32 defined in OPC 10000-5 |
|||||
HasProperty |
Variable |
OptionSetValues |
LocalizedText [] |
PropertyType |
|
Conformance Units |
|||||
Security User Management Server |
The DataType UserConfigurationMask is formally defined in Table 16.
Table 16 – UserConfigurationMask values
Value |
Bit No. |
Description |
NoDelete |
0 |
The user cannot be deleted. |
Disabled |
1 |
The user is disabled. |
NoChangeByUser |
2 |
The user cannot change the password. |
MustChangePassword |
3 |
The user must change the password to get the assigned roles. The Method ChangePasssword defined in 5.2.8 is used to set a new password. |
The UserConfigurationMask representation in the AddressSpace is defined in Table 17.
Table 17 – UserConfigurationMask definition
Attribute |
Value |
||||
BrowseName |
UserConfigurationMask |
||||
IsAbstract |
False |
||||
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Others |
Subtype of UInt32 defined in OPC 10000-5 |
|||||
HasProperty |
Variable |
OptionSetValues |
LocalizedText [] |
PropertyType |
|
Conformance Units |
|||||
Security User Management Server |
This Structure DataType is used to provide the metadata for a field in a DataSet. The UserManagementDataType is formally defined in Table 18.
Table 18 – UserManagementDataType structure
Name |
Type |
Description |
UserManagementDataType |
Structure |
|
userName |
String |
Name of the user. |
userConfiguration |
UserConfigurationMask |
The configuration mask for the user. |
description |
String |
A description for the user. |
Its representation in the AddressSpace is defined in Table 19.
Table 19 – DataSetMetaDataType definition
Attributes |
Value |
BrowseName |
UserManagementDataType |
IsAbstract |
False |
Subtype of Structure defined in OPC 10000-5. |
|
Conformance Units |
|
Security User Management Server |
This Method is used to add a user to the user management of the Server.
The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.
Signature
AddUser (
[in]String UserName,
[in]String Password,
[in]UserConfigurationMaskUserConfiguration,
[in]String Description
);
Argument |
Description |
UserName |
The name of the user to add. |
Password |
The password for the user. |
UserConfiguration |
The configuration mask for the user. |
Description |
A description for the user. |
Method Result Codes
ResultCode |
Description |
Bad_AlreadyExists |
The user does already exist. |
Bad_OutOfRange |
The password is outside the valid range of accepted length and characters. |
Bad_NotSupported |
The UserConfiguration has flags set that are not supported by the Server. See PasswordOptions for flags supported by the Server. |
Bad_ConfigurationError |
The UserConfiguration has invalid combinations of flags set. |
Bad_UserAccessDenied |
The caller does not have the necessary Permissions. |
Bad_SecurityModeInsufficient |
The communication channel is not using encryption. |
Bad_ResourceUnavailable |
The Server does not have enough resources to add the user. |
This Method is used to modify a user in the user management of the Server.
If the UserConfiguration bit Disabled is changed to TRUE, all Sessions and Subscriptions associated with the disabled user shall be closed by the Server.
The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.
Signature
ModifyUser (
[in]String UserName,
[in]Boolean ModifyPassword,
[in]String Password,
[in]Boolean ModifyUserConfiguration,
[in]UserConfigurationMaskUserConfiguration,
[in]Boolean ModifyDescription,
[in]String Description
);
Argument |
Description |
UserName |
The name of the user to modify. |
ModifyPassword |
Flag indicating if the password should be changed. |
Password |
The password for the user. The password is set to a null or empty string if ModifyPassword is false. The argument is ignored if ModifyPassword is false. |
ModifyUserConfiguration |
Flag indicating if the user configuration should be changed. |
UserConfiguration |
The configuration mask for the user. The argument is ignored if ModifyUserConfiguration is false. |
ModifyDescription |
Flag indicating if the user description should be changed. |
Description |
A description for the user. The argument is ignored if ModifyDescription is false. |
Method Result Codes
ResultCode |
Description |
Bad_NotFound |
The user was not found in the user management. |
Bad_OutOfRange |
The password is outside the valid range of accepted length and characters. |
Bad_NotSupported |
The UserConfiguration has flags set that are not supported by the Server. See PasswordOptions for flags supported by the Server. |
Bad_ConfigurationError |
The UserConfiguration has invalid combinations of flags set. |
Bad_UserAccessDenied |
The caller does not have the necessary Permissions. |
Bad_SecurityModeInsufficient |
The communication channel is not using encryption. |
This Method is used to remove a user from the user management of the Server.
All Sessions and Subscriptions associated with the removed user shall be closed by the Server.
The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.
If the user of the Session used to call the Method is to be removed, the Method shall fail with Bad_InvalidSelfReference.
Signature
RemoveUser (
[in]String UserName
);
Argument |
Description |
UserName |
The name of the user to remove. |
Method Result Codes
ResultCode |
Description |
Bad_NotFound |
The specified user does not exist. |
Bad_UserAccessDenied |
The caller does not have the necessary Permissions. |
Bad_NotSupported |
The user cannot be deleted due to NoDelete user configuration mask setting. |
Bad_SecurityModeInsufficient |
The communication channel is not using encryption. |
Bad_InvalidSelfReference |
The user to remove is used by the Session used to call the Method. |
This Method is used to change the password of the user for the Session used to call the Method. The Method shall fail with Bad_InvalidState if the user token type for the Session is not USERNAME.
The bit MustChangePassword in the UserConfigurationMask defined in 5.2.3 indicates if the Server requires that the user changes the password.
If the user that is used to activate a Session is required to change the password, the Service ActivateSession shall return Good_PasswordChangeRequired and the activated Session shall have only the Role Anonymous. In this state, the Session shall be allowed to call ChangePassword for the user that activated the Session. After a successful call of ChangePassword, the Client is required to call ActivateSession with the user and the new password to apply the change and to get the Roles configured for the user.
Even if the Method is not browseable through a hierarchy for the Session user, it shall be accessible and callable by the Session user with the well defined NodeIds for the UserManagement Object and the ChangePassword Method.
This Method affects security and shall only be browseable and callable through an encrypted channel. It shall be callable by the Session user if the user token type for the Session is USERNAME, even if the Role for the user is Anonymous.
Signature
ChangePassword (
[in]String OldPassword,
[in]String NewPassword
);
Argument |
Description |
OldPassword |
The old password for the Session user. |
NewPassword |
The new password for the Session user. It is recommended that the user interface for entering the new password requires to enter the password twice to avoid typos. The Server can apply additional restrictions to the accepted password in addition to the one indicated by PasswordOptionMask. |
Method Result Codes
ResultCode |
Description |
Bad_IdentityTokenInvalid |
The old password is not valid. |
Bad_OutOfRange |
The new password is outside the valid range of accepted length and characters. |
Bad_InvalidState |
The caller is not authenticated with a USERNAME user token. |
Bad_NotSupported |
The password cannot be changed due to NoChangeByUser user configuration mask setting. |
Bad_SecurityModeInsufficient |
The communication channel is not using encryption. |
Bad_AlreadyExists |
The new password matches the old password. |
The UserManagement Object defined in Table 20 is used to manage users known to the Server.
Table 20 – UserManagement definition
BrowseName |
UserManagement |
||||
References |
Node Class |
BrowseName |
DataType |
TypeDefinition |
Modelling Rule |
ComponentOf the ServerConfiguration Object defined in OPC 10000-12 |
|||||
HasTypeDefinition |
ObjectType |
UserManagementType |
|
|
|
Conformance Units |
|||||
Security User Management Server |
______________