0% found this document useful (0 votes)

445 views

UMX User Manual

Uploaded by

NaveenKarthick

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

445 views

UMX User Manual

Uploaded by

NaveenKarthick

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 78

s Contents

UMX Overview 1
Concepts You Need to Know About 2
How to Display UMX Information 3
How to Create UMC Objects 4
How to Update UMC Objects 5
How to Retrieve Information about
6
UMC Objects
How to Display Lists of UMC or
7
User Management Component 1.9.1 Windows Objects

UMX User Manual

How to Delete UMC Objects 8
How to Perform Binding / Unbinding
9
Commands
How to Import / Export UMC Users
10
and Groups
How to Execute Administrative
11
Commands
How to Manage Account Policies 12
How to Execute Commands in
13
Interactive Mode
How to Execute Authentication
14
Commands
How to Manage Secure Application
15
Data Support
Error Codes 16
Parameter Sizes 17

04/2018
A5E39179300-AD
Guidelines

This manual contains notes of varying importance that should be read with care; i.e.:

Important:

Highlights key information on handling the product, the product itself or to a particular part of the documentation.

Note: Provides supplementary information regarding handling the product, the product itself or a specific part of
the documentation.

Trademarks

All names identified by ® are registered trademarks of Siemens AG.

The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes
could violate the rights of the owner.

Disclaimer of Liability

We have reviewed the contents of this publication to ensure consistency with the hardware and software
described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the
information in this publication is reviewed regularly and any necessary corrections are included in subsequent
editions.

Security information

Siemens provides products and solutions with industrial security functions that support the secure operation of
plants, systems, machines and networks. In order to protect plants, systems, machines and networks against
cyber threats, it is necessary to implement – and continuously maintain – a holistic, state-of-the-art industrial
security concept. Siemens’ products and solutions only form one element of such a concept.

Customer is responsible to prevent unauthorized access to its plants, systems, machines and networks. Systems,
machines and components should only be connected to the enterprise network or the internet if and to the extent
necessary and with appropriate security measures (e.g. use of firewalls and network segmentation) in place.

Additionally, Siemens’ guidance on appropriate security measures should be taken into account. For more
information about industrial security, please visit http://www.siemens.com/industrialsecurity.

Siemens’ products and solutions undergo continuous development to make them more secure. Siemens strongly
recommends to apply product updates as soon as available and to always use the latest product versions. Use of
product versions that are no longer supported, and failure to apply latest updates may increase customer’s
exposure to cyber threats.

To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed under http://www.
siemens.com/industrialsecurity.

Siemens AG A5E39179300-AD Copyright © Siemens AG 2018

Digital Factory 20180412_55713 Technical data subject to change
Postfach 48 48
90026 NÜRNBERG
GERMANY
Contents
1 UMX Overview ......................................................................................................................... 5
2 Concepts You Need to Know About...................................................................................... 7
2.1 User Manager User........................................................................................................... 7
2.2 User Manager Group ........................................................................................................ 8
2.3 User Manager Role........................................................................................................... 9
2.4 User Manager Function Rights ......................................................................................... 9

3 How to Display UMX Information ........................................................................................ 11

3.1 Help.................................................................................................................................. 11

4 How to Create UMC Objects ................................................................................................ 12

4.1 Create User..................................................................................................................... 12
4.2 Create Group .................................................................................................................. 14
4.3 Create Role..................................................................................................................... 15

5 How to Update UMC Objects ............................................................................................... 16

5.1 Update User.................................................................................................................... 16
5.2 Update Group ................................................................................................................. 18
5.3 Update User Alias ........................................................................................................... 19
5.4 Update User Attribute ..................................................................................................... 19

6 How to Retrieve Information about UMC Objects.............................................................. 21

6.1 List Entity Details ............................................................................................................ 21
6.2 List Event Log Records................................................................................................... 22

7 How to Display Lists of UMC or Windows Objects............................................................ 24

7.1 List Entities...................................................................................................................... 24
7.2 Count Entities.................................................................................................................. 25

8 How to Delete UMC Objects................................................................................................. 27

8.1 Delete Entity.................................................................................................................... 27

9 How to Perform Binding / Unbinding Commands ............................................................. 29

9.1 Add Attribute to User....................................................................................................... 29
9.2 Add Attribute to User - Size ............................................................................................ 30
9.3 Add a Set of Attributes to User ....................................................................................... 31
9.4 Add Alias to User ............................................................................................................ 32
9.5 Assign Group/Role to User ............................................................................................. 32
9.6 Assign Role to Group...................................................................................................... 33
9.7 Assign Function Right to Role......................................................................................... 34
9.8 Remove User from Group/Role ...................................................................................... 35
9.9 Remove Role from Group ............................................................................................... 35
9.10 Remove Attribute from User ......................................................................................... 36
9.11 Remove Alias from User ............................................................................................... 37

User Management Component 1.9.1 - UMX User Manual

iii
A5E39179300-AD
9.12 Remove Function Right from Role................................................................................ 38

10 How to Import / Export UMC Users and Groups .............................................................. 39

10.1 Import Entities from File ................................................................................................ 39
10.2 Import Windows Local Users ........................................................................................ 42
10.3 Import Active Directory Users ....................................................................................... 43
10.4 Import Active Directory Groups..................................................................................... 44
10.5 Import Package - UMC Fully Configured ...................................................................... 44
10.6 Export Entities to File .................................................................................................... 47
10.7 Export Package............................................................................................................. 47
10.8 Update via Package...................................................................................................... 48

11 How to Execute Administrative Commands..................................................................... 50

11.1 Set User Password ....................................................................................................... 50
11.2 Enable User .................................................................................................................. 51
11.3 Disable User.................................................................................................................. 51
11.4 Unlock User................................................................................................................... 52
11.5 Disable Safe Mode........................................................................................................ 53
11.6 Show Status .................................................................................................................. 53
11.7 Get Domain Identifier .................................................................................................... 56
11.8 Get Domain Name ........................................................................................................ 56

12 How to Manage Account Policies ..................................................................................... 58

12.1 Modify Account Policies - Passwords ........................................................................... 58
12.2 Modify Account Policies - Associate UMC User with Provisioning Service .................. 59
12.3 Modify Account Policies - Restore ................................................................................ 60
12.4 Modify Account Policies - Set Default PKI Rule............................................................ 61
12.5 Modify Account Policies - Reset Default PKI Rule........................................................ 62
12.6 Modify Account Policies - Secure Application Data Support......................................... 62

13 How to Execute Commands in Interactive Mode ............................................................. 63

13.1 Interactive Mode ........................................................................................................... 63
13.2 Enable Notifications ...................................................................................................... 63

14 How to Execute Authentication Commands .................................................................... 65

14.1 Test Authentication........................................................................................................ 65
14.2 Generate Ticket ............................................................................................................ 66
14.3 Change User Password ................................................................................................ 66

15 How to Manage Secure Application Data Support .......................................................... 68

15.1 Enable Encryption......................................................................................................... 68
15.2 Encrypt Keys................................................................................................................. 69
15.3 Decrypt Keys................................................................................................................. 70

16 Error Codes ......................................................................................................................... 71

16.1 UMC APIs Error Codes................................................................................................. 71

17 Parameter Sizes .................................................................................................................. 78

User Management Component 1.9.1 - UMX User Manual

iv
A5E39179300-AD
1 UMX Overview
The umx utility can be used to manage users, groups, roles and account policies of the User
Management Component (UMC). According to the selected options (switches) and the related
parameters, the utility allows you to execute different commands. When describing the commands, we
do not provide an explicit description of the switches when they identify the parameter they precede.

This utility is distributed with UMC and it is installed in the subdirectory \BIN of the 64 and 32 bit
installation folder. It must be executed from a command prompt within this directory.

In addition, the execution of a umx command can be performed interactively, see interactive
command.

Important:

As umx is a command line utility, if you want to insert a parameter with blank spaces you
have to enclose it between double quotes.

Users Allowed to Execute umx Commands

The execution of a umx command can be performed according to two login modes:

• current user: the user that performs the UMC command is the Windows user which has
launched the windows command prompt;
• specified user: the user that performs the UMC command is explicitly inserted in the command
line; -x switch has to be inserted as first parameter when launching the command; username
and password have to be inserted as second and third parameter.

Regardless of the login mode which is used the execution of commands is limited according to the
function rights of the user, for example:

• if the User Manager user owns the UM_ADMIN function right, they can execute all the umx
commands;
• users who own the UM_VIEW function right can only execute commands which access the
database with read only access rights;
• users who own the UM_VIEW function right plus the User Manager function right that is
required for the specific of the action can execute the relative action.

See User Manager Function Rights for a list of UM function rights.

The following diagram presents the UMC object model whose understanding helps in using the umx
utility.

User Management Component 1.9.1 - UMX User Manual

5
A5E39179300-AD
1 UMX Overview

User Management Component 1.9.1 - UMX User Manual

6
A5E39179300-AD
2 Concepts You Need to Know About
The following concepts are the basics you need to know before you start configuring UMC:

• UM User
• User Manager Group
• User Manager Role
• User Manager Function Rights

2.1 User Manager User

A User Manager user (UM user in what follows) is a user in the User Manager Component database,
identified by a user name. Note that UM users are different entities with respect to Windows users,
which are defined at operating system level.

Custom attributes can be associated with UM users. Example of custom attributes are common user
properties such as phone number, department, and so on.
To apply Secure Application Data Support (SADS), access to encrypted application data can be
granted to authorized users to allow them to decrypt it using specific Subject Keys.

UM User Types

You can distinguish three types of UM users:

• users created from scratch in UMC or created via csv file;

• Windows local users that are imported into UMC (via umx): in this case the user name follows
the pattern <machineName>\<localUserName>;
• Active Directory users that are imported into UMC (via umx or via Web UI): in this case the
user name follows the pattern <ADdomainName>\<ADuserName>.

UM User Passwords

Users created within UMC have also an associated password. Empty passwords are not allowed.
Users imported from Windows authenticate against Windows and do not have a UMC password.
Imported Windows local users authenticate only locally against Windows on the machine where they
are present. They can be used only for configuration purposes, for instance to be associated with a
Windows service running on the machine.

Offline Users

When you create a UMC user you can flag the user as offline. UMC provisioning service checks if the
offline user exists in Active Directory:

User Management Component 1.9.1 - UMX User Manual

7
A5E39179300-AD
2 Concepts You Need to Know About
2.2 User Manager Group

• if the user is present, user data are synchronized and the user becomes online,
• otherwise the user remains offline.

Important:

Users created as offline are enabled by design: they can therefore perform the actions
allowed by their function rights.

The user name of offline users must follow the AD pattern <domainName>\<ADuserName>. They do
not have a UMC password, as they cannot authenticate until they become online. The User Security
Identifier (SID, see Microsoft Documentation on Security Identifiers for more details) property is set to a
default value (S-1-0-0) that is synchronized with the actual AD value by the UMC provisioning service.

Users are also flagged offline if they are deleted from AD. In this case users are permanently deleted
from UMC database after an amount of time that can be configured (default is12 hours). See the
additional provisioning configuration in the User Management Component Installation Manual for more
details.

2.2 User Manager Group

A User Manager group (UM group in what follows) is a container of users and is identified by a name.
Note that UM groups are different entities with respect to Windows groups that are defined at operating
system level.

To apply Secure Application Data Support (SADS), access to encrypted application data can be
granted to authorized groups to allow them to decrypt it using specific Subject Keys.

UM Group Types

There are two types of UM groups:

• groups created from scratch in UMC or created via csv file;

• Active Directory groups that are imported into UMC (via umx or via Web UI).

Offline Groups

When creating a UMC group, you can flag the group as offline. UMC provisioning service checks if the
offline group exists in Active Directory:

• if the group is present, group data are synchronized, the AD users members of the groups are
imported into UMC and the group becomes online,
• otherwise the group remains offline.

The group name of offline users must follow the AD pattern <ADdomainName>\<ADgroupName>.

User Management Component 1.9.1 - UMX User Manual

8
A5E39179300-AD
2 Concepts You Need to Know About
2.3 User Manager Role

2.3 User Manager Role

A User Manager role (UM role in what follows) groups a set of function rights. Function rights are the
capabilities to perform operations. They are associated with roles so that the set of UM users having a
specific UM role is allowed to perform the set of operations associated with it. UM roles can be
associated with UM users or with UM groups so that all the users belonging to such groups inherit the
UM role function rights. UM roles are used to define the function rights within UMC, for instance, to
define whether a user can configure UMC or not.

The following roles are automatically created by the system while configuring UMC:

• Administrator: built-in "root" role, can perform any operation. The user that has this role is a
root user that can perform any operation. This role cannot be associated with any group. It can
be associated with a user if the user performing the association has in turn the Administrator
role. The Administrator role cannot be deleted. Only users having the Administrator role can
modify other users having this role.
• UMC Admin: can manage users, groups and all the other UMC entities.
• UMC Viewer: can access the user management configuration without making modifications.

2.4 User Manager Function Rights

Function rights are the capabilities to perform operations. They are associated with roles so that the
set of UM users having a specific UM role is allowed to perform the set of operations associated with it.
The following table contains a list of UM Function Rights:

Name Description

UM_ADMIN Allows you to display the UMC database data and to configure the UMC
database, that is to create users, groups and so on, to import and export data
via file, to register UMC station clients. This function right allows you to execute
all umx commands.

UM_VIEW Allows you to display the UMC database data related to users, groups, roles
and account policies.

UM_RESETPWD The user can reset the password of another user. The user must also have
associated the UM_VIEW function right.

UM_UNLOCKUSR The user can unlock any other user. The user must also have associated the
UM_VIEW function right.

UM_ATTACH The user can attach a machine to a UM domain, the machine is promoted to the
UM agent role.

UM_JOIN The user can promote a machine to a UM server role. If the machine is not yet
attached to the UM domain, it is attached. This function right incorporates the
UM_ATTACH function right.

UM_RESETJOIN The user can downgrade a machine from the UM ring server or UM server role
to the UM agent role.

User Management Component 1.9.1 - UMX User Manual

9
A5E39179300-AD
2 Concepts You Need to Know About
2.4 User Manager Function Rights

Name Description

UM_IMPORT The user can import the UM Configuration via package. The user must also
have associated the UM_VIEW function right.

UM_EXPORT The user can export the UM Configuration into a package. The user must also
have associated the UM_VIEW function right.

UM_BACKUP The user can back up the UM Configuration (Full backup). This function right is
not used, as the functionality controlled by it has not yet been implemented.

UM_EXPORTCK The user can export Claim Key. This function right is not used, as the
functionality controlled by it has not yet been implemented.

UM_EXPORTDK The user can export Domain Key. This function right is not used, as the
functionality controlled by it has not yet been implemented.

UM_RA Login from Remote Authentication. This function right is not used, as the
functionality controlled by it has not yet been implemented.

UM_RINGMNG The user can promote a machine to a UM ring server role. If the machine is not
yet attached to the UM domain, it is attached.

UM_ADSYNC The user can perform the background AD provisioning synchronization.

UM_VIEWELG The user can display event logging data. The user must also have associated
the UM_VIEW function right.

UM_CLAIMAUTH The user can create an identity from a valid claim.

UM_REGCLIENT The user can register UMC station clients.

User Management Component 1.9.1 - UMX User Manual

10
A5E39179300-AD
3 How to Display UMX Information
The following command can be used to display information on UMX commands.

• Help

3.1 Help
This command displays the first level of help or the details of the different commands depending on the
input parameters.

Syntax

umx -h [command]

Parameters

• command can be one of the command categories displayed launching umx -h; examples are
create, update, etc.

User Management Component 1.9.1 - UMX User Manual

11
A5E39179300-AD
4 How to Create UMC Objects
The following commands can be used to create UMC objects such as users, groups and roles.

• Create User
• Create Group
• Create Role

4.1 Create User

This command creates a new UM user setting the necessary parameters. To enable the user
parameter override lock, you have to create the user and then perform a user update.

Syntax

Create users

umx [-x commandUserName commandUserPassword] -c -u name -p password [-f

fullName] [-m paramMustPwd] [–C paramCanPwd] [–l paramLock] [-e paramEnabled]

Create offline users

Users created as offline are enabled by design.

umx [-x commandUserName commandUserPassword] -c -u name -off

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• name is the string representing the user name, only alphanumeric characters are allowed.
• fullName is the string representing the user full name, for instance the pair Name and Surname.

User Management Component 1.9.1 - UMX User Manual

12
A5E39179300-AD
4 How to Create UMC Objects
4.1 Create User

• password is the password associated to the user. Empty passwords are not allowed. The
password specified for the user via this command is not forced to comply with password
policies.
• paramMustPwd allows the values 0 or 1. If set to 1, the user is forced to change the password
at first login, if set to 0 the user is not forced to change the password at first login. Default value
is 0.
• paramCanPwd allows the values 0 or 1. If set to 1 the user can change the password, if set to 0
the user cannot change the password. Default value is 0.
• paramLock allows the values 0 or 1. If set to 1 the user is locked and cannot perform any action.
If set to 0 the user is unlocked and can perform the actions according to the associated function
rights. The user can be locked by the system when attempting to login several times with a
wrong password, the number of allowed attempts is established by the security policies. Default
value is 0.
• paramEnabled allows the values 0 or 1. If set to 0 the user cannot perform any action, if set to 1
the user is enabled and can perform the actions according to the associated function rights.
Default value is 0.

Parameter Behavior

The following table presents the different behaviors of the application depending on the values of the
paramMustPwd and paramCanPwd parameters.

paramMustPwd paramCanPwd Behavior

value value

0 0 The user cannot change the password.

0 1 The user can change the password whenever he/she wants.

1 0 The user must change the password at first login. Afterwards,

he/she cannot change the password anymore.

1 1 The user must change the password at first login. Afterwards,

he/she can change the password whenever he/she wants.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-off If specified, the user is created as an offline user. For more details on offline users see User
Manager User.

Examples

umx -c -u myUser -f "Peter Brown" -p default123 -m 1 -C 1 -l 0 -e 1

User Management Component 1.9.1 - UMX User Manual

13
A5E39179300-AD
4 How to Create UMC Objects
4.2 Create Group

The command above creates the user myUser with full name Peter Brown, password default123. The
user have to change the password at first login, is unlocked and enabled.

umx –c –u DOM\userOFF –off

The command above creates the offline user DOM\userOFF, with all the flags set to 0.

umx –c –u userOn –p a

The command above creates the offline user userOn, password a and with all the flags set to 0.

4.2 Create Group

This command creates a new UM group.

Syntax

umx [-x commandUserName commandUserPassword] -c -g name –d description [-off]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• name is the string representing the group name, only alphanumeric characters are allowed.
• description is the string containing a short description of the group. This field is optional if the
group is created offline.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-off If specified the group is created as an offline group. For more details on offline groups see
User Manager Group.

User Management Component 1.9.1 - UMX User Manual

14
A5E39179300-AD
4 How to Create UMC Objects
4.3 Create Role

4.3 Create Role

This command creates a new UM role. The number of roles present in the system cannot exceed
36200.

In addition a database constraint on the role identifiers exists. In case you get an error message that
no more role identifiers are available, to create new roles, you have first to purge the existing one with
the corresponding umconf command. See the UMCONF User Manual for more details.

Syntax

umx [-x commandUserName commandUserPassword] -c -r name –d description

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• name is the string representing the role name, only alphanumeric characters are allowed.
• description is the string containing a short description of the role.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

15
A5E39179300-AD
5 How to Update UMC Objects
The following commands can be used to update UMC objects such as users, user attributes or groups.

• Update User
• Update Group
• Update User Alias
• Update User Attribute

5.1 Update User

This command updates an existing UM user. Note that at least one of the UM user properties must be
updated.

When editing user which have been imported into UMC from active directory or windows, see
Limitations on imported users.

Syntax

umx [-x commandUserName commandUserPassword] -U -u user [-s (use username

instead of userId)] [–e expirationDate] [-ae alertOnExDays] [-p pwdDays]
[-ap alertOnPwdExDays] [-al autologoffMinutes] [-wa
warningOnAutologoffMinutes] [-la language] [-da dataLanguage] [-fu fullname]
[-co comment] [-em emailAddress] [-o paramOverrideLock]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
• expirationDate is the account expiration date in Unix time format.
• alertOnExDays is the number of days from which a warning appears to the user notifying him/
her about the user expiration.
• pwdDays is the number of days for which the password is valid, max 1828 days.
• alertOnPwdExDays is the number of days from which a warning appears to the user notifying
him/her about the password expiration.

User Management Component 1.9.1 - UMX User Manual

16
A5E39179300-AD
5 How to Update UMC Objects
5.1 Update User

• autologoffMinutes is the number of minutes that must elapse before a user is automatically
logged off from the system (session-based).
• warningOnAutologoffMinutes is the number of minutes that must elapse before a warning
appears to a user to inform that he/she will be logged off from the system (session-based).
• language is the user language and has the format <langcode>-<countrycode> (for example en-
GB) where:
– langcode is the language code according to the ISO 639 standard; we accept both two-
letter codes (ISO 639-1) and three-letter codes (ISO 639-2);
– countrycode is the country code according to the ISO 3166 standard.

• dataLanguage is the language the language in which are displayed the user data, see above for
the language.
• fullname is the user Full Name (include in doublequotes if it contains spaces, e.g. -fu "Full
Name")
• comment is the user comment (include in doublequotes if it contains spaces, e.g. -co "This User
is Used Only For Test")
• emailAddress is the user email address
• paramOverrideLock allows the values 0 or 1. If set to 1 the user cannot be locked. If set to 0 the
user can be locked. For instance, the user can be locked by the system when attempting to
login several times with a wrong password, the number of allowed attempts is established by
the security global account policies. In case of value set to 1, even though the user attempts to
login several times with a wrong password, he/she is not locked.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-s After the "-u" switch the user name must be entered instead of the numeric user Id.

Update Limitations on Imported Users

User which have been imported from Active direct and Windows local users can be updated from the
UMX but the following limitations apply:

UMX Parameter UMC Web Name AD Name UMC Active Windows

users Directory Local

expirationDate User Expiration Date N/A

alertOnExDays Alert when user is about to N/A

expire

pwdDays Password Duration (days) N/A

alertOnPwdExDays Alert when password is N/A

about to expire

language Language N/A

User Management Component 1.9.1 - UMX User Manual

17
A5E39179300-AD
5 How to Update UMC Objects
5.2 Update Group

UMX Parameter UMC Web Name AD Name UMC Active Windows

users Directory Local

dataLanguage Data Language N/A

fullname Full Name Common

Name

comment Comment Description

N/A Initials Initials

emailAddress Email 1 Email

paramOverrideLock Override Lock Policy on N/A

invalid credentials

UMC Attributes and UMC Attributes and their N/A

their values values

User Alias User Alias N/A

5.2 Update Group

This command updates an existing UM group. Note that at least one of the UM group properties must
be updated.

Syntax

umx [-x commandUserName commandUserPassword] -U(pdate) -g(roup) <Id|name>

[-s (use name instead of Id)][-d(escription) <Description>][-o(verride user
lock) <0|1>]

Parameters

User Management Component 1.9.1 - UMX User Manual

18
A5E39179300-AD
5 How to Update UMC Objects
5.3 Update User Alias

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-s After the "-u" switch the user name must be entered instead of the numeric user Id.

5.3 Update User Alias

This command modifies a user alias.

Syntax

umx [-x commandUserName commandUserPassword] -U -a -v aliasName -u user [-s

(use username instead of userId)]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• aliasName is a string representing the alias name;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

5.4 Update User Attribute

This command updates the value of an existing attribute of a UM user. The user attribute
USER_USNCHANGED is used by UMC provisioning for UMC AD users. If you set the value to 0 the
user fields are synchronized with AD fields.

User Management Component 1.9.1 - UMX User Manual

19
A5E39179300-AD
5 How to Update UMC Objects
5.4 Update User Attribute

Syntax

umx [-x commandUserName commandUserPassword] -U -A attributeName -v

attributeNewValue -u userId

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• attributeName is a string representing the attribute name;
• attributeNewValue is the attribute value;
• userId is a positive number representing the internal identifier of the record representing the UM
user to which the given attribute and its value are associated; to retrieve the user identifier see
List Entity Details.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

20
A5E39179300-AD
6 How to Retrieve Information about UMC Objects
The following commands can be used to retrieve information about UMC objects such as users,
groups, roles or AT records.

• List Entity Details

• List Event Log Records

6.1 List Entity Details

This command lists the details of the selected entity (user, group, role). It can be used to retrieve the
entity identifier from the entity name.

Syntax

umx [-x commandUserName commandUserPassword] -i {–u user [-s]| -g group [-s]

| -r role [-s][-v]}

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
• group represents the group name if the switch –s is present, represents the group internal
identifier if the switch –s is not present, the identifier is a positive number univocally identifying
the record;
• role represents the role name if the switch –s is present, represents the role internal identifier if
the switch –s is not present, the identifier is a positive number univocally identifying the record;
optional switch -v shows groups and users which have been assigned to the specified role

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

21
A5E39179300-AD
6 How to Retrieve Information about UMC Objects
6.2 List Event Log Records

-s If the switch –s is present, objects are identified by their name. If the switch –s is not
present, objects are identified by their internal identifier. The identifier is a positive number
univocally identifying the record.

-v Displays extended information on role (list of users and groups assigned to the role)

Important:

When using the -v switch to display the role details, listing users can take several
minutes; this is due to the lack of a direct link between the role entity and the user entity.

6.2 List Event Log Records

This command lists the event log records related to an input date, for the entire day starting from 00:
01. The limit is set to 1001 records per day. to retrieve all the records for a day you have to use the
switch -f.

Syntax

umx [-x commandUserName commandUserPassword] -i -at time [-f ]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• time is the date in Unix time format of the day for which you wish to the event log records. The
string now represents the current date. As an example, the Unix time 1460939793 corresponds
to ISO 8601: 2016-04-18T00:36:33Z.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-f Forces the dump of all the records of the specified day to a file with name <unixtime>.dat
which is saved in the location from which UMX is being launched.

User Management Component 1.9.1 - UMX User Manual

22
A5E39179300-AD
6 How to Retrieve Information about UMC Objects
6.2 List Event Log Records

Example

Two command examples follow.

umx –i –at now

umx –i –at 1450259593

umx –i –at 1460279589 -f

in the last example umx create a file with name 1460279589.dat with all records about Sun, 10 Apr
2016 09:13:09 GMT

An example of the output follows.

---- AT Records 1 ----

AT Record {
"timestamp": "2015-12-1613:44:23.0+0100",
"source": "",
"username": "SWQA\\itre0043",
"action": "login error",
"value": {
"result":4
}
}
Time taken: 0.02s

User Management Component 1.9.1 - UMX User Manual

23
A5E39179300-AD
7 How to Display Lists of UMC or Windows Objects
The following commands can be used to display a list of UMC or Windows objects such as users,
groups, roles, function rights or account policies.

• List Entities
• Count Entities

7.1 List Entities

This command lists the set of entities, their details stored in the database depending on the selected
switch. For the users also the attributes and their values are displayed.

Syntax

umx [-x commandUserName commandUserPassword] -l {-u [-v] | -wu | -du

searchStringUsers | -g | -dg searchStringGroups | -r | -f | -a | -d
domainName}

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• searchStringUsers filters the Active Directory users to be listed, the "*" wildcard can be used,
the search field is the user name.
• searchStringGroups filters the Active Directory groups to be listed, the "*" wildcard can be used,
the search field is the group name.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-u Displays the list of UM users.

-v If this switch is present, more user details are displayed.

-wu Displays the list of Windows local users.

User Management Component 1.9.1 - UMX User Manual

24
A5E39179300-AD
7 How to Display Lists of UMC or Windows Objects
7.2 Count Entities

-du Displays the list of Active Directory users belonging to the domain to which the local
machine is joined filtered by the search string. The first field displayed is used to import
purposes. The domain name has to be specified with -d domainName switch.

-g Displays the list of UM groups.

-dg Displays the list of Active Directory groups belonging to the domain to which the local
machine is joined filtered by the search string. The first field displayed is used to import
purposes. The domain name has to be specified with -d domainName switch.

-r Displays the list of UM roles.

-f Displays the list of UM function rights.

-a Displays the list of UM account policies. Note that the user associated to the provisioning
service is stored as an account policy and is displayed in this list.

-d Displays the list of Windows domains.

Example

umx -l -du ross*

The command above displays the list of Active Directory users belonging to the domain to which the
local machine is joined whose user name starts with the string "ross".

7.2 Count Entities

This command lists the number of the different main entities stored in the database: number of UM
users, number of UM roles, number of UM groups and number of function rights.

Syntax

umx [-x commandUserName commandUserPassword] -k

Parameters

User Management Component 1.9.1 - UMX User Manual

25
A5E39179300-AD
7 How to Display Lists of UMC or Windows Objects
7.2 Count Entities

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

26
A5E39179300-AD
8 How to Delete UMC Objects
The following command can be used to delete UMC objects such as users, groups or roles.

• Delete Entity

8.1 Delete Entity

This command deletes the entity given in input.

Syntax

umx [-x commandUserName commandUserPassword] -d {-u user | -g group | -r

role | -a} [-f][-s]

Parameters

• group represents the group name if the switch –s is present; it represents the group internal
identifier if the switch –s is not present. The identifier is a positive number univocally identifying
the record;
• role represents the role name if the switch –s is present, represents the role internal identifier if
the switch –s is not present, the identifier is a positive number univocally identifying the record;

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-a All the UM users, groups and roles are deleted except for the UM user launching the
command, the UM administrator and the Administrator role.

User Management Component 1.9.1 - UMX User Manual

27
A5E39179300-AD
8 How to Delete UMC Objects
8.1 Delete Entity

-f Forces the deletion of the user launching the command.

User Management Component 1.9.1 - UMX User Manual

28
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
The following commands can be used to perform binding or unbinding operations on UMC objects
such as adding/removing a user to a group/role, adding/removing user attributes or adding/removing
function rights to a role.

Binding Commands

• Add Attribute to User

• Add Attribute to User - Size
• Add a Set of Attributes to User
• Add Alias to User
• Assign Group/Role to User
• Assign Role to Group
• Assign Function Right to Role

Unbinding Commands

• Remove User from Group/Role

• Remove Role from Group
• Remove Attribute from User
• Remove Alias from User
• Remove Function Right from Role

9.1 Add Attribute to User

This command adds an attribute and its value to a UM user.

Syntax

umx [-x commandUserName commandUserPassword] -a -A attributeName -v

attributeValue -u user [-s (use username instead of userId)]

User Management Component 1.9.1 - UMX User Manual

29
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.2 Add Attribute to User - Size

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• attributeName is a string representing the attribute name;
• attributeValue is the attribute value;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.2 Add Attribute to User - Size

This command is only for testing purposes. It adds an attribute of a predefined size to a UM user. A
default value is given to the attribute.

Syntax

umx [-x commandUserName commandUserPassword] -a –A attributeName -S size -u

user [-s (use username instead of userId)]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• attributeName is a string representing the attribute name;
• size is the attribute size in bytes;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details .

User Management Component 1.9.1 - UMX User Manual

30
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.3 Add a Set of Attributes to User

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.3 Add a Set of Attributes to User

This command is only for testing purposes. It adds a set of attributes of a given size to a UM user. A
default value is given to the attributes.

Syntax

umx [-x commandUserName commandUserPassword] -a –A namePrefix -n number –S

size -u user [-s (use username instead of userId)]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• namePrefix is the prefix used for the name of the set of attributes;
• number is the number of attributes to add;
• size is the attribute size in bytes;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details .

Example

umx -a -A testAtt –n 10 –s 20 -u myUser

The command above creates ten attributes for the user myUser. The attributes are named testAtt1,
testAtt2, and so on, the size of each attribute is 20 bytes.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

31
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.4 Add Alias to User

9.4 Add Alias to User

This command adds an alias to a UM user. Only one alias per user is currently supported.

Syntax

umx [-x commandUserName commandUserPassword] -a -a -v aliasName -u user [-s

(use username instead of userId)]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• aliasName is a string representing the alias name;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.5 Assign Group/Role to User

This command adds a user to a group or assigns a role to a user.

Syntax

umx [-x commandUserName commandUserPassword] -a -u user {-g group| -r role}

[-s]

User Management Component 1.9.1 - UMX User Manual

32
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.6 Assign Role to Group

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
• group represents the group name if the switch –s is present; it represents the group internal
identifier if the switch –s is not present. The identifier is a positive number univocally identifying
the record;
• role represents the role name if the switch –s is present, represents the role internal identifier if
the switch –s is not present, the identifier is a positive number univocally identifying the record;

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.6 Assign Role to Group

This command assigns a role to a group.

Syntax

umx [-x commandUserName commandUserPassword] -a -g group -r role [-s]

Parameters

User Management Component 1.9.1 - UMX User Manual

33
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.7 Assign Function Right to Role

• role represents the role name if the switch –s is present, represents the role internal identifier if
the switch –s is not present, the identifier is a positive number univocally identifying the record;

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.7 Assign Function Right to Role

This command assigns a function right to a role.

Syntax

umx [-x commandUserName commandUserPassword] -a –f functionRightName -r role

[-s]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• functionRightName is the name of a UM function right. For the list of the UM function rights see
User Manager Function Rights.
• role represents the role name if the switch –s is present, represents the role internal identifier if
the switch –s is not present, the identifier is a positive number univocally identifying the record;

Switches

Switch Description

-x The command is executed by the user given as input parameter..

User Management Component 1.9.1 - UMX User Manual

34
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.8 Remove User from Group/Role

9.8 Remove User from Group/Role

This command removes a UM user from a group or deletes the association of a UM role to a UM user.

Syntax

umx [-x commandUserName commandUserPassword] -R -u user {-g group | -r role}

[-s]

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.9 Remove Role from Group

This command deletes the association of a role to a group.

User Management Component 1.9.1 - UMX User Manual

35
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.10 Remove Attribute from User

Syntax

umx [-x commandUserName commandUserPassword] -R -g group -r role [-s]

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.10 Remove Attribute from User

This command removes an attribute and its value from a user.

Syntax

umx [-x commandUserName commandUserPassword] -R -A attributeName -u userId

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;

User Management Component 1.9.1 - UMX User Manual

36
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.11 Remove Alias from User

• commandUserPassword is the string representing the password of the user that is executing the
command;
• attributeName is a string representing the attribute name;
• userId is a positive number representing the internal identifier of the record representing the UM
user to which the given attribute and its value are associated; to retrieve the user identifier see
List Entity Details .

Switches

Switch Description

-x The command is executed by the user given as input parameter.

9.11 Remove Alias from User

This command removes the alias from a user.

Syntax

umx [-x commandUserName commandUserPassword] -R -a -u userId [-s (use

username instead of userId)]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• userId is a positive number representing the internal identifier of the record representing the UM
user to which the given attribute and its value are associated; to retrieve the user identifier, see
List Entity Details.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

37
A5E39179300-AD
9 How to Perform Binding / Unbinding Commands
9.12 Remove Function Right from Role

9.12 Remove Function Right from Role

This command deletes the association of a function right to a role.

Syntax

umx [-x commandUserName commandUserPassword] -R -f functionRightName –r role

[-s]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• functionRightName is the name of a UM function right. For the list of UM function rights see
User Manager Function Rights .
• role represents the role name if the switch –s is present, represents the role internal identifier if
the switch –s is not present, the identifier is a positive number univocally identifying the record;

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

38
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
The following commands can be used to perform import or export operations such as importing\
exporting users/groups from/to a csv file, importing Windows local users, importing Active Directory
users/groups or importing\exporting a UMC package to/from a file.

Import Commands

• Import Entities from File

• Import Windows Local Users
• Import Active Directory Users
• Import Active Directory Groups
• Import Package - UMC Fully Configured

Export Commands

• Export Entities to File

• Export Package
• Update via Package

10.1 Import Entities from File

This command imports a set of users or groups into the UMC database. If the user/group is an existing
user/group in the UMC database, the corresponding record is updated, if the user/group does not exist
it is inserted.

The format of the file to import users/groups is csv (Comma Separated Values). The first row of the csv
file must contain the column names, the following lines must contain the corresponding values
semicolon separated.

CAUTION:

The order of the column of the file must be as they are listed.

The table below lists the record names and descriptions for the import of users. The insertion of a user
whose group does not exist fails. As a consequence, before importing the users, you have to import
their groups.

Name Description

Name User name.

Password User password. This field is empty in case of export.

User Management Component 1.9.1 - UMX User Manual

39
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.1 Import Entities from File

Name Description

Full Full user name.

Name

Groups List of group names to which the user belongs separated by ",". Example: group1,
group2,group3. If the group does not exist binding is not performed; no error is returned.

Email User email.

Language User language.

Data User data language.

Language

Status A bit mask representing the following flags:

• USER_IS_ENABLED
• USER_IS_LOCKED
• USER_IS_IMPORTED: indicates that the user has been imported from AD. Note
that this information is significant only in case of export.
• USER_HAS_EXPIRATION_DATE
To set a flag to true the character "x" has to be inserted in the corresponding position,
otherwise the character "-" has to be inserted. Example: x-x denotes a user which is
enabled, is not locked, is not imported and has an expiration date. The expiration date is
stored in a user property, if the flag USER_HAS_EXPIRATION_DATE is set to false, the
stored value is ignored.

Mobile Mobile phone number.

Phone Phone number.

First First name.

Name

Last Last name.

Name

Initials Initials.

Comment Comment.

Policy A bit mask representing following flags:

• USER_MUST_CHANGE_PASSWORD
• USER_CAN_CHANGE_PASSWORD
• USER_HAS_PASSWORD_EXPIRATION
• USER_HAS_ALARM_BEFORE_PASSWORD_EXPIRATION
To set a flag to true the character "x" has to be inserted in the corresponding position,
otherwise the character "-" has to be inserted. Example: xx- denotes a user that can
must the password at first login, can change the password, the password never expires
and no alarm is displayed for password expiration. The password expiration days is
stored in a user property, if the flag USER_HAS_PASSWORD_EXPIRATION is set to
false, the stored value is ignored.

Expiration User expiration date.

Date

User Management Component 1.9.1 - UMX User Manual

40
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.1 Import Entities from File

Name Description

Password An integer representing the password expiration days.

Expiration
Days

Alarm An integer representing the alert in days before the password expiration.
Password
Expiration
Days

CAUTION:

Note that Active Directory (AD) users cannot be imported into UMC via csv file. In case
you perform this operation, the newly-created UM users are not linked to AD. To import
AD users you have to use the UMC Web UI or the appropriate umx command.

The table below lists the record names and descriptions for the import of groups.

Name Description

Name Group name

Description Group description

A list of rules to manage special characters follows:

• semicolon: if a record value contains a semicolomn, it must be delimited by quotation marks.

For example: suppose that we want to insert the full name as Brown;Peter, we should have in
the csv file "Brown;Peter"
• quotation mark: If a record value contains the quotation mark, it must delimited by quotation
marks and any quotation mark must be preceded by a quotation mark. For example: if we want
to insert the value "Peter" we should insert in the csv file the value ""Peter""
• comma: list of values are separated by commas; if one of the values contains comma character,
any value must be delimited by quotation marks. For example: to insert group,1 and group,2
associated to a user we should insert in the csv file "group,1","group,2". If one of the listed
values contains a quotation character, this character must be preceded by three quotation mark.

Syntax

umx [-x commandUserName commandUserPassword] -I {-u |-g} -f fileName

Parameters

• filename is the name of the csv file, for instance myFile.csv

User Management Component 1.9.1 - UMX User Manual

41
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.2 Import Windows Local Users

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-u The data of the csv files are imported as UM users.

-g The data of the csv files are imported as UM groups.

10.2 Import Windows Local Users

This command imports the given Windows user into UMC users; optionally, an existing role can be
assigned to the imported user. The user name of the UMC imported user follows the pattern
<machineName>\<localUserName>.

The command can only be used to import a local machine user on a UM Server or UM Ring Server, if
you need to import a Windows Local User on an Agent, see, Importing a Windows Local User on an
Agent in the UMC Installation Manual. To import Active Directory users you have to use the UMC Web
UI or the appropriate umx command.

This command allows one also to import built-in Windows local users. In the following table we report
the user name parameter corresponding to the built-in Windows local user.

User User name parameter

Local System "NT AUTHORITY\System"

Local Service "NT AUTHORITY\LOCAL SERVICE"

Network Service "NT AUTHORITY\NETWORK SERVICE"

CAUTION:

Imported Windows local users should be used only for configuration purposes, for
instance to be associated to a Windows service running on the machine. Their
authentication is demanded to the underlying operating system.

Syntax

umx [-x commandUserName commandUserPassword] -I -u -w userName [-r role]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;

User Management Component 1.9.1 - UMX User Manual

42
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.3 Import Active Directory Users

• commandUserPassword is the string representing the password of the user that is executing the
command;
• userName is the string representing the user name;
• role represents the role name, it must exist in UMC.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-w Indicates that the user to be imported is a Windows user.

10.3 Import Active Directory Users

This command imports a given Active Directory user (Windows domain user) into UMC users. The
user name of the UMC imported user follows the pattern <ADdomainName>\<ADuserName>.
Imported Active Directory users authenticate against Windows. The import is based on a search index
that is returned by the umx command List Entities, thus a precondition is to execute the List Entities
command first with a search criteria that matches the user you want to import. The command based on
a search index works only in interactive mode and cannot be used in scripts. Alternatively, you can
import a set of Active Directory users according to an input search criteria. Optionally an existing role
can be assigned to the imported users.

Syntax

umx [-x commandUserName commandUserPassword] -I -du -s searchString -d

domainName [-r role] [-f]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• searchString filters the Active Directory users to be listed, the "*" wildcard can be used, the
search is perfomed in the following Active Directory fields: user name (sAMAccountName), user
full name (displayName), and common name (cn).
• domainName is the domain from which the user(s) will be imported.
• role is the existing role that will be assigned to the imported user(s).

User Management Component 1.9.1 - UMX User Manual

43
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.4 Import Active Directory Groups

Switches

Switch Description

-f Forces the creation of multiple users.

10.4 Import Active Directory Groups

This command imports a set of Active Directory groups into UMC groups according to an input search
criteria. The group name of the UMC imported groups follows the pattern <ADdomainName>\
<ADgroupName>. All the users belonging to the group are imported and authenticate against
Windows. Optionally an existing role can be assigned to the imported groups.

Syntax

umx [-x commandUserName commandUserPassword] -I -dg -s searchString -d

domainName [-f]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• searchString filters the Active Directory groups to be listed, the "*" wildcard can be used, the
search field is the group name (cn).
• domainName is the name (without extension) of the domain to which the group belongs.

Switches

Switch Description

-f Forces the creation of multiple groups.

10.5 Import Package - UMC Fully Configured

This command imports UMC user, groups, roles and functional rights from an input UMC package and
merges the package data with the current configuration.

User Management Component 1.9.1 - UMX User Manual

44
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.5 Import Package - UMC Fully Configured

UMC package is a UMC proprietary format, zipped and encrypted. You will be prompted to insert a
password for the decryption that has to be the same of the one used in the export package command.

Prerequisites

• The user performing the command must have the function right UM_ADMIN or both the function
right UM_VIEW and UM_IMPORT.
• UMC has been configured. If UMC is only installed and not configured, to import a package you
have to use the corresponding umconf command. For more details see the UMCONF User
Manual.
• This command can be run only on the priority ring server.

Merge Behavior

The following image provides a visual description of the process.

In the engineering station you can create users, groups, roles and functional rights. When importing
the configuration package on the target system, the data in the target system are updated or
overwritten according to the imported data. The engineering data in the package overwrites all the
engineering data of the target system, except:

• Passwords: the passwords of target system are maintained.

• Object identifiers: if an object with a different name and the same identifier exists, a new
identifier is assigned to the imported object.

The entities are merged as follows:

• Users: The users on the source machine are added to the target machine along with all of their
attributes and properties. When a user is present on both the source and the target machine
(same name), the details of the user on the target machine are overwritten but their password is
maintained.
• Groups:The groups present on the source machine are added to the target machine along with
all of their roles and members. When a group is present on both the source and the target
machine (same name), the details of the groups, including its members and roles are
overwritten with the values present in the source.
• Roles:The roles present on the source machine are added to those present on the target
machine with all the their functional rights. When a role is present on both the source and target
machine the (same name), the functional rights and configurations of the role is overwritten with
the values present in the source.

User Management Component 1.9.1 - UMX User Manual

45
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.5 Import Package - UMC Fully Configured

• Windows Local users: If Windows local users are imported via AD into an engineering station
and then they are imported via package into a target system, their username changes from
<engineeringStationName>\<localUserName>, to <targetMachineName>\<localUserName>.
• Offline users and groups: can be created in the engineering station. After the import package
operation in the target system, when the UMC provisioning service runs, if a user/group is found
in AD with the same name, object data are aligned and the object becomes online. For the
groups, all the AD users belonging to the group are imported into UMC.

The following image presents an example of the import of the UMC configuration of an engineering
station into a target system.

Syntax

umx [-x commandUserName commandUserPassword] -Ip -f file -p password

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• file is the path and name of the file to be imported, for instance C:\temp\myPackage;
• password is the archive password.

User Management Component 1.9.1 - UMX User Manual

46
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.6 Export Entities to File

Switches

Switch Description

-x The command is executed by the user given as input parameter.

10.6 Export Entities to File

This command exports the UM users or UM groups to a csv (Comma Separated Values) file. The
format of the file is the same of the import one (see import command ). Password are not exported.
The flag USER_IS_IMPORTED of the Status field indicates that the user has been imported from AD.

Syntax

umx [-x commandUserName commandUserPassword] -E {-u | -g} -f fileName

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-u The data of the csv files are exported as UM users.

-g The data of the csv files are exported as UM groups.

10.7 Export Package

This command exports UMC user, groups and roles data to a UMC package. UMC package is a UMC
proprietary format, zipped and encrypted. The exported package is the input of the import package
command. The user performing the command must have the function right UM_ADMIN or both the
function right UM_VIEW and UM_EXPORT.

User Management Component 1.9.1 - UMX User Manual

47
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.8 Update via Package

For more information on the import/export package usage see the Standalone Engineering Station
Scenario in the User Management Component Installation Manual.

Syntax

umx [-x commandUserName commandUserPassword] -Ep -f file -p password

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• file is the path and name of the exported file, for instance C:\temp\myPackage. The directory
where the file will be located has to be previously created in the file system.
• password is the encryption password for the archive.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

10.8 Update via Package

UMX provides an additional update via package command. this can be used if you want to update the
engineering station with production data, you can export production data into a package and
subsequently perform an update package command in the engineering station using the exported
package. The effects of the update via package operation are:

• All the data of the engineering station are overwritten or deleted. The only exceptions are user
passwords: if a user exists both in the production machine and in the engineering station, the
password of the engineering station is maintained.
• The Administrator user of the engineering station is maintained.

This command can be run only on the priority ring server.

UMC package is a UMC proprietary format, zipped and encrypted. You will be prompted to insert a
password for the decryption that has to be the same of the one used in the export package command.

The user performing the command must have the function right UM_IMPORT.

For more information on the import/export/update package usage see the Standalone Engineering
Station Scenario in the User Management Component Installation Manual.

User Management Component 1.9.1 - UMX User Manual

48
A5E39179300-AD
10 How to Import / Export UMC Users and Groups
10.8 Update via Package

Syntax

umx [-x commandUserName commandUserPassword] -Up -f file [-p password]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• file is the path and name of the file to be imported, for instance C:\temp\myPackage;
• password is the archive password. If not provided, the user will be prompted to insert the
password.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

49
A5E39179300-AD
11 How to Execute Administrative Commands
The following commands can be used to perform administrative operations, such as setting
passwords, enabling/disabling/unlocking a user, displaying the connection status or disabling the safe
mode.

• Set User Password

• Enable User
• Disable User
• Unlock User
• Disable Safe Mode
• Show Status
• Get Domain Identifier
• Get Domain Name

11.1 Set User Password

This command changes the user password. The new password must not necessarily conform to the
global account policies. The user performing the command must have the function right UM_ADMIN or
both the function rights UM_VIEW and UM_RESETPSW. Empty passwords are not allowed.

Syntax

umx [-x commandUserName commandUserPassword] –setpwd userName newPassword

Parameters

Switches

Switch Description

User Management Component 1.9.1 - UMX User Manual

50
A5E39179300-AD
11 How to Execute Administrative Commands
11.2 Enable User

-x The command is executed by the user given as input parameter.

11.2 Enable User

This command enables the user.

Syntax

umx [-x commandUserName commandUserPassword] -enableusr userName

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

11.3 Disable User

This command disables the user.

Syntax

umx [-x commandUserName commandUserPassword] -disableusr userName

User Management Component 1.9.1 - UMX User Manual

51
A5E39179300-AD
11 How to Execute Administrative Commands
11.4 Unlock User

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

11.4 Unlock User

This command unlocks the user.

Syntax

umx [-x commandUserName commandUserPassword] -unlockusr userName

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

52
A5E39179300-AD
11 How to Execute Administrative Commands
11.5 Disable Safe Mode

11.5 Disable Safe Mode

This command disables the safe mode. The UM ring server on which safe mode is disabled becomes
the master ring server and is able to perform write operations on the UMC database. Consider that
some operations on the UMC system configuration are not allowed in this case, e. g. modifying the
whitelist (see UMCONF User Manual for more details). For more information on the UMC machine
roles see also the overview of the User Management Component Installation Manual.

Syntax

umx [-x commandUserName commandUserPassword] –disablesafe

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

11.6 Show Status

This command provides the results of the UMC health check as output.

Note: In order to retrieve the status of UMC you must specify a user who is a Windows
user with Administrative rights or elevated user if User Account Control (UAC) is enabled.

Info Description

UMC Health The status of UMC server. Example: All UMC servers are running.
Status

UMC The status of UMC Secure Communication Services. Example: All UMC
Communication communication are running.
Status

User Management Component 1.9.1 - UMX User Manual

53
A5E39179300-AD
11 How to Execute Administrative Commands
11.6 Show Status

Info Description

Machine role The possible values are:

• ring;
• server;
• agent.
Example: Machine role is ring

Claim Key (Not for the agent) A claim key is present or not present.

Ticket Key (Not for the agent) A ticket key is present or not present.

UMC databases (Not for the agent) UMC databases are present or not present.

Discovery (Not for the agent) Details on the connection between server and client. Example:
status Discovery status is connected
The possible values are:
• connected;
• standalone (not used);
• no configuration found;
• not initialized;
• generic error.

Workstation (Not for the agent) Example: Workstation status is master

status The possible values are:
• master: the machine is a master UM ring server;
• online: the machine is a UM ring server, not master, or a UM server;
• remote_master_is_in_safe_mode: the machine is a UM server connected
to a master in safe mode;
• initializing: the machine is an initialization phase;
• degraded: the machine is a UM server not connected to any UM ring
server;
• unconnected: not connected;
• segregated: the machine is a segregated server;
• error: generic error.

Ring master The name of the ring master. Example: Now Ring master is : vm-umc1, this field
also specifies if the ring server is in safe mode: vm-umc1 in safe mode.

Authentication The connected authentication server. Example: Authentication server is vm-umc1

server

Syntax

umx [-x commandUserName commandUserPassword] –status

User Management Component 1.9.1 - UMX User Manual

54
A5E39179300-AD
11 How to Execute Administrative Commands
11.6 Show Status

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

Examples

Example #1: the following example shows the output of the health check performed on the ring server.

UMC Health Check information.

UMC Health Status : All UMC servers are running.
UMC Communication Status : All UMC communication are running.
Machine role is ring
Claim Key : present
Ticket Key : present
UMC databases : present
Discovery status is connected
Workstation status is master
Now Ring master is : vm-umc1
Authentication server is vm-umc1
Time taken: 0.13s

Example #2: the following example shows the output of the health check performed on the agent.

UMC Health Check information.

UMC Health Status : All UMC servers are running.
UMC Communication Status : All UMC communication are running.
Machine role is agent
Now Ring master is : vm-umc1
Authentication server is vm-umc1
Time taken: 11.46s

User Management Component 1.9.1 - UMX User Manual

55
A5E39179300-AD
11 How to Execute Administrative Commands
11.7 Get Domain Identifier

11.7 Get Domain Identifier

Retrieves the ID of the current domain.

Syntax

umx [-x commandUserName commandUserPassword] -getdomainid

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

11.8 Get Domain Name

Retrieves the name of the current domain.

Syntax

umx [-x commandUserName commandUserPassword] -getdomainname

Parameters

User Management Component 1.9.1 - UMX User Manual

56
A5E39179300-AD
11 How to Execute Administrative Commands
11.8 Get Domain Name

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

57
A5E39179300-AD
12 How to Manage Account Policies
These commands can be used to modify the account policies related to the following operations:

• Manage Passwords
• Associate UMC User to Provisioning Service
• Restore account policy default values
• Set Default PKI Rule
• Reset Default PKI Rule
• Manage Secure Application Data Support (SADS)

12.1 Modify Account Policies - Passwords

This command modifies the account policies related to password management. If you enable the
password history by days, the password history by number of password is disabled and vice versa.

Syntax

umx [-x commandUserName commandUserPassword] -AP

[-pwdMinLen minLen]
[-pwdMaxLen maxLen]
[-pwdMinLowChar minLC]
[-pwdMinUpChar minUC]
[-pwdMinAlphaChar minAlphaC]
[-pwdMinNumChar minNumC]
[-pwdMinOtherChar minOC]
[-enablePwdHistoryByDays flag -pwdMinDaysBeforePwdReuse daysReuse]
[-enablePwdHistoryByNumPwd flag -pwdMinNumPwdBeforePwdReuse numPwd]
[-enableLockAfterNumAttempts flag -maxLoginErrors numErrors]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• minLen is the minum number of characters allowed in passwords. If you set this value to 0, this
check is disabled. Empty passwords are not allowed.
• maxLen is the maximum number of characters allowed in passwords. If you set this value to 0,
this check is disabled. Empty passwords are not allowed.

User Management Component 1.9.1 - UMX User Manual

58
A5E39179300-AD
12 How to Manage Account Policies
12.2 Modify Account Policies - Associate UMC User with Provisioning Service

• minLC is the minum number of lower case characters allowed in passwords.

• minUC is the minum number of upper case characters allowed in passwords.
• minAlphaC is the minum number of letters allowed in passwords.
• minNumC is the minum number of numbers allowed in passwords.
• minOC is the minum number of special characters (not numbers or letters) allowed in
passwords.
• flag, for the description of this parameter refer to the switch that precedes it in the command
above, 0 corresponds to false and 1 corresponds to true;
• daysReuse is the number of days before you can reuse the same password;
• numPwd is the number of passwords before you can reuse the same password;
• numErrors is the number of errors in typing the password after which the user is locked. The
lock of the user depends also on the value of the user parameter paramOverrideLock (see
Update User).

Switches

Switch Description

-x The command is executed by the user given as input parameter.

12.2 Modify Account Policies - Associate UMC User with Provisioning Service
This command associates a UMC user identified by the parameter name with the UM service
UPService.exe. This user must have a role with the associated function right UM_ADSYNC. This role
is not automatically created and has to be created before associating this user. This user is stored as
an account policy. It is mandatory to restart the UM service UPService.exe after executing the
command.

Important:

This configuration is not mandatory. The UMC user associated by default with the
provisioning service is the UMC administrator. We strongly recommend to perform this
configuration to harden your system following the least privilege principle.

Syntax

umx [-x commandUserName commandUserPassword] -AP -provisioningDefaultUser

user [-s]

User Management Component 1.9.1 - UMX User Manual

59
A5E39179300-AD
12 How to Manage Account Policies
12.3 Modify Account Policies - Restore

Parameters

Switches

Switch Description

12.3 Modify Account Policies - Restore

This command modifies the account policies restoring them to their default values. Default values are:

• minum number of characters: 8

• maximum number of characters: 120
• minum number of lower case characters: 1
• minum number of upper case characters: 1
• minum number of letters: 2.
• minum number of numbers: 1.
• minum number of special characters (not numbers or letters): 0
• password history:
– enable Password History by Days: true
– number of days before you can reuse the same password: 120
– enable Password History by Number of Passwords: false
– number of passwords before you can reuse the same password: 5

• Enable user lock after n wrong login attempts: true

• number of errors in typing the password after which the user is locked: 5

Syntax

umx [-x commandUserName commandUserPassword] -AP -restore

User Management Component 1.9.1 - UMX User Manual

60
A5E39179300-AD
12 How to Manage Account Policies
12.4 Modify Account Policies - Set Default PKI Rule

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

12.4 Modify Account Policies - Set Default PKI Rule

This command sets a default PKI rule to be used in smart card authentication. A PKI rule establishes,
for a given issuer, which is the authorization mode that can be used and the corresponding filter.
Please refer to the smart card authentication configuration in the User Management Component
Installation Manual for more details and the example.

Syntax

umx -AP -setdefaultpki -issuer issuerName -authmode authModeValue [-filter

filterValue]

Parameters

• issuerName is the name of the issuer of the certificate, by now this value is not used;
• authModeValue represents the different types of allowed authentication modes:
– 2: Authentication using filter on Subject;
– 3: Alias Authentication using filter on Subject
– 4: Authenticate using CN;
– 5: Alias Authentication using CN;
– 10: Authentication using filter on Alternate Subject;
– 11: Alias Authentication using filter on Alternate Subject.

• filterValue is the regular expression representing the filter.

User Management Component 1.9.1 - UMX User Manual

61
A5E39179300-AD
12 How to Manage Account Policies
12.5 Modify Account Policies - Reset Default PKI Rule

12.5 Modify Account Policies - Reset Default PKI Rule

This command resets the default PKI rule to be used in smart card authentication. A PKI rule
establishes, for a given issuer, which is the authorization mode that can be used and the
corresponding filter.

Syntax

umx -AP -resetdefaultpki

12.6 Modify Account Policies - Secure Application Data Support

This command modifies the account policy related to Secure Application Data Support (SADS).

Syntax

umx -AP {-setakp | -resetakp}

Switches

Switch Description

-setakp Enables Secure Application Data Support for users and groups.

-resetakp Disables Secure Application Data Support for users and groups.

User Management Component 1.9.1 - UMX User Manual

62
A5E39179300-AD
13 How to Execute Commands in Interactive Mode
The following command can be used to run UMX in interactive mode.

• Interactive Mode
• Enable Notifications

13.1 Interactive Mode

This command launches the umx interactive mode. Umx process is always active and the single
commands can be launched directly without being preceded by the umx string.

The following commands can be launched only in interactive mode:

• -q, to exit the interactive mode;

• -lockdb, to perform a write lock on the UMC database;
• -unlockdb, to remove the write lock on the UMC database.

Syntax

umx -interactive

Important: Database Lock

When umx is launched in interactive mode, a write lock on the database is performed.
Thus, no other process/application can modify the database entities. Read only access is
allowed.

13.2 Enable Notifications

This command is only for testing purposes. It enables the notifications on the server connection status
and on the create/update/delete of the following database objects: users, groups, roles and account
policies.

Syntax

umx [-x commandUserName commandUserPassword] -N

User Management Component 1.9.1 - UMX User Manual

63
A5E39179300-AD
13 How to Execute Commands in Interactive Mode
13.2 Enable Notifications

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

64
A5E39179300-AD
14 How to Execute Authentication Commands
The following command can be used to perform the authentication of UMC users.

• Test Authentication
• Generate Ticket
• Change User Password

14.1 Test Authentication

This command performs an authentication versus UMC with the credentials provided in input. If the
switch -win is present, the authentication of the current Windows logged in user is also performed. The
command output shows whether the authentication succeeds or fails and whether the authenticated
user owns or not the function right UM_ADMIN.

Syntax

umx [-x commandUserName commandUserPassword] -t userName password [-win]

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

-win Authenticates also the current Windows logged in user

User Management Component 1.9.1 - UMX User Manual

65
A5E39179300-AD
14 How to Execute Authentication Commands
14.2 Generate Ticket

14.2 Generate Ticket

This command, given a user name and an associated password, generates a ticket that is used for
authentication instead of the password. Ticket duration (in seconds) has to be specified; after the
duration, the ticket expires and cannot be used to login anymore.

Syntax

umx [-x commandUserName commandUserPassword] -T userName password duration

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

14.3 Change User Password

This command changes the user password knowing the old password. The new password must
conform to the global account policies. Empty passwords are not allowed. This command can be
performed also on a UM server in degraded mode (see the User Management Component Installation
Manual for more details). When the UM server degraded mode ends, the reconciliation between
passwords at database level is performed and the most recent is kept.

User Management Component 1.9.1 - UMX User Manual

66
A5E39179300-AD
14 How to Execute Authentication Commands
14.3 Change User Password

Syntax

umx [-x commandUserName commandUserPassword] –changepwd userName oldPassword

newPassword

Parameters

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

67
A5E39179300-AD
15 How to Manage Secure Application Data Support
The following commands can be used to manage data encryption and decryption for users and groups
to apply Secure Application Data Support (SADS).

• Enable Encryption
• Encrypt Keys
• Decrypt Keys

SADS capabilities at application level can be enabled via umx or Web UI by modifying an account
policy. For what concerns the subject level, this can only be done via umx.

15.1 Enable Encryption

This command enables encryption capabilities on subjects (users or groups).

Syntax

umx [-x commandUserName commandUserPassword] -SK -e {-u user |-g group} [-s]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details.
• group represents the group name if the switch –s is present, represents the group internal
identifier if the switch –s is not present, the identifier is a positive number univocally identifying
the record.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

68
A5E39179300-AD
15 How to Manage Secure Application Data Support
15.2 Encrypt Keys

15.2 Encrypt Keys

This command encrypts an application key (AK) using the user or group subject key (SK).

Syntax

umx [-x commandUserName commandUserPassword] -AK -e -k Key {-u user |-g

group} [-s] [-f]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• Key is the application key to be used to encrypt application data.
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details.
• group represents the group name if the switch –s is present, represents the group internal
identifier if the switch –s is not present, the identifier is a positive number univocally identifying
the record.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

69
A5E39179300-AD
15 How to Manage Secure Application Data Support
15.3 Decrypt Keys

15.3 Decrypt Keys

This command decrypts an application key (AK) using the user or group's subject key (SK). The
encrypted Application Key can be decrypted only if it has previously been encrypted with a Subject Key
of the current authenticated user or the groups he is a member of.

Syntax

umx [-x commandUserName commandUserPassword] -AK -d -k EncryptedKey {-u user

|-g group} [-s] [-f]

Parameters

• commandUserName is the string representing the name of the user that is executing the
command;
• commandUserPassword is the string representing the password of the user that is executing the
command;
• EncryptedKey is the key to be decrypted for the user or group according to their data access
control confguration;
• user represents the user name if the switch –s is present, represents the user internal identifier
if the switch –s is not present, the identifier is a positive number univocally identifying the record;
to retrieve the user identifier see List Entity Details;
• group represents the group name if the switch –s is present, represents the group internal
identifier if the switch –s is not present, the identifier is a positive number univocally identifying
the record.

Switches

Switch Description

-x The command is executed by the user given as input parameter.

User Management Component 1.9.1 - UMX User Manual

70
A5E39179300-AD
16 Error Codes
Value Description

0 Success

-1 Command syntax error

In all the other cases, the command returns the last error code (decimal format) returned by the UMC
APIs invoked during the command execution. See UMC APIs Error Codes for more details.

Example #1

Consider the following script to display the information of the user identified by 66 where no user has
assigned the identifier 66 in the UMC database:

umx -i -u 66
echo %errorlevel%

No deletion is performed and umx returns the decimal number 273 that corresponds to the following
error code in UMC APIs Error Codes.

SL_OBJ_DOES_NOT_EXIST 0x111 273 The UMC object does not exist or has not yet been
saved into the UMC database.

16.1 UMC APIs Error Codes

All the UMC APIs return a boolean value or an object handle. If the API is successful, the returned
boolean value is true or the object handle is well formed; otherwise the returned boolean value is false,
or null is returned instead of the object handle. If the API fails an error code can be retrieved calling the
SL_GetLastError method. SL_RESULT defines the type of error. In what follows we list the possible
error codes.

Generic Errors

Name Hexadecimal Value Decimal Value Description

SL_SUCCESS 0X00 0 No errors have occurred.

SL_GENERROR 0X01 1 Generic error.

SL_BAD_HANDLE 0x114 276 Internal error for invalid handle.

SL_NOSESSION 0X30 48 The Web session is expired.

User Management Component 1.9.1 - UMX User Manual

71
A5E39179300-AD
16 Error Codes
16.1 UMC APIs Error Codes

Authentication Errors

Name Hexadecimal Decimal Description

Value Value

SL_USERLOCKED 0X02 2 The user for whom you want to

perform the authentication is
locked.

SL_USERDISABLED 0X03 3 The user for whom you want to

perform the authentication is
disabled.

SL_WRONGUSERNAMEPASSWORD 0X04 4 During the authentication phase,

the user name or password are
incorrect.

SL_PASSWORDPOLICYVIOLATION 0X05 5 Password policy violation

(determined by UMC account
policies). For a detailed list of
Account Policies, see User
Management Component API
SDK Developer Manual.

SL_USERMUSTCHANGEPASSWORD 0X06 6 The user password must be

changed.

SL_PASSWORDEXPIRED 0X07 7 The user password is expired.

SL_FAILED 0X0A 10 Generic operation failed.

SL_ALREADYLOCKED 0X0B 11 The UMC object is already

locked.

SL_COMMERR 0X0C 12 Transmission/Communication

error.

SL_NOTIMPL 0X10 16 Returned if a not implemented

method is invoked.

SL_CHANGEPSWDISABLE 0X19 25 The user cannot change the

password.

SL_USERUNKNOWN 0X20 32 The user is not present in the

system.

SL_USERNEVEREXPIRE 0X21 33 The user never expires.

SL_TICKETEXPIRED 0X22 34 The authentication ticket is

expired.

SL_USER_EXPIRED 0x27 39 The user is expired.

SL_PSWMINLEN_ERR 0x120 288 The account policy related to the

minimal password length has
been violated.

SL_PSW_CHANGE_FAIL 0X154 340 Password change failure.

User Management Component 1.9.1 - UMX User Manual

72
A5E39179300-AD
16 Error Codes
16.1 UMC APIs Error Codes

Name Hexadecimal Decimal Description

Value Value

SL_INVALID_NONCE 0x166 358 Login failed: invalid token. This

event may occur if you try to
access the login page directly
from the URL or if you leave the
login page open.

SL_WEAK_AUTH 0x167 359 Login failed: access not allowed

using weak authentication
method.

CRUD Operation Errors

Name Hexadecimal Decimal Description

Value Value

SL_ALREADYEXIST 0x0D 13 The UMC object already

exists.

SL_LOCK_NEEDED 0x23 35 A lock is needed to complete

the operation.

SL_NOT_LOCKED 0x24 36 The UMC object is not locked

so you cannot unlock it.

SL_OBJVERMISMATCH 0X31 49 A UMC object has been

simultaneously modified by
two Web UI instances and an
object version mismatch has
been detected.

SL_INVALID_OPERATION 0x103 259 The operation cannot be

performed on the selected
object.

SL_OBJ_DOES_NOT_EXIST 0x111 273 The UMC object does not

exist or has not yet been
saved into the UMC
database.

SL_OBJECT_LOCKED_IN_DATABASE 0X153 339 The UMC object is already

locked.

SL_FAIL_NOTAMASTER 0x160 352 An attempt has been made to

modify the UMC database on
a machine that is not a
master.

User Management Component 1.9.1 - UMX User Manual

73
A5E39179300-AD
16 Error Codes
16.1 UMC APIs Error Codes

Name Hexadecimal Decimal Description

Value Value

SL_FAIL_BINDING_ADMIN_ROLE 0x161 353 An attempt has been made to

assign the Administrator role
to a group or the user who
performed the association,
either a UMX user or a Web
UI user, does not have the
Administrator role.

SL_OBJ_OFFLINE 0x0F 15 The user/group for which you

want to perform an operation
is offline and the operation is
not allowed for offline objects.

SL_INVALID_NAME_FOR_OFFLINE_OBJ 0x165 357 The offline user/group that

you are creating does not
follow the pattern
<domainName>\<objName>.

SL_INVALID_SID 0x5C 92 Invalid User Security

Identifier (SID). See Microsoft
Documentation on Security
Identifiers for more details.

Provider Operation Errors

Name Hexadecimal Decimal Description

Value Value

SL_INVALID_PROVIDER 0x100 256 Operation not provided by this

provider.

SL_INVALID_HANDLE 0x101 257 An invalid handle was passed as

parameter.

SL_ERROR_LOADING_PROVIDER 0x102 258 An error occurred when loading

the provider.

Internal or Parameter Errors

Name Hexadecimal Decimal Description

Value Value

SL_INVALID_PARAMETERS 0x104 261 The method has an incorrect

parameter.

SL_MEMORY_ERROR 0x105 262 Memory allocation error.

SL_INITIALIZATION_ERROR 0x106 263 Initialization error.

SL_INVALID_LOCK_OPTION 0x108 264 The lock option has not been defined.

User Management Component 1.9.1 - UMX User Manual

74
A5E39179300-AD
16 Error Codes
16.1 UMC APIs Error Codes

Name Hexadecimal Decimal Description

Value Value

SL_INVALID_PROPERTY 0x109 265 The property has not been defined for
the object.

File Errors

Name Hexadecimal Value Decimal Value Description

SL_ACCESS_FILE_ERROR 0x112 274 Access file error.

SL_UNKNOWN_FILE_FORMAT 0x113 275 Unknown file format.

SL_FILE_NOT_FOUND 0x50 80 File not found.

SL_PATH_NOT_FOUND 0x51 81 Path not found.

SL_FILE_CREATION_FAIL 0x52 82 Error during file creation.

SL_PATH_CREATION_FAIL 0x53 83 Error during path creation.

SL_INVALID_PATH 0x54 84 Invalid path.

Function Rights Errors

Name Hexadecimal Decimal Description

Value Value

SL_RESOURCE_NOT_FOUND 0x150 336 The user does not have the correct
function right to perform the
requested operation. This error has
the same meaning as the
SL_MISSING_FUNCTION_RIGHT
error.

SL_INVALID_RESOURCE 0x151 337 The function right does not exist.

SL_MISSING_FUNCTION_RIGHT 0x152 338 The user does not have the correct
function right to perform the
requested operation. This error has
the same meaning as the
SL_RESOURCE_NOT_FOUND
error.

Service Layer Errors

Name Hexadecimal Value Decimal Value Description

SL_CLAIM_EXPIRED 0X155 341 The claim is expired.

User Management Component 1.9.1 - UMX User Manual

75
A5E39179300-AD
16 Error Codes
16.1 UMC APIs Error Codes

Name Hexadecimal Value Decimal Value Description

SL_CLAIM_INVALID 0X156 342 The claim is invalid.

SL_JSON_ERROR 0X157 343 The .json file is not well formed.

SL_MKTKT_FAILURE 0X158 344 The "make ticket" operation failed.

SL_ABORTED 0x159 345 Operation aborted.

Package Errors

Name Hexadecimal Decimal Description

Value Value

SL_PACKAGE_CREATION_FAIL 0x55 85 Package creation failed.

SL_PACKAGE_COMPRESSION_FAIL 0x56 86 Package compression

failed.

SL_PACKAGE_UNCOMPRESSION_FAIL 0x57 87 Package decompression

failed.

SL_PACKAGE_ENCRYPTION_FAIL 0x58 88 Package encryption

failed.

SL_PACKAGE_DECRYPTION_FAIL 0x59 89 Package decryption

failed.

SL_PACKAGE_RESTORE_FAIL 0x5A 90 Package restore failed.

SL_PACKAGE_WRONG_PASSWORD 0x5B 91 Wrong password for the

package.

Database Errors

Name Hexadecimal Decimal Description

Value Value

SL_DBFILE_ACCESS_DENIED 0X32 50 The user cannot access a UMC

database file.

SL_DBFILE_ERROR 0X33 51 Generic UMC database file error.

SL_DBFILE_OUT_OF_SPACE 0X34 52 A UMC database file is full.

SL_ROLEIDS_OUT_OF_SPACE 0X35 53 No more role IDs are available in the

role database file. A purge of the roles
is needed.

User Management Component 1.9.1 - UMX User Manual

76
A5E39179300-AD
16 Error Codes
16.1 UMC APIs Error Codes

User Alias Errors

Name Hexadecimal Decimal Description

Value Value

SL_INVALID_USER_ALIAS 0x5E 94 Invalid user alias name.

SL_USER_ALIAS_ALREADY_EXIST 0x5F 95 User alias already exists.

SL_BAD_PKI_FILTER_NAME 0x115 277 Invalid filter name or filter name

not present when authmode =
SL_PKI_FILTER_MASK.

Secure Application Data Support (SADS) Errors

Name Hexadecimal Decimal Description

Value Value

SL_INVALID_DOMAIN_NAME 0x60 96 Invalid domain name.

SL_NOT_CURRENT_DOMAIN 0x61 97 Input domain name is not the

current domain.

SL_INVALID_KEY 0x70 112 Invalid key.

SL_KEY_GENERATION_FAIL 0x71 113 Error during key generation.

SL_KEY_ENCRYPTION_FAIL 0x72 114 Error during key encryption.

SL_KEY_DECRYPTION_FAIL 0x73 115 Error during key decryption.

SL_KEY_NOT_FOUND 0x74 116 Key not found.

SL_KEY_ENCRYPTION_NOT_ENABLED 0x75 117 Application key protection

(global policies) not enabled.

SL_MAX_NUM_KEY 0x76 118 The maximum number of

allowed keys has been
reached.

SL_KEY_DECRYPTION_NO_ID_FOUND 0x77 119 No SUID of the identity has

been found in EAK array.

SL_SADS_VERSION_ERROR 0x78 120 Wrong SADS version.

SL_WRONG_IDENTITY 0x79 121 Ticket authentication error

while decrypting a key.

SL_EAK_BAD_FORMAT 0x80 128 Bad format of the encryption

application object.

SL_SUBJECT_NOT_ENABLED 0x81 129 Encryption not enabled for the

specified subject.

SL_SUBJECT_KEY_OBSOLETE 0x82 130 The decryption has been

executed using an obsolete
key.

User Management Component 1.9.1 - UMX User Manual

77
A5E39179300-AD
17 Parameter Sizes
The following table lists the sizes for the main UMC database fields.

API Property Name API Object Web UI Display UMX Size in

Name Parameter Chars

SL_USER_NAME SLOBJ_USER User Name name 100

SL_USER_PASSWORD SLOBJ_USER Password password 120

SL_USER_FULLNAME SLOBJ_USER Full Name fullName 250

SL_GROUP_NAME SLOBJ_GROUP Group Name name 100

SL_GROUP_DESCRIPTION SLOBJ_GROUP Description description 260

SL_ROLE_NAME SLOBJ_ROLE Role Name name 255

SL_ROLE_DESCRIPTION SLOBJ_ROLE Description description 40

SL_ATTRIBUTE_NAME SLOBJ_ATTRIBUTE Attribute Name attribute 80

name

User Management Component 1.9.1 - UMX User Manual

78
A5E39179300-AD

Tellabs 8800 Multi Service Router MSR Series Enabling New
No ratings yet
Tellabs 8800 Multi Service Router MSR Series Enabling New
13 pages
TL1 ReferenceGuide R4.7.1 PRELIMINARY
100% (1)
TL1 ReferenceGuide R4.7.1 PRELIMINARY
376 pages
ABR I O Driver Manual PDF
No ratings yet
ABR I O Driver Manual PDF
209 pages
zxr10 PDF
No ratings yet
zxr10 PDF
100 pages
BCC Basic Troubleshooting Guide
No ratings yet
BCC Basic Troubleshooting Guide
21 pages
Winshuttle-Migrating-Finance-SAP-ECC-to-S4HANA-whitepaper-EN
100% (1)
Winshuttle-Migrating-Finance-SAP-ECC-to-S4HANA-whitepaper-EN
62 pages
Advantages of UNM2000
No ratings yet
Advantages of UNM2000
49 pages
Fast Tools GS50A01A10-01EN
No ratings yet
Fast Tools GS50A01A10-01EN
57 pages
Msan Ua5000
No ratings yet
Msan Ua5000
33 pages
SCC-U21C185B150 HW Meafnaf Software Upgrade Guideline
No ratings yet
SCC-U21C185B150 HW Meafnaf Software Upgrade Guideline
8 pages
Software Upgrade Procedure
No ratings yet
Software Upgrade Procedure
4 pages
204-4117-07 - DmSwitch EDD SII - Installation Manual
No ratings yet
204-4117-07 - DmSwitch EDD SII - Installation Manual
40 pages
600-35ns01-A - Honeywell 35 Series NVR Network Security Guide-0728
No ratings yet
600-35ns01-A - Honeywell 35 Series NVR Network Security Guide-0728
25 pages
ProVision 6 5 2 User Manual PDF
No ratings yet
ProVision 6 5 2 User Manual PDF
398 pages
FONST 5000 U10E Quick Installation Guide Version A
No ratings yet
FONST 5000 U10E Quick Installation Guide Version A
35 pages
OTA105101 OptiX OSN 1500 Hardware Description ISSUE 1.20
No ratings yet
OTA105101 OptiX OSN 1500 Hardware Description ISSUE 1.20
119 pages
02 Msoftx3000 Hardware System Issue1 0
No ratings yet
02 Msoftx3000 Hardware System Issue1 0
68 pages
Netman 4000 OMC-A: Network Management System System Overview
No ratings yet
Netman 4000 OMC-A: Network Management System System Overview
35 pages
Siemens Surpass7025
No ratings yet
Siemens Surpass7025
2 pages
GFK1533-VersaMax DeviceNet Communication Modules
No ratings yet
GFK1533-VersaMax DeviceNet Communication Modules
54 pages
MANUAL Radio Saf
No ratings yet
MANUAL Radio Saf
63 pages
NV9.7 TPD 080808 1
No ratings yet
NV9.7 TPD 080808 1
75 pages
Switching Um
No ratings yet
Switching Um
63 pages
1642EMUX21 CH Ed01
No ratings yet
1642EMUX21 CH Ed01
56 pages
Wizcon Quick Guide
No ratings yet
Wizcon Quick Guide
98 pages
Lecture 3 Operating System Structures
No ratings yet
Lecture 3 Operating System Structures
30 pages
T-Berd Mts 8000 and T-Berd Mts 6000a
100% (1)
T-Berd Mts 8000 and T-Berd Mts 6000a
396 pages
Passport 8600 Product Brief
100% (2)
Passport 8600 Product Brief
96 pages
S56H2021
No ratings yet
S56H2021
55 pages
Manual
No ratings yet
Manual
98 pages
1353sh Administracion
100% (1)
1353sh Administracion
360 pages
00384246-OSN 3500 - Hardware Description (V100R008 - 10)
No ratings yet
00384246-OSN 3500 - Hardware Description (V100R008 - 10)
820 pages
1830-PSS New NE Software Installation 10-10-2012
No ratings yet
1830-PSS New NE Software Installation 10-10-2012
39 pages
VCL TP Teleprotection Equipment Easy To Use GUI Guide: Valiant Communications Limited - 2018 1
No ratings yet
VCL TP Teleprotection Equipment Easy To Use GUI Guide: Valiant Communications Limited - 2018 1
58 pages
Umux 1500 1200 e
100% (1)
Umux 1500 1200 e
2 pages
Hands-On Guide To OVSV610R103 C&C08 Switch: Huawei Technologies Co., LTD
No ratings yet
Hands-On Guide To OVSV610R103 C&C08 Switch: Huawei Technologies Co., LTD
29 pages
FactoryTalk View SE - Backup Your Application Using The Distributed Application Manager
No ratings yet
FactoryTalk View SE - Backup Your Application Using The Distributed Application Manager
4 pages
NetEngine 8000 M14, M8 and M4 V800R023C00SPC500 Configuration Guide 04 Interface and Data Link
No ratings yet
NetEngine 8000 M14, M8 and M4 V800R023C00SPC500 Configuration Guide 04 Interface and Data Link
207 pages
Ont v200r006s102 User Manual
No ratings yet
Ont v200r006s102 User Manual
62 pages
FONST 4000 Intelligent OTN Equipment Product Description (Version F)
No ratings yet
FONST 4000 Intelligent OTN Equipment Product Description (Version F)
442 pages
Using Optivity NMS 10.3 Applications: Part No. 207569-F November 2004 4655 Great America Parkway Santa Clara, CA 95054
100% (1)
Using Optivity NMS 10.3 Applications: Part No. 207569-F November 2004 4655 Great America Parkway Santa Clara, CA 95054
885 pages
Integrating CM 1542-5 As I Slave in STEP 7 V5.x
No ratings yet
Integrating CM 1542-5 As I Slave in STEP 7 V5.x
7 pages
XMS Administration Guide Xmsadm - v21-410
No ratings yet
XMS Administration Guide Xmsadm - v21-410
136 pages
Intouch Tse DG 10
No ratings yet
Intouch Tse DG 10
139 pages
R17.0 DTN and DTN-X Alarm and Trouble Clearing Guide
No ratings yet
R17.0 DTN and DTN-X Alarm and Trouble Clearing Guide
639 pages
Gs33l50e20-40e 003
No ratings yet
Gs33l50e20-40e 003
4 pages
V-24 Serial Interface
No ratings yet
V-24 Serial Interface
11 pages
TNMS ASON / Ethernet Manager 11.0: User Manual (UMN)
No ratings yet
TNMS ASON / Ethernet Manager 11.0: User Manual (UMN)
113 pages
Ipss4 Um
No ratings yet
Ipss4 Um
207 pages
PWS 008289
No ratings yet
PWS 008289
12 pages
ZXA10 MSAN Technical Specification
100% (3)
ZXA10 MSAN Technical Specification
173 pages
Hit 7300
No ratings yet
Hit 7300
2 pages
Ic Inst-Emxpii
No ratings yet
Ic Inst-Emxpii
173 pages
Miracast For Realtek WiFi
No ratings yet
Miracast For Realtek WiFi
6 pages
Huawei Smartax Ma5616 Hardware Description v800r310c0002 - 2
No ratings yet
Huawei Smartax Ma5616 Hardware Description v800r310c0002 - 2
164 pages
Cacti 0.8 Beginner's Guide
From Everand
Cacti 0.8 Beginner's Guide
Thomas Urban
No ratings yet
DeviceNet The Ultimate Step-By-Step Guide
From Everand
DeviceNet The Ultimate Step-By-Step Guide
Gerardus Blokdyk
No ratings yet
Drive testing The Ultimate Step-By-Step Guide
From Everand
Drive testing The Ultimate Step-By-Step Guide
Gerardus Blokdyk
No ratings yet
UMCONF User Manual
No ratings yet
UMCONF User Manual
36 pages
UMCONF User Manual
No ratings yet
UMCONF User Manual
35 pages
UMC Release Notes
No ratings yet
UMC Release Notes
34 pages
Unprojected PLC PLC Communication PDF
No ratings yet
Unprojected PLC PLC Communication PDF
30 pages
Projected PLC PLC Communication PDF
No ratings yet
Projected PLC PLC Communication PDF
9 pages
Projected PLC PLC Communication PDF
No ratings yet
Projected PLC PLC Communication PDF
9 pages
Notes - E3-LIB - LIB PDF
No ratings yet
Notes - E3-LIB - LIB PDF
1 page
Workable BI Data Link - Database Structure v1.6
No ratings yet
Workable BI Data Link - Database Structure v1.6
56 pages
Flexy Family User Guide
No ratings yet
Flexy Family User Guide
36 pages
Different Types of Computers
No ratings yet
Different Types of Computers
17 pages
2023 OLA Funding Program For Partners
No ratings yet
2023 OLA Funding Program For Partners
13 pages
System Analysis and Design
100% (1)
System Analysis and Design
54 pages
Best Practice Configuration of The Security Audit Log
No ratings yet
Best Practice Configuration of The Security Audit Log
4 pages
Alfreda Burke
No ratings yet
Alfreda Burke
3 pages
BMT - Signal, IP Lists Rev.4
No ratings yet
BMT - Signal, IP Lists Rev.4
1 page
go4braindumps-oracle-1z0-902-exam-dumps-by-baldwin-29-01-2024-8qa
No ratings yet
go4braindumps-oracle-1z0-902-exam-dumps-by-baldwin-29-01-2024-8qa
9 pages
Ecommerce 2,0
No ratings yet
Ecommerce 2,0
33 pages
Brown Et Al 2015
No ratings yet
Brown Et Al 2015
19 pages
DW Chapter 3
No ratings yet
DW Chapter 3
25 pages
Session 1 2 Blockchain v2.16
No ratings yet
Session 1 2 Blockchain v2.16
204 pages
Lesson 5 Collaborative ICT Development
0% (1)
Lesson 5 Collaborative ICT Development
18 pages
VMW 10q3 White Paper Cloud Director Security PDF
No ratings yet
VMW 10q3 White Paper Cloud Director Security PDF
37 pages
Chapter Seven: Cookies and Session Management in PHP
No ratings yet
Chapter Seven: Cookies and Session Management in PHP
65 pages
Developing Java 2 Platform, Enterprise Edition (J2EE) Compatible Applications
No ratings yet
Developing Java 2 Platform, Enterprise Edition (J2EE) Compatible Applications
8 pages
Chapter 4
No ratings yet
Chapter 4
42 pages
NS7 6.2 Efw
No ratings yet
NS7 6.2 Efw
19 pages
Architecture Diagram BI Platform 4.3
No ratings yet
Architecture Diagram BI Platform 4.3
1 page
Module 07 - Mimics
No ratings yet
Module 07 - Mimics
15 pages
Final Presentation About Hotel
No ratings yet
Final Presentation About Hotel
26 pages
Database Design: Answer
No ratings yet
Database Design: Answer
14 pages
Information Security: 1.0 Purpose and Benefits
100% (1)
Information Security: 1.0 Purpose and Benefits
16 pages
BCA DM Chapter 6 - Association
No ratings yet
BCA DM Chapter 6 - Association
37 pages
Fundamental of Computer Systems Assignment
No ratings yet
Fundamental of Computer Systems Assignment
3 pages
Ais CH04
100% (1)
Ais CH04
65 pages
Library DB
No ratings yet
Library DB
10 pages
Design Review AI: Scope
No ratings yet
Design Review AI: Scope
17 pages