Cybersecurity information 1

Basics of UMC 2
Installing and configuring
UMC 3

Using UMC Web UI 4

UMC - Central User Management
UMC security concept 5

References 6
Programming and Operating Manual

11/2023
A5E52954435-AA
Legal information
Warning notice system
This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent
damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert
symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are
graded according to the degree of danger.

DANGER
indicates that death or severe personal injury will result if proper precautions are not taken.

WARNING
indicates that death or severe personal injury may result if proper precautions are not taken.

CAUTION
indicates that minor personal injury can result if proper precautions are not taken.

NOTICE
indicates that property damage can result if proper precautions are not taken.
If more than one degree of danger is present, the warning notice representing the highest degree of danger will
be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to
property damage.
Qualified Personnel
The product/system described in this documentation may be operated only by personnel qualified for the specific
task in accordance with the relevant documentation, in particular its warning notices and safety instructions.
Qualified personnel are those who, based on their training and experience, are capable of identifying risks and
avoiding potential hazards when working with these products/systems.
Proper use of Siemens products
Note the following:

WARNING
Siemens products may only be used for the applications described in the catalog and in the relevant technical
documentation. If products and components from other manufacturers are used, these must be recommended or
approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance
are required to ensure that the products operate safely and without any problems. The permissible ambient
conditions must be complied with. The information in the relevant documentation must be observed.

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.

Siemens AG A5E52954435-AA Copyright © Siemens AG 2023.

Digital Industries Ⓟ 09/2023 Subject to change All rights reserved
Postfach 48 48
90026 NÜRNBERG
GERMANY
Table of contents

1 Cybersecurity information..................................................................................................................... 9
2 Basics of UMC ...................................................................................................................................... 11
2.1 Introduction to UMC .......................................................................................................... 11
2.2 Abbreviations .................................................................................................................... 13
2.3 Definitions ......................................................................................................................... 14
2.3.1 UM domain........................................................................................................................ 14
2.3.2 UM user............................................................................................................................. 14
2.3.3 UM group .......................................................................................................................... 15
2.3.4 UM role ............................................................................................................................. 16
2.3.5 UM function rights............................................................................................................. 17
2.3.6 Computer roles .................................................................................................................. 18
2.3.7 Provisioning scenarios........................................................................................................ 22
2.3.8 Claim key........................................................................................................................... 22
3 Installing and configuring UMC ........................................................................................................... 23
3.1 Prerequisites ...................................................................................................................... 23
3.1.1 General recommendations and requirements ..................................................................... 23
3.1.2 Supported browsers ........................................................................................................... 24
3.1.3 Supported operating systems ............................................................................................. 24
3.1.4 Microsoft Visual C++ .......................................................................................................... 24
3.1.5 Identity Provider prerequisites ............................................................................................ 25
3.1.6 Requirements of Microsoft IIS Manager .............................................................................. 25
3.1.7 Configuring the HTTPS protocol in Microsoft IIS Manager .................................................... 27
3.2 Installing UMC ................................................................................................................... 29
3.3 Configuring UMC ............................................................................................................... 30
3.3.1 Configuring standalone UMC scenario ................................................................................ 30
3.3.2 Configuring UMC scenario.................................................................................................. 31
3.3.2.1 Configuring the primary UMC ring server............................................................................ 32
3.3.2.2 Configuring the secondary UMC ring server ........................................................................ 33
3.3.2.3 Configuring UMC web components .................................................................................... 34
3.3.2.4 Configuring the UMC station client ..................................................................................... 61
3.3.2.5 Configuring Simatic Logon Remote Authentication (SLRA) .................................................. 62
3.3.2.6 Configuring Desktop Single Sign-on (DSSO) ........................................................................ 63
3.3.2.7 Configuring Global User Management (GUM) ..................................................................... 63
3.4 Configuring the identity provider........................................................................................ 65
3.4.1 High availability / reliability general issues .......................................................................... 65
3.4.2 Health state service............................................................................................................ 66
3.4.3 NLB and health state integration ........................................................................................ 67
3.5 Updating UMC ................................................................................................................... 70
3.5.1 General Recommendations ................................................................................................ 70
3.5.1.1 Migrating IdP configurations .............................................................................................. 71
3.5.2 Updating the secondary UMC ring server............................................................................ 72

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 3
Table of contents

3.5.3 Updating the primary UMC ring server ............................................................................... 73

3.5.4 Restarting the secondary UMC ring server .......................................................................... 74
3.5.5 Updating a UMC server ...................................................................................................... 74
3.5.6 Updating a UMC agent ....................................................................................................... 75
3.5.7 Updating the UMC station client......................................................................................... 75
3.6 Deleting UMC configuration ............................................................................................... 76
3.7 Uninstalling UMC station client software ............................................................................ 77
3.8 Troubleshooting................................................................................................................. 78
3.9 Additional information ....................................................................................................... 81
3.9.1 Importing a local Windows user into a UMC agent .............................................................. 81
3.9.2 UMC processes................................................................................................................... 82
3.9.3 Event logging .................................................................................................................... 82
3.9.3.1 Event logging security notes .............................................................................................. 83
3.9.4 Additional provisioning configuration ................................................................................. 84
3.9.5 Additional provisioning details ........................................................................................... 88
3.9.6 Performing the automatic certificates renewal .................................................................... 91
4 Using UMC Web UI ............................................................................................................................... 93
4.1 Quick guide to using the UMC Web UI ................................................................................ 93
4.1.1 General Recommendations ................................................................................................ 93
4.1.2 Logging in to the UMC Web UI............................................................................................ 94
4.1.3 Home page of the UMC Web UI .......................................................................................... 96
4.2 Changing user profile ......................................................................................................... 97
4.2.1 Changing Password............................................................................................................ 97
4.2.2 Changing Language ........................................................................................................... 98
4.2.3 Generating a Secret Key ..................................................................................................... 99
4.3 Managing UM users ......................................................................................................... 101
4.3.1 Creating UMC users ......................................................................................................... 102
4.3.2 Updating UM users .......................................................................................................... 103
4.3.2.1 Editing User Attributes ..................................................................................................... 105
4.3.2.2 Assigning UM role to a user.............................................................................................. 106
4.3.2.3 Editing account policies ................................................................................................... 106
4.3.3 Importing AD users .......................................................................................................... 108
4.3.4 Unlocking UM users ......................................................................................................... 111
4.4 Managing UM groups....................................................................................................... 112
4.4.1 Creating UM groups ......................................................................................................... 112
4.4.2 Updating UM groups ........................................................................................................ 113
4.4.3 Importing AD groups........................................................................................................ 115
4.4.4 Deleting UM groups ......................................................................................................... 118
4.5 Managing UM roles.......................................................................................................... 119
4.5.1 Creating UM roles ............................................................................................................ 119
4.5.2 Updating UM roles ........................................................................................................... 121
4.6 Managing account policies............................................................................................... 123
4.7 Managing UMC licenses ................................................................................................... 128
4.8 Managing IdP configurations ............................................................................................ 130
4.8.1 Configuring authentication options .................................................................................. 131
4.8.2 Configuring disclaimers.................................................................................................... 133

UMC - Central User Management

4 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Table of contents

4.8.3 Configuring Languages .................................................................................................... 133

4.9 Managing system users.................................................................................................... 136
4.10 Viewing event log ............................................................................................................ 137
4.11 Parameter sizes................................................................................................................ 140
5 UMC security concept ........................................................................................................................ 141
5.1 Introduction..................................................................................................................... 141
5.2 Security strategies............................................................................................................ 142
5.2.1 Plant security ................................................................................................................... 142
5.2.2 Network security.............................................................................................................. 142
5.2.3 System integrity............................................................................................................... 142
5.3 Security implementation .................................................................................................. 143
5.3.1 Step-by-step guide to security implementation ................................................................. 143
5.3.2 Network security implementation .................................................................................... 144
5.3.2.1 Security cells and perimeter networks .............................................................................. 144
5.3.2.2 Firewalls and VPNs ........................................................................................................... 149
5.3.3 System integrity implementation ..................................................................................... 149
5.3.3.1 System hardening ............................................................................................................ 150
5.3.3.2 Allowlisting...................................................................................................................... 155
5.3.3.3 Disaster recovery ............................................................................................................. 157
5.3.3.4 Security controller............................................................................................................ 158
5.3.3.5 Patch management.......................................................................................................... 158
5.3.3.6 Malware detection and prevention ................................................................................... 159
5.3.3.7 User account management .............................................................................................. 160
5.3.3.8 UMC Web UI redirect validation ........................................................................................ 164
6 References ......................................................................................................................................... 165
6.1 UMCONF reference .......................................................................................................... 165
6.1.1 UMCONF overview........................................................................................................... 165
6.1.2 Overview of UMCONF commands..................................................................................... 166
6.1.2.1 View help ........................................................................................................................ 166
6.1.3 Creating UM objects......................................................................................................... 166
6.1.3.1 Create UM domain ........................................................................................................... 166
6.1.3.2 Creating administrator ..................................................................................................... 167
6.1.3.3 Create claim key............................................................................................................... 168
6.1.4 Managing UM services ..................................................................................................... 169
6.1.4.1 Assign Windows user to the "UP Service" service ............................................................... 169
6.1.4.2 Assign user to the "UMC Service" service .......................................................................... 170
6.1.4.3 Set secure LDAP connection for the "UP Service" service.................................................... 170
6.1.4.4 Query and change GUM port............................................................................................ 171
6.1.5 Execute binding/unbinding commands............................................................................. 172
6.1.5.1 Attach UMC agent............................................................................................................ 172
6.1.5.2 Join UMC server ............................................................................................................... 173
6.1.5.3 Unjoin server ................................................................................................................... 175
6.1.5.4 Retrieve fingerprint .......................................................................................................... 175
6.1.6 Managing central configurations ...................................................................................... 176
6.1.6.1 Retrieve default configuration file ..................................................................................... 176
6.1.6.2 Set up central configuration ............................................................................................. 176
6.1.6.3 Retrieve central configuration........................................................................................... 177
6.1.7 Upgrading UM objects...................................................................................................... 177

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 5
Table of contents

6.1.7.1 Upgrade UM domain........................................................................................................ 177

6.1.8 Deleting UMC configuration ............................................................................................. 178
6.1.8.1 Delete UMC configuration ................................................................................................ 178
6.1.9 Managing allowlist entries ............................................................................................... 179
6.1.9.1 Create allowlist entry ....................................................................................................... 179
6.1.9.2 List allowlist entries ......................................................................................................... 179
6.1.9.3 Remove allowlist entry ..................................................................................................... 180
6.1.10 Manage plugins ............................................................................................................... 180
6.1.10.1 Register cookie adapter .................................................................................................... 180
6.1.10.2 List registered plugins ...................................................................................................... 181
6.1.10.3 Deregister plugin ............................................................................................................. 182
6.1.11 Managing log files............................................................................................................ 183
6.1.11.1 Archive log files................................................................................................................ 183
6.1.11.2 Extract log files ................................................................................................................ 183
6.1.12 Renewing certificates ....................................................................................................... 184
6.1.12.1 Renew certificate ............................................................................................................. 184
6.1.12.2 Renew network certificates............................................................................................... 185
6.1.13 Starting UMCONF in interactive mode .............................................................................. 186
6.1.13.1 Start interactive operation................................................................................................ 186
6.1.14 Delete UM roles ............................................................................................................... 187
6.1.14.1 Purge Role IDs.................................................................................................................. 187
6.1.15 Show Lists ....................................................................................................................... 187
6.1.15.1 Display server list ............................................................................................................. 187
6.1.16 Enabling or disabling DSSO .............................................................................................. 188
6.1.17 Managing SLRA functionality............................................................................................ 188
6.1.17.1 Manage SLRA functionality............................................................................................... 188
6.1.18 Managing GUM server list ................................................................................................ 189
6.1.18.1 Commands for the management of the GUM server list .................................................... 189
6.1.18.2 Create GUM list entry ....................................................................................................... 190
6.1.18.3 List GUM list entry ........................................................................................................... 191
6.1.18.4 Remove GUM list entry..................................................................................................... 191
6.1.19 Error codes ...................................................................................................................... 192
6.2 UMX reference................................................................................................................. 193
6.2.1 UMX overview ................................................................................................................. 193
6.2.2 Viewing UMX information ................................................................................................ 194
6.2.2.1 View help ........................................................................................................................ 194
6.2.3 Creating UMC objects....................................................................................................... 195
6.2.3.1 Create UM user ................................................................................................................ 195
6.2.3.2 Create UM group.............................................................................................................. 196
6.2.3.3 Create UM role................................................................................................................. 197
6.2.4 Updating UMC objects ..................................................................................................... 198
6.2.4.1 Update UM user ............................................................................................................... 198
6.2.4.2 Update UM group ............................................................................................................ 200
6.2.4.3 Update UM user alias ....................................................................................................... 201
6.2.4.4 Update UMC user attribute............................................................................................... 202
6.2.5 Polling information about UMC objects............................................................................. 202
6.2.5.1 Create list with object details............................................................................................ 202
6.2.5.2 List event log records ....................................................................................................... 203
6.2.6 Displaying lists of UMC or Windows objects ...................................................................... 204
6.2.6.1 Create list of objects......................................................................................................... 204
6.2.6.2 Count objects .................................................................................................................. 205
6.2.7 Deleting UMC objects....................................................................................................... 206

UMC - Central User Management

6 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Table of contents

6.2.7.1 Delete object ................................................................................................................... 206

6.2.8 Executing binding/unbinding commands.......................................................................... 207
6.2.8.1 Overview of binding/unbinding commands ...................................................................... 207
6.2.8.2 Add attribute to a UM user ............................................................................................... 208
6.2.8.3 Add attribute to a UM user - Size ...................................................................................... 208
6.2.8.4 Add a set of attributes to a UM user.................................................................................. 209
6.2.8.5 Add alias name to a UM user ............................................................................................ 210
6.2.8.6 Assign a UM group/UM role to a UM user.......................................................................... 210
6.2.8.7 Assign a UM role to a UM group ....................................................................................... 211
6.2.8.8 Assigning a UM function right to a UM role....................................................................... 212
6.2.8.9 Remove UM user from a UM group/UM role ...................................................................... 213
6.2.8.10 Remove UM role from a UM group.................................................................................... 213
6.2.8.11 Remove attribute of a UM user ......................................................................................... 214
6.2.8.12 Remove alias name of a UM user ...................................................................................... 214
6.2.8.13 Remove UM function right from a UM role........................................................................ 215
6.2.9 Importing and exporting UMC users and UMC groups....................................................... 216
6.2.9.1 Overview of import/export commands ............................................................................. 216
6.2.9.2 Import objects from a file ................................................................................................. 216
6.2.9.3 Export objects to a file...................................................................................................... 225
6.2.9.4 Import local users or virtual user accounts........................................................................ 226
6.2.9.5 Import AD users ............................................................................................................... 227
6.2.9.6 Import AD groups ............................................................................................................ 228
6.2.9.7 Import AD Groups with LDAP query .................................................................................. 229
6.2.10 Execute administrative commands ................................................................................... 230
6.2.10.1 Set user password ............................................................................................................ 230
6.2.10.2 Enable UM user................................................................................................................ 230
6.2.10.3 Disable UM user............................................................................................................... 231
6.2.10.4 Unlock UM user ............................................................................................................... 231
6.2.10.5 Disable safe mode............................................................................................................ 232
6.2.10.6 Show status ..................................................................................................................... 233
6.2.10.7 Retrieve domain ID........................................................................................................... 235
6.2.10.8 Get domain name ............................................................................................................ 236
6.2.10.9 Generate or reset secret key for 2FA ................................................................................. 236
6.2.10.10 Change user language ..................................................................................................... 237
6.2.10.11 Change language of the user data.................................................................................... 237
6.2.10.12 Display user properties..................................................................................................... 238
6.2.10.13 Force synchronization of the "UP Service" service.............................................................. 238
6.2.11 Managing account policies............................................................................................... 239
6.2.11.1 Change account policies - Passwords ................................................................................ 239
6.2.11.2 Change account policies – Assign Windows user to the "UP Service" service ...................... 240
6.2.11.3 Change account policies - Restore .................................................................................... 241
6.2.11.4 Change account policies - Set default PKI rule ................................................................... 242
6.2.11.5 Change account policies - Reset default PKI rule................................................................ 243
6.2.11.6 Change account policies - Secure Application Data Support .............................................. 243
6.2.11.7 Change account policies - Enable password check............................................................. 243
6.2.11.8 Change account policies - Disable password check............................................................ 243
6.2.12 Execute commands in interactive mode............................................................................ 244
6.2.12.1 Interactive mode.............................................................................................................. 244
6.2.12.2 Enable notifications.......................................................................................................... 244
6.2.13 Execute authentication commands................................................................................... 245
6.2.13.1 Test authentication .......................................................................................................... 245
6.2.13.2 Generate ticket ................................................................................................................ 245

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 7
Table of contents

6.2.13.3 Change user password ..................................................................................................... 246

6.2.14 Working with Secure Application Data Support (SADS)...................................................... 247
6.2.14.1 Overview of data encryption and decryption commands................................................... 247
6.2.14.2 Enable encryption............................................................................................................ 247
6.2.14.3 Encrypt keys .................................................................................................................... 248
6.2.14.4 Decrypt keys .................................................................................................................... 248
6.2.15 Error codes ...................................................................................................................... 249
6.2.15.1 Error codes ...................................................................................................................... 249
6.2.15.2 UMC APIs error codes ....................................................................................................... 250
6.2.16 Parameter sizes................................................................................................................ 255

UMC - Central User Management

8 Programming and Operating Manual, 11/2023, A5E52954435-AA
Cybersecurity information 1
Siemens provides products and solutions with industrial cybersecurity 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
cybersecurity concept. Siemens’ products and solutions constitute one element of such a
concept.
Customers are responsible for preventing unauthorized access to their plants, systems,
machines and networks. Such systems, machines and components should only be connected
to an enterprise network or the internet if and to the extent such a connection is necessary
and only when appropriate security measures (e.g. firewalls and/or network segmentation)
are in place.
For additional information on industrial cybersecurity measures that may be implemented,
please visit
https://www.siemens.com/global/en/products/automation/topic-areas/industrial-
cybersecurity.html (https://www.siemens.com/global/en/products/automation/topic-areas/
industrial-cybersecurity.html).
Siemens’ products and solutions undergo continuous development to make them more
secure. Siemens strongly recommends that product updates are applied as soon as they are
available and that the latest product versions are used. Use of product versions that are no
longer supported, and failure to apply the latest updates may increase customer’s exposure
to cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Cybersecurity
RSS Feed under
https://new.siemens.com/global/en/products/services/cert.html (https://new.siemens.com/
global/en/products/services/cert.html).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 9
Cybersecurity information

UMC - Central User Management

10 Programming and Operating Manual, 11/2023, A5E52954435-AA
Basics of UMC 2
2.1 Introduction to UMC

Overview
UMC allows you to set up a central user management, i.e. you can define and manage users and
user groups across software and devices. Users and user groups can also be transferred from
Microsoft Active Directory. You can import the central users and user groups into various
applications.
An efficient user management is an essential part of any security concept. The user
management of UMC allows for the
plant-wide, central management of users with optional connection of Microsoft Active
Directory. Thanks to the specific assignment of UM roles and rights to individuals,
maintenance is minimized while achieving a high degree of transparency. The central
user management thus forms the basis for an efficient and integrated management of
personalized access rights in the plant. In this way, security risks can be significantly reduced.

Advantages and benefits of a central user management

The international standard IEC 62443 deals with cyber security in industrial automation
systems. In the standard, the following topics, among others, are of crucial importance:
• Authentication
• Authorization
• Centralized user management
It must be possible to identify users (authentication) and, depending on the person, to grant
appropriate rights on the system (authorization).
A decentralized user management, where the users are stored locally on each system or
component, is inefficient for larger systems and not manageable in the long run. Therefore, a
central user management is of utmost importance.
With a central user management, the components only have to forward the authentication
request to the central office and grant access (depending on authorization) following
successful feedback from the central office.

Note
The concept of User Management and Access Control (UMAC) provides for user management to
take place in UMC but rights to be managed locally in the application.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 11
Basics of UMC
2.1 Introduction to UMC

Additional information about UMC

The SiePortal provides you with additional information on installation and configuration as well
as on the connection of UMC to various Siemens products. You can find the application examples
as PDF documents under Central user management with the "User Management Component
(UMC)" (https://support.industry.siemens.com/cs/us/en/view/109780337).

UMC - Central User Management

12 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Basics of UMC
2.2 Abbreviations

2.2 Abbreviations

Abbreviation/acronym Explanation
AD Microsoft Active Directory
CSV Comma Separated Values (file format)
DSSO Desktop Single Sign-on
FQDN Fully qualified domain name
GUM Global User Management
ID Identifier
JSON JavaScript Object Notation (data format)
IdP Identity provider
MES/MOM Manufacturing Execution System/Manufacturing
Operation Management
NLB Network load balancing
SADS Secure Application Data Support
SID Security identifier
SLRA Simatic Logon Remote Authentication
TOTP Time-based one-time password
UM User management
UMC User Management Component

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 13
Basics of UMC
2.3 Definitions

2.3 Definitions

2.3.1 UM domain
A UM domain (user management domain) is a collection of computers that share a common
directory database. A UM domain provides access to the centralized user and group accounts
that are maintained by the UM domain administrator.

Note
UM domains are entities other than Windows domains, which are defined at the operating
system level.

2.3.2 UM user
A UM user (User Management user) is a user in the UMC database identified by a user name. It
should be noted that UM users are entities other than local users, which are defined at the
operating system level.
UM users can be assigned customer-specific attributes. An example of such attributes are
common user properties such as telephone number, department and so on.
For Secure Application Data Support (SADS), authorized users can be granted access to
encrypted application data so that they can decrypt it with specific Subject Keys.

UM user types
A distinction is made between three UM user types:
• UMC users created in UMC or created via a CSV file.
Each user created in UMC has an associated password. Empty passwords are not allowed.
• AD users imported into UMC via the UMX utility or the UMC Web UI. In this case, the user
name follows the pattern <ADdomainName>\ <ADuserName>.
Users imported from Active Directory authenticate themselves to Active Directory and do not
have a UMC password.
For information on the offline availability of AD users, see section "Computer roles
(Page 18)".
• Local users imported into UMC via the UMX utility. In this case, the user name follows the
pattern <machineName>\ <localUserName>.
Imported local users only authenticate themselves to Windows on the computer they are
working on. They can only be used for configuration purposes, for example for the
assignment to a Windows service that is running on the computer.

UMC - Central User Management

14 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Basics of UMC
2.3 Definitions

Offline user
When creating a UMC user, this user can be marked as offline. The "UP Service" checks whether
the offline user exists in Active Directory. If the user is there, the user data is synchronized and
the user is online. Otherwise he remains offline.

Note
Users who have been created as "offline" via the umx utility are basically activated. Therefore,
they can perform all the actions that are allowed by their UM function rights.

The user name of offline users must follow the AD pattern

<ADdomainName>\<ADuserName>. These users do not have a UMC password because
their authentication is only possible when they are online. The "User Security Identifier" (SID)
property is set to the default value of "S-1-0-0", which is synchronized with the actual AD
value by the "UP Service".
For more information about SID, see the Microsoft documentation on "Security
Identifier": https://learn.microsoft.com/de-de/windows/win32/secauthz/security-identifiers?
redirectedfrom=MSDN (https://learn.microsoft.com/en-us/windows/win32/secauthz/security-
identifiers?redirectedfrom=MSDN)
Users are also flagged as "offline" if they are deleted in AD. These users are then permanently
deleted from the UMC database after a certain time. You can either set this time yourself or
adopt the default of 12 hours.

Limits for UM users

Description Maximum
Number of UM roles assigned to a UM user 50
Number of UM groups assigned to a UM user 50

2.3.3 UM group
A UM group (User Management group) is a container with users that is identified by a name. It
should be noted that UM groups are different entities than Windows groups, which are defined
at the operating system level.

UM group types
There are two types of UM groups:
• UMC groups created in UMC or created via a CSV file.
• AD groups (Active Directory groups) imported into UMC via the UMX utility or the UMC Web
UI.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 15
Basics of UMC
2.3 Definitions

Offline groups
When creating a UMC group, it can be marked as offline. The "UP Service" checks whether the
offline user exists in Active Directory:
• If the group exists, the group data is synchronized. The AD users who are members of the
group are imported into UMC and the group changes to online.
• If the group does not exist in the Active Directory, it remains offline.
The group name must follow the AD pattern "<ADdomainName>\<ADgroupName>". The
"UP Service" searches for the AD group by its Common Name (CN).
If necessary, the manner in which the "UP Service" is to query the AD group and import
its users into UMC can be configured using the description field of the created group. The
description must then conform to this pattern:
{{Q=<ldap query>
Here {{Q= is a fixed prefix and <ldap query=> is the query in question. The group name
can then be "<ADdomainName>\ <GroupName>", whereby the entry for "GroupName" can
be selected by the user.

Limits for groups

Description Maximum
Number of UM groups assigned to a UM user 50
Number of UM roles in a UM group 50
Number of UM users in a UM group 1000

2.3.4 UM role
A UM role (User Management role) includes a number of UM function rights. UM function rights
allow a user to perform certain functions. They are assigned to UM roles so that UM users with a
specific UM role are allowed to perform the operations assigned to that UM role. UM roles can
be associated with UM users or UM groups so that all UM users in such a UM group inherit the
UM function rights of the UM role. With the help of the UM roles, the UM function rights are
defined in UMC, for example, whether a UM user is allowed to configure UMC or not.
The following UM roles are automatically created by the system when the UMC is configured:
• UM role "Administrator": Integrated administrator role that is allowed to perform any
operation.
This UM role cannot be assigned to a UM group. It can only be assigned to a UM user if the
UM user who makes the assignment also has the UM role "Administrator". You cannot delete
the UM role "Administrator". Only users with the UM role "Administrator" can edit other UM
users with this UM role. Account policies have no effect on the integrated administrator role.
• UM role "UMC admin" Can manage UM users, UM groups, and all other UM entities.
• UM role "UMC Viewer": Can access the configuration of the user management but cannot
make any changes.

UMC - Central User Management

16 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Basics of UMC
2.3 Definitions

2.3.5 UM function rights

UM function rights (User Management function rights) allow a UM user to perform certain
functions. UM function rights are assigned to UM roles. Therefore, a UM user with a specific UM
role is allowed to perform the functions assigned to that UM role. The following table contains
a list of the UM function rights:

Name Description
UM_ADMIN Allows the execution of the following functions:
• Viewing the data from the UMC database, such as UM users or UM groups
• Configuring the data in the UMC database
• Importing and exporting of data using a file
• Registering UMC station clients
• Executing all UMX commands
UM_VIEW Allows the viewing of data for UM users, UM groups, UM roles and account policies from the
UMC database.
UM_RESETPWD Allows the resetting of another UM user's password. In addition, the UM function right
"UM_VIEW" is required.
UM_UNLOCKUSR Allows the unlocking of another UM user. In addition, the UM function right "UM_VIEW" is
required.
UM_ATTACH Allows the connection of a computer to a UM domain. This computer is then promoted to the
UM role "UM Agent".
UM_JOIN Allows the promotion of a computer to the "UM Server" computer role. In doing so, it is con‐
nected to the UM domain if necessary. This UM function right includes the UM function right
"UM_ATTACH".
UM_RESETJOIN Allows the demotion of a computer from the computer role "UMC Ring Server" or "UMC Server"
to the UM role "UMC Agent".
UM_IMPORT Allows the import of a UM configuration from a package. In addition, the UM function right
"UM_VIEW" is required.
UM_EXPORT Allows the export of a UM configuration to a package. In addition, the UM function right
"UM_VIEW" is required.
UM_BACKUP Allows the backup a UM configuration as a full backup.
UM_EXPORTCK Allows the export of claim keys.
UM_EXPORTDK Allows the export of domain keys.
UM_RA Allows login using a remote authentication.
UM_RINGMNG Allows the promotion of a computer to the UM role "UM Ring Server". In doing so, it is connected
to the UM domain if necessary.
UM_ADSYNC Allows the execution of the synchronization of the AD provisioning service in the background.
UM_VIEWELG Allows the viewing of event log data. In addition, the UM function right "UM_VIEW" is required.
UM_CLAIMAUTH Allows the creation of an identity from a valid claim.
UM_REGCLIENT Allows the registering of clients for the UMC station.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 17
Basics of UMC
2.3 Definitions

2.3.6 Computer roles

Roles for UMC computers

In a typical UMC scenario, there are the following computer roles:
UMC ring server: The owner of the UMC configuration, which is responsible for managing
the UMC domain and providing the full implementation of the authentication and user
management functions. Priority is given to the UMC ring server that is configured first and
on which the UMCONF utility is run. If more than one UMC ring server is available and the
connection of the primary UMC ring server is disconnected, the system dynamically selects a
new primary UMC ring server.
UMC server: Provides the full implementation of authentication functions. The UMC server is
in emergency mode if it is not connected to a UMC ring server.
UMC runtime server: Provides the full implementation of authentication functions.
However, engineering tasks, with the exception of password changes, are only possible when
connected to a UMC server or UMC ring server by means of the REST API (Web UI/Service
Layer). This role is a simple role with a focus on the activities required to run a desktop
application and a faster connectivity process. The UMC runtime server is in emergency mode
if it is not directly or indirectly connected to a UMC ring server or UMC server. The UMC
runtime server can connect directly to the UMC ring server or use a server or another UMC
runtime server as a proxy. The network topology is automatically adjusted to automatically
balance the connection and reduce resource consumption on the UMC ring server without
increasing infrastructure requirements.
UMC agent: Acts as a client of the UMC server/UMC ring server to which it is connected,
and on which an application developed with the UMC API can be executed. To import a
local Windows user into an agent, see Importing a local Windows user into a UMC agent
(Page 81).

Note
The UMC agent does not allow any engineering tasks, except for encryption activation.

The main differences between the three roles mentioned above are listed in the following
table.
The UMC ring server to which the other UMC ring servers send requests to write to the UMC
database (write candidate) is called the master ring server. Both the primary UMC ring server
and the secondary UMC ring server can be the master.
If the primary server is the master, writing is enabled and the computer can write to the UMC
database.
In the event of an error, the secondary UMC ring server becomes the master ring server
without activated writing (safe mode). If safe mode is switched off with the corresponding
umx command, the secondary UMC ring server becomes the master and writing is activated.
Note that in this case certain actions in the UMC system configuration are not possible, e.g.
editing the allowlist.

UMC - Central User Management

18 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Basics of UMC
2.3 Definitions

UMC station client

Computer role that is on an equal footing with the roles described above. A UMC station client
is a computer on which the UMC station client software has been installed and that has been
registered as a trusted computer. A UMC station client makes a claim containing certified login
station data. With the help of this data, the client product can be used to assign authorization
rights to a computer that does not need to be a UMC ring server, UMC server, or UMC agent.
A UMC installation includes the UMC station client installation, so UMC ring servers, UMC
servers, and UMC agents only need to register to become UMC station clients, while on a
computer that does not belong to the UMC domain, the UMC station client software must
first be installed and then the computer must be registered to become a UMC station client.

Note
If you want to manage AD users, the UMC ring server and the UMC server computers must be
connected to the AD domain.

Functionalities of the computer roles

The following table shows the assignment of functionalities according to the computer roles.
The following symbols indicate the supported functionality:

Indicates that the functionality has been fully implemented

Indicates that the functionality is not available

Indicates that the functionality is only available when the system is connected to the UMC
server

UMC runtime server UMC server UMC ring server UMC agent
Execute TIA user authen‐
tication
Local individual changes
Change password
Authentication to Active
Directory
Attach/connect to UM
domain (acts as a proxy for
agents)
Potential master
Can sign authentication
object
Transfer UMC configura‐
tion (only when connected
to the ring)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 19
Basics of UMC
2.3 Definitions

UMC runtime server UMC server UMC ring server UMC agent
Can host identity provid‐
er/remote authentica‐
tion or
UMC Web UI
Number of instances max. 150 max. 4 1-2 max. 25
Offline authentication/
write protection for con‐
figuration
Ring failover recovery
Store and forward elec‐
tronic log
Protocol forwarding
Import local Windows
users
Import AD user/group
AD cache
SLRA
DSSO

Transfer of the UMC configuration

The UMC configuration is transferred from the UMC master ring server to the UMC servers to
enable faster local authentication. Changes to the configuration are made in the primary UMC
master ring server and transferred to the connected UMC servers. The synchronization of the
configuration starts as soon as at least 30 seconds have passed since the last change. This
stabilization time is necessary to avoid an excess of adjustments when many changes are made
in a short period of time. After this time, the transfer of the configuration begins, which means
it will take a little longer (from a few seconds up to a few minutes) until the configuration is
adjusted on all UMC servers.

Offline availability of UMC users

Since the UMC configuration is forwarded from the UMC master ring server to the UMC servers,
the UMC users are authenticated locally. Therefore, authentication of the UMC users on the UMC
servers is available even if the UMC server is disconnected from the UMC ring server, provided
that the configuration was transferred before the connection was disconnected.

Offline availability of AD users

The authentication of AD users is performed by Windows. In addition, a centralized cache is
provided. This also allows you to authenticate with your Active Directory access data in the
following cases:
• If no network connection is available.
• If you were not previously logged in to this UMC server.

UMC - Central User Management

20 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Basics of UMC
2.3 Definitions

Note
Enable and disable cache
To enable the cache, proceed as follows:
1. Open the "Account policies" menu.
2. Switch to the "Password lockout, duration and reuse" tab.
3. Set a value >0 in the "Number of days before Active Directory cache expires" field.
To disable the cache, set the value "0" in the "Number of days before Active Directory cache
expires" field.

The access data in the cache are transferred to the UMC database as "salted hashes". The
cache is provided or updated during authentication or a password change. It is maintained in
the primary UMC ring server and forwarded to the secondary UMC ring server and the UMC
servers. If authentication with AD fails in the event of a specific network error, UMC performs
authentication based on the information in the cache.
The cache for user passwords has a configurable expiration date. A new global policy is
available for enabling the cache and setting its expiration date. Permitted values are: 30-250
days (1-8 months). The default is 0, which means that the cache is disabled. The policy can
be set up using UMX, the UMC Web UI and a JSON import and is managed centrally. The
password cache expires if there is no login for this user within the specified time period. The
period of validity can be updated in increments of 2 days.
If the cache is disabled, the passwords are no longer stored in the cache and are no longer
updated. However, the passwords already stored in the cache (when the policy is enabled)
are not removed from the cache.
The update of the password cache for AD users is an engineering action. Therefore:
• Before the password is forwarded, it must also be updated on the UMC ring server. If the
authentication or password change is performed on a server, the new password is only
updated when the UMC ring server is reached.
• The propagation is delayed for at least 30 seconds (as for the other engineering actions).
• If the AD user password is changed via UMC, no additional login is required for offline
availability on all stations.

Offline availability of SADS

The configuration of the Secure Application Data Support is not set up by default on UMC
servers. Therefore, Secure Application Data Support (SADS) is not available if the UMC server is
disconnected from the UMC ring server. It can be configured for a group to allow the users of that
group to use SADS even when they are offline. For the configured group, the required SADS
configuration is forwarded from the UMC ring server to the UMC servers so that local use is
possible.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 21
Basics of UMC
2.3 Definitions

2.3.7 Provisioning scenarios

The following provisioning scenarios are supported:
• Standalone scenario: A UMC ring server on which UMC and all web components are
installed and configured. A quick configuration guide is available for this scenario.
• Redundant scenario:
– 2 UMC ring servers, of which one is configured first and is considered the primary UMC
ring server, and the second is added with the join command in the ring
– up to 4 UMC servers
• Central scenario:
– 1 or 2 UMC ring servers, of which one is configured first and is considered the primary
UMC ring server, and the second is added in the ring with the join command
– up to 4 UMC servers
– up to 25 UMC agents
Each UMC web component can be installed and configured on any UMC ring server and/or
any UMC server. If the UMC Web UI is installed on a UMC server, AD users cannot be
imported via the UMC Web UI.
The NLB redundancy is supported only for the identity provider.

Standalone engineering station

With UMC, configuration data (users, groups, etc.) can be prepared in a standalone engineering
station and exported to a UMC configuration package, which can then be imported into a target
system in production. The two package commands "umx export" and "import" are used for this
purpose. If you want to overwrite the configuration of the target production system with the
configuration of the engineering source computer, the update command can be used instead of
the import command. For more information on these commands and what effect they have on
the target computer, see the UMX reference.
If no target system is configured, you can import a package with the "umconf import
package" command. For more information, see the UMCONF reference.

2.3.8 Claim key

A claim is a claim that an instance, e.g. a person or organization, makes for itself or another
instance. The instance that makes the claim(s) is the provider. This mechanism is used for the
web authentication. When the user authenticates himself to the identity provider, he receives a
claim. This claim is signed with the private claim key. Once a relying party needs to verify the
claim, it uses the corresponding public claim key that has been previously installed in the
instance. How this public claim key is installed is the responsibility of the relying party.

UMC - Central User Management

22 Programming and Operating Manual, 11/2023, A5E52954435-AA
Installing and configuring UMC 3
3.1 Prerequisites

3.1.1 General recommendations and requirements

Operating systems
• The operating system must be updated with the latest security patches to improve the
reliability and security of the system.
• The operating system must be based on the Windows NT kernel.
• UMC cannot be installed on Windows Vista or older Windows versions.

Browser
• The browser used to display the UMC Web UI must allow the display of popups.
• When using the UMC Web UI, do not select the "Prevent this page from creating more
dialogues" option. The selection of this option will result in malfunctions of the UMC Web UI.
• Disable the "Autocomplete" option in the settings of your browser.
• Disable the option to save passwords in the settings of your browser.

Time synchronization
The time synchronization of the computer in a UMC network is an essential requirement,
without which some important functions could be impaired.
In particular, the authentications performed through tickets can fail in the absence of time
synchronization, since the validity and duration of the tickets themselves are based on their
creation date.
For example, functions that use this type of authentication internally, such as SADS
encryption and decryption, may not work properly. Connecting UMC servers and clients in
the network would also fail due to a certificate validation error.
The time synchronization affects all UMC servers and clients, without distinction of role.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 23
Installing and configuring UMC
3.1 Prerequisites

3.1.2 Supported browsers

Use of the following browser versions ensures a successful configuration of the identity provider
and UMC Web UI:
• Microsoft Edge 92.0.902.67 or higher
• Chrome 105.0.5195.102 or higher
Use of the following browser versions generally allows, but does not ensure, a successful
configuration of the identity provider and UMC Web UI:
• Microsoft Edge 25.10586.0.0 or higher
• Microsoft Edge 83.0.478.58 (based on Chromium)
• Chrome 32.0.1700.107 or higher
• Firefox 31.0 or higher

3.1.3 Supported operating systems

The following operating systems are required for a successful installation of UMC:
• Windows 10 Version 21H2 or higher
• Windows 11 Version 21H2 or higher
• Windows Server 2019 (Datacenter, Essentials, Standard)
Installation of UMC is possible with the following operating systems but not recommended:
• Windows 7 SP1 (x64)
• Windows 8.1 (x64)
• Windows Server 2008 R2 SP1 (Standard, Datacenter Edition)
• Windows Server 2012 R2 (Standard, Datacenter Edition)
• Windows Server 2016 (Standard)

3.1.4 Microsoft Visual C++

To install UMC, the following redistributable package must have been installed:
• Microsoft Visual C++ 2019 Redistributable - x64 14.29.30139.0

Note
In the BUNDLE and SIWA installation programs, the redistributable packages are installed
automatically.

UMC - Central User Management

24 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.1 Prerequisites

3.1.5 Identity Provider prerequisites

• Microsoft Framework:
– Microsoft .NET Framework 4 Client Profile
– Microsoft .NET Framework 4 Extended
• Microsoft Internet Information Services (IIS):
– IIS 7.5, 8, 8.5 or 10.
Note that for the IIS 7.5 you need to add JSON to the MIME types.
• IIS extension "Application Request Routing 3.0" including prerequisites has been
downloaded and installed.
Run the file on the computer and search for "Application Request Routing".

Note
The UMC web services use cookies to ensure correct functioning. No warning is displayed
regarding the use of cookies, since the application may not be used as an open web service,
which is available, for example, on the Internet.

3.1.6 Requirements of Microsoft IIS Manager

To enable configurations with Internet Information Services (IIS) Manager, the features
described below must be enabled on Windows. The steps to check and enable the functions vary
depending on the version of Windows you are using. The required functions for Windows 10 and
Windows Server are described below.
• In Windows 10, open the Turn Windows features on or off application. Make sure that the
functions listed in the "Windows 10" section are turned on.
• In Windows Server, open the Server Manager application. Click "Add Roles and Features"
in the "Manage" menu and select a server. Make sure that the functions listed in the
"Windows Server" section are enabled.

Windows 10
.NET Framework 3.5
.NET Framework 4.8 Advanced Services
• ASP.NET 4.8
• WCF services
– TCP port sharing

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 25
Installing and configuring UMC
3.1 Prerequisites

Internet Information Services

• Web management tools
– IIS management service
– IIS management console
– IIS management scripts and tools
• WWW services
– General HTTP features:
HTTP error
Default document
Static content
Directory browsing
– Application development features:
.NET Extensibility 4.8
ASP.NET 4.8
ISAPI Extensions
ISAPI Filters
– Performance features:
Static content compression
– Security:
Request filtering
Windows authentication
– System status and diagnostics:
HTTP logging
Windows PowerShell 2.0
• Windows PowerShell 2.0 Engine

Windows Server
Web server
• General HTTP features
– Default document
– Directory search
– HTTP error
– Static content
• System status and diagnostics
– HTTP logging
• Power
– Static content compression

UMC - Central User Management

26 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.1 Prerequisites

• Security
– Request filtering
– Windows authentication
• Application development
– .NET Extensibility 4.6
– ASP.NET 4.6
– ISAPI extension
– ISAPI Filters
Management tools
• IIS management console
• IIS management scripts and tools
• Management service
.NET Framework 3.5 Features
• .NET Framework 3.5 (includes .NET 2.0 and 3.0)
.NET Framework 4.6 Features
• .NET Framework 4.6
• ASP.NET 4.6
• WCF services
– TCP port sharing
• Windows PowerShell
– Windows PowerShell 5.1
– Windows PowerShell 2.0 Engine
– Windows PowerShell ISE

Recommendation
.NET Framework 4.6 Features
• Windows Defender Features and WoW64 Support
– Windows Defender
– GUI for Windows Defender

3.1.7 Configuring the HTTPS protocol in Microsoft IIS Manager

This procedure allows you to configure IIS to work with the HTTPS protocol and is required if you
want to use the HTTPS protocol, which is highly recommended in plant environments.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 27
Installing and configuring UMC
3.1 Prerequisites

Requirements
A valid SSL certificate has been acquired from a certificate authority or a self-signed SSL
certificate has been created.

Procedure
1. Open the IIS Manager.
2. In the tree topology on the left, select the node of the website you have configured.
3. Right-click on the node and select "Edit bindings".
4. Click "Add".
The following dialog opens.

5. Enter the parameters as in the previous figure and click "OK".

The SSL certificate parameter must be the name of the certificate acquired.
6. Click "OK" and then "Close".

UMC - Central User Management

28 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.2 Installing UMC

3.2 Installing UMC

UMC is automatically installed when the TIA Portal is installed.
UMC can also be installed separately. The installation file "TIA_UMC_V2.exe" for UMC and the
English-language documentation for UMC can be found on the TIA Portal installation disc
(DVD 2) in the "Support" and "Documentation" folders.

Note
Setup limitations
The UMC installation fails when it is installed on a Windows AD Domain Controller because local
groups that were created at the end of the setup phase cannot be created on these computers.

Requirements
• The requirements for the installation for UMC are met. You can find additional information in
the section "Prerequisites (Page 23)".
• You have administrator rights on Windows.

Procedure
1. Run the "Start.exe" file in the UMC installation directory.
Before the installation can be performed, a restart of your computer is required.
After your computer restarts, the installation program will open again.
2. Select the installation language and click "Next".
3. Select the components to be installed.
4. If necessary, change the target directory for the installation and click "Next".
5. Read and confirm the license terms and security information by selecting the check boxes.
6. Click "Next".
An overview of the product configuration is displayed.
7. Click "Install".

Result
UMC is installed on your computer.
To use UMC, you must first configure UMC (Page 30).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 29
Installing and configuring UMC
3.3 Configuring UMC

3.3 Configuring UMC

The UMC allows the following configurations:
• Standalone scenario in which only one primary UMC ring server is configured.
• Redundant scenario by adding a secondary UMC ring server.
• Decentralized scenario with multiple UMC servers, UMC agents, and UMC station clients.
Depending on your scenario, use one of the following workflows:
• For a simple standalone UMC installation on a computer with HTTPS, use the
scenario Configuring standalone UMC scenario (Page 30).
• For decentralized and redundant scenarios or additional configurations, use the
scenario Configuring UMC scenario (Page 31).

HTTP configuration

Note
We strongly recommend that you enable HTTPS in plant environments.
If the HTTPS protocol has been configured, HTTP cannot be used.

When configuring HTTP, observe the following instructions:

• If the UMC Web UI does not work, check that the value of the registry key
"HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\UserManagement\WebUI\Settings\secure" is
set to 0.
• The smartcard authentication does not work.

3.3.1 Configuring standalone UMC scenario

The following describes only the minimum steps required to configure a UMC standalone
scenario, i.e. a computer configured as a UMC ring server. Not all possible configuration options
are documented. Some additional configurations that can be applied to this scenario are listed
in the "Additional configurations" section.

Requirements
• UMC has been fully installed.
• IIS has been configured to work with the HTTPS protocol.
• When managing Active Directory users, the specified Windows user has the following
requirements:
– Active Directory access rights
– Write access to the UMC program data subfolder "\CONF" (e.g.
"C:\ProgramData\Siemens\UserManagement\CONF")
Alternative: Membership of the Windows group "UM Service Accounts"

UMC - Central User Management

30 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

Procedure
1. In the "Bin" or "Wow\bin" subdirectory, right-click UMCONF and select "Run as administrator".
2. Follow the displayed configuration steps in the interactive mode of UMCONF:
– Create a UMC domain by specifying a name with only alphanumeric characters.
– Create the root user "Administrator" by specifying a user name with only alphanumeric
characters and a password that complies with your organization's password policies.
– Link a Windows user who is either a member of the "UM Service Accounts" group or has
administrative rights for the "UMC Service" service by entering the user name .\ and the
corresponding password.
If the virtual account "NT SERVICE\UMC Service" is specified, no password entry is required.
– (Optional) To manage AD users within UMC, specify a Windows user by entering the
domain user name and password, as described in the requirements.
3. Right-click the "IdP_WebUI_configurator.bat" file under "C:\Program
Files\SIEMENS\UserManagement\BIN" when the default installation folder is selected, and
select "Run as administrator".

Result
The UMC Web UI and IdP are configured.

Additional configurations
• Configure Firefox for the integrated Windows authentication. This process is not required for
other browsers.
• Perform additional identity provider configuration.
• If Secure Application Data Support (SADS) is required, it must be enabled via the UMX utility
by running the following command: "umx -AP -setakp". For more information, see the UMX
reference.
• If you need SLRA support, you can find more information in the "Configuring Simatic Logon
Remote Authentication (SLRA) (Page 62)" section.
• If you need Desktop Single Sign-on, you can find more information in the "Configuring
Desktop Single Sign-on (DSSO) (Page 63)" section.

3.3.2 Configuring UMC scenario

Requirements
• If you want to manage AD users, the UMC ring server and the UMC servers must be connected
to the AD domain.
• Check if the connection to TCP/4002 is enabled on all computers (or disable the firewall for
"um.Ris.exe", the UM process that is responsible for communicating with UM computers).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 31
Installing and configuring UMC
3.3 Configuring UMC

• Check if the connection to TCP/4004 is enabled on all computers (or disable the firewall for
"um.ssrem.exe", the UM process that listens on this port).
• The firewall configuration on UMC servers and UMC ring servers must be configured to allow
inbound access for the following ports:
– Port for HTTP (80 by default)
– Port for HTTPS (443 by default)

The procedure in principle

1. Configure the computer that you have selected as primary master.
2. Configure the computer that you have selected as the secondary master (only in redundant
scenario).
3. (Optional) Configure one or more computers as UM servers by using the UMCONF program
to join the server to the UM domain ("serverType" parameter is equal to 0).
4. (Optional) Configure one or more computers as UMC agent by using the UMCONF program
to join the UMC agent to the UM domain.
5. Configure the web components.
6. (Optional) Install and configure UMC station clients.
7. (Optional) Configure SLRA support.
8. (Optional) Configure Desktop Single Sign-on.
9. (Optional) Assign an administrative role to a UM user so that this user can execute the
"umx.exe" command or log in to the UMC Web UI to manage UM users and groups.

3.3.2.1 Configuring the primary UMC ring server

After the installation of UMC, the configuration must be done via UMCONF. The steps are
described using UMCONF in interactive mode. UMCONF is provided with UMC and installed in
the subdirectory "\BIN" (64bit). If the import of an existing configuration is required, the import
command must be executed via UMCONF.

Requirements
• The complete UMC installation has been installed.
• Required only to manage AD users: The Windows user specified in optional step 2 to manage
AD users requires:
– Active Directory access rights
– Write access to the UMC folder "C:\ProgramData\Siemens\UserManagement\CONF" or
alternatively membership in the Windows group "UM Service Accounts".

UMC - Central User Management

32 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

Procedure
1. Right-click UMCONF in the "Bin" or "Wow\bin" subdirectory, for example, "C:\Program
Files\Siemens\UserManagement\Bin" and select "Run as administrator".
2. Follow the guided configuration in the interactive mode of UMCONF:
– Create a UM domain by specifying a name with only alphanumeric characters.
– Create a UM user management user with the UM role "Administrator" by specifying a user
name with only alphanumeric characters and a password that conforms to your
organization's password policies. You can find additional information under Password
strength (Page 162).
– Link a local user who is either a member of the "UM Service Accounts" group or has
administrative rights for the "UMC Service" service by entering the user name .\ and the
corresponding password.
– Optional: To manage AD users, specify a local user as described under requirements by
entering the domain user name and password.

Note
If Secure Application Data Support (SADS) is required, refer to the UMX reference (Page 247).
The user assigned to the "UMC Service" service may only be changed via UMCONF.

3.3.2.2 Configuring the secondary UMC ring server

Requirements
• You must have already created a UMC ring server.
• A complete UMC installation has been installed on the computer.

Procedure
To configure a secondary UMC ring server, proceed as follows:
1. Join the server using the UMCONF program.
2. If you have configured AD provisioning on the primary UMC ring server, you must also
configure it on the secondary UMC ring server.

Additional functions
Additional provisioning configurations can also be made.
To add the service layer to the allowlist, log in to the UMC Web UI with the UM role
"Administrator".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 33
Installing and configuring UMC
3.3 Configuring UMC

3.3.2.3 Configuring UMC web components

After installing UMC, if necessary, you can configure the web components as described below.

Requirements
• The computer is configured as a UMC ring server or UMC server.
• If the computer is not the primary UMC ring server, you must add the service layer to the
allowlist by logging in to the UMC Web UI with the user with UM role "Administrator" or
via UMCONF on the primary ring server.
• The firewall configuration on UMC servers and UMC ring servers must be configured to allow
inbound access either through the port used for HTTP (80 by default) or by the port used for
HTTPS (443 by default).
• If you use the HTTPS protocol, IIS must be configured to work with the HTTPS protocol.

Configuration types
• Via a script: The manual method can be used for HTTPS. The script automatically configures
the web components.
• Manual: The manual method can be used for HTTP or HTTPS. You can use the method to
structure your own custom configuration script.

Resetting the configuration of the web components

UMC provides the "REMOVE_IdP_WebUI_configurator.bat" script to reset the configuration of the
web components. The batch file is located in "C:\Program Files\SIEMENS\UserManagement\BIN"
if the default installation folder was selected.

Note

If you make a change to the IIS configuration after starting the configuration script
"IdP_WebUI_configurator.bat" or if you have configured UMC without this script, you must reset
the configuration of the web components and only then configure the system again.

Configuring UMC web components via a script

In order to configure all web components on the same UMC ring server/UMC server, UMC
provides the "IdP_WebUI_configurator.bat" script, which allows you to configure the
components to work with the HTTPS protocol and to configure integrated Windows
authentication (with the exception of Firefox configuration, which must be done manually).

UMC - Central User Management

34 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

The batch file is located in "C:\Program Files\SIEMENS\UserManagement\BIN" if the default

installation folder was selected. If IIS has been previously configured to work with the HTTPS
protocol, the script will configure the UMC Web UI accordingly.

Note
• If the user under which the script is executed is a local Windows user, retrieval of the Fully
Qualified Domain Name (FQDN) is not possible. As a result, the IdP's registry key is
configured with only the computer name and not the domain name.
• If you have configured a site in IIS with a name that is not "Default website", you must open
a command prompt as an administrator in the installation folder of the BAT file and specify
the name of the site as the first parameter: E.g. C:\Program
Files\Siemens\UserManagement\BIN>IdP_WebUI_configurator.bat "Your website name".
• If you want to specify a specific "reverseProxy" value that is different from the value
automatically retrieved in the script and you want to use it in the identity provider
configuration, you can specify it as the second parameter when starting the
"IdP_WebUI_configurator.bat" script: for example, C:\Program
Files\Siemens\UserManagement\BIN>IdP_WebUI_configurator.bat "Your website name"
"Your reverse proxy address".
• When using an NLB, specify the cluster name/address instead of the reverse proxy address as
the second parameter.
• By default, the identity provider process "node.exe" is monitored at port 8443. If you want to
change this default value, you can specify the desired port value as the third parameter when
starting the IdP_WebUI_configurator.bat script: E.g. C:\Program
Files\Siemens\UserManagement\BIN>IdP_WebUI_configurator.bat "Your website name"
"Your reverse proxy address" "Port number".
• If you want to specify a particular parameter while keeping the default values of the previous
parameters, you must pass an empty string for the parameters you do not want to adjust. For
example, if you only want to specify a certain port number without changing the IIS site
name and the reverse proxy address, you have to call the script
"IdP_WebUI_configurator.bat" in this way: C:\Program
Files\Siemens\UserManagement\BIN>IdP_WebUI_configurator.bat "" "" "Port number". The
empty quotes indicate an empty value for the parameters that are transferred to the script.

General recommendations
The web components can be configured in any UMC ring server and/or in any UMC server. To
ensure high availability and reliability of the IdP, we recommend that you install and configure
it on multiple computers and configure the high availability/reliability of the IdP.

Requirements
• IIS has been previously configured to work with the HTTPS protocol.
• The computer is configured as a UMC ring server or UMC server.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 35
Installing and configuring UMC
3.3 Configuring UMC

Procedure
1. On all servers on which you want to configure the web components, right-click the
"IdP_WebUI_configurator.bat" file, located at C:\Program
Files\SIEMENS\UserManagement\BIN when the default installation folder was selected, and
select "Run as administrator".
2. Configure your browser for the integrated Windows authentication (optional).
3. Configure the smartcard authentication (optional).
4. Perform additional identity provider configuration (optional).

Configuring integrated Windows authentication

You can use the following procedures to configure the integrated Windows authentication of the
identity provider (IdP) so that you can log in to the UMC Web UI with the current Windows
session. This requires the following procedure:
1. Enable Windows authentication in IIS.
2. Install the role service for Windows authentication.
If you want to use Firefox, you must also make several manual browser configurations.

Requirements
• The requirements for the identity provider (Page 25) are met.
• The computer is configured as a UMC ring server or UMC server.

Enabling Windows authentication in IIS

1. Open the IIS Manager.
2. In the tree topology on the left, select the "IPSimatic Logon" node.

UMC - Central User Management

36 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

3. Double-click "Authentication".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 37
Installing and configuring UMC
3.3 Configuring UMC

4. Make sure that the following authentication settings are set:

UMC - Central User Management

38 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

5. Right-click the "IPSimatic Logon" node and select "Add application" to add the WinAuthSite
application. The path is, for example, "C:\Program
Files\Siemens\UserManagement\web\ipsimatic-logon\WinAuthSite". Then, click "OK".
6. In the tree topology on the left, select the "WinAuthSite" node and set the following
authentication settings.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 39
Installing and configuring UMC
3.3 Configuring UMC

Installing the role service for Windows authentication

1. Open the Server Manager.
2. Select the "Server Roles" node in the tree topology on the left.
3. Install the role service for Windows authentication.

UMC - Central User Management

40 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

Configuring Firefox for integrated Windows authentication

With the procedure described below, you can configure Firefox to use the integrated Windows
authentication of the identity provider (IdP) so that you can log in to the UMC Web UI with the
current Windows session. The " <domain>" string can correspond to one of the two names:
• Computer name: If the computer on which IdP is installed does not belong to an AD domain,
e.g. "myMachine".
• Fully Qualified Domain Name (FQDN): If the machine on which IdP is installed belongs to an
AD domain.
The FQDN is composed as follows: <computerName>.<domainName>.extension, e.g.
"myMachine.siemens.com".

Requirements
The configurations of IIS for the integrated Windows authentication have been performed.

Procedure
1. In Firefox, call up the URL "about:config".
2. Click the "I'll be careful, I promise!" button.
3. In the "Search" dialog box, search for the "network.negotiate-auth.allow-non-fqdn"
preference.
4. Double-click the property to set the value to "true".
5. Close the window.

Managing the configuration of the identity provider (IdP)

The following configurations can be specified either locally or centrally using the function for
specifying the configuration in UMCONF.
If the IdP has been configured via a script, these configurations are optional. However, if it
has been configured manually, you need to specify some values in the local configuration file.
The identity provider uses three configurations:
• Local configuration file: Contains a set of data related to the IdP instance that must be
specified either manually or by running the "IdP_WebUI_configurator.bat" file. This file can
also be used to specify all computer-specific central configuration overrides.
• Default configuration file: Contains the default configuration for the IdP that is installed by
UMC and cannot be changed. These configurations are used when the configuration is not
specified in either the local or central configuration file.
• Central configuration file: Contains the set of configurations to be applied to multiple servers
and should be used to specify deviations from the default file. Most of the existing settings
can be overridden by the local configuration file if required.
Any local or central configuration change is automatically loaded by the identity provider
with a delay of less than 1 minute.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 41
Installing and configuring UMC
3.3 Configuring UMC

Note
Diagram explanations
• Some values exist only in the local configuration file.
• Some values of the central configurations cannot be overwritten by the local configuration
file.

Local configuration file

In the local configuration file, you can specify the settings that are to apply only to this particular
computer. The file is located in the WEB\umc-sso\config subfolder and is named
"configuration.json", for example: "C:\Program Files\Siemens\UserManagement\WEB\umc-
sso\config\configuration.json".
You can specify any of the attributes that are present in the default file in the local file. You
can also set override to "true" to use the locally specified configuration instead of the central
configuration.

Note
• The values of "clusters", "enableWhitelist", "reverseproxy", and "reverseproxyPort" cannot be
overridden by the local configuration if they are specified in the central configuration.
• To manually configure the IdP, you need to set the values of the fields: "UMCDllFolderPath",
"reverseProxy", and "idpListenerPort".
• For the changes made to the local configuration file to take effect, you must restart the UMC
service.

{
"private": {
"UMCDllFolderPath": "C:/Program Files/Siemens/UserManagement/
bin",
"useHttps": false,
"httpsServerKey": "",
"httpsServerCert": "",
"configurationInterval": 60000,
"idpListenerPort": 8443,
"logs": {
"winston": {
"maxFiles": "2",
"maxSize": "1000000",
"traceLevel": "error"
}
}

UMC - Central User Management

42 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

},
"reverseProxy": "https://IDPTEST",
"reverseProxyPort": "",
"override" : false
}

Field Description Value

UMCDllFolderPath The path of the user management instal‐ This value is transferred from the BAT file
lation, for example "C:/Program Files/ and only needs to be changed in case of
Siemens/UserManagement/bin" manual IdP configuration.
configurationInterval Specifies the poling interval for central The default value is 60000 ms. It must
configuration and the allowlisting. For not be changed.
internal use only.
idpListenerPort Specifies the port number of the IDP The default port number is 8443. To
node.js listener. change this option, pass the user-de‐
fined port number as the third parameter
to the "IdP_WebUI_configurator.bat" file.
reverseProxy The URL of the reverse proxy.
reverseProxyPort The port of the reverse proxy. Default value 443.
override Specifies whether the value of the local The default setting is "false". Possible val‐
configuration overwrites the central con‐ ues "true" or "false".
figuration.

The "logs" section is used to create a unique configuration point for the logging systems.
The "Winston" section provides the configuration for the "node.js" identity provider server

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 43
Installing and configuring UMC
3.3 Configuring UMC

protocol. Messages are logged in the "umc_sso_server.log" file. The corresponding properties
are described in the following table:

Field Description Value

maxFiles Maximum number of files generated for The default value is 2.
this log
maxSize Maximum size of files generated by the The value is specified in bytes. The de‐
log fault value is 1000000 bytes ≃ 1 Mbyte
traceLevel Minimum severity of messages to be re‐ The accepted value can be a string or an
corded by the log ID number:
{
error: 0,
warn: 1,
info: 2,
verbose: 3,
debug: 4,
silly: 5
}
The logging level is described on the
winston page (https://github.com/
winstonjs/winston#logging-levels//
XmlEditor.InternalXmlClipboard:bfe1d6
79-a57d-2715-4d9a-a4b1bee77724).
The default value is "error".

The following is an example of a configured local configuration file.

{
"private": {
"UMCDllFolderPath": "C:/Program Files/Siemens/UserManagement/
bin",
"useHttps": false,
"httpsServerKey": "",
"httpsServerCert": "",
"configurationInterval": 5000,
"idpListenerPort" : 8443,
"logs": {
"winston": {
"maxFiles": "2",
"maxSize": "1000000",
"traceLevel": "error"
}
}
},

UMC - Central User Management

44 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

"reverseProxy": "https://mymachine",
"reverseProxyPort": "",
"languages": {
"de-DE": {
"id": "de-DE",
"name": "Deutsch"
},
"en-US": {
"id": "en-US",
"name": "English US"
}
},
"authenticationOptions": {
"autoLogin": "",
"disableCredentialsLogin": false,
"enableFlexAuth": true,
"enableIWA": false,
"enablePKI": true
},
"override": true
}

Default configuration file

The default file contains the default configurations that are used when the configurations are not
specified in the central or local files. A copy of this file can be created using the UMCONF
command "getdefaultconfig".
{
"configdata": {
"authenticationOptions": {
"authenticationLevelCredentialsLogin": "strong",
"authenticationLevelWindowsLogin": "strong",
"autoLogin": "",
"disableCredentialsLogin": false,
"enable2FactorAuth": false,
"enableFlexAuth": false,
"enableIWA": true,

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 45
Installing and configuring UMC
3.3 Configuring UMC

"enablePKI": false
},
"clusters": 1,
"cookieFlags": {
"httpOnly": true,
"samesite": "none",
"secure": true,
"domain": ""
},
"cookiePath": "/",
"disclaimerContent": {
"de-DE": "Sie sind in eine geschützte Umgebung
eingetreten. Um die Umgebung zu verlassen, müssen Sie sich
abmelden. Das Schließen des Browsers ist nicht ausreichend, um
zu gewährleisten, dass Sie die Umgebung verlassen haben.\n<br/><br/
>\n<b>Sicherheitsinformationen</b>\n<br/>\nUm Anlagen, Systeme,
Computer und Netzwerke vor Internetbedrohungen zu schützen, ist
es nötig, ein holistisches Konzept für die industrielle Sicherheit
auf dem neuesten Stand zu implementieren und kontinuierlich
aufrechtzuerhalten. Produkte und Lösungen von Siemens stellen nur
ein Element eines solchen Konzepts dar. Weitere Informationen über
die industrielle Sicherheit finden Sie unter http://www.siemens.com/
industrialsecurity.",
"en-US": "You have entered a protected environment. To
exit, you must log out: closing the browser is not sufficient
to guarantee that you have exited the environment.\n<br/><br/>
\n <b>Security information</b> \n<br/> \nIn 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.
For more information about industrial security, please visit http://
www.siemens.com/industrialsecurity.",
"es-ES": "Ha entrado en un entorno protegido. Para
salir es necesario cerrar sesión, no es suficiente cerrar el
explorador para garantizar que se ha salido del entorno.\n<br/><br/
>\n<b>Información de Seguridad</b>\n<br/>\nPara proteger plantas,
sistemas, máquinas y redes contra ciberamenazas, es necesario
implementar -y mantener constantemente- un concepto de seguridad
industrial holística de última generación. Los productos y
soluciones Siemens constituyen solamente un elemento de dicho
concepto. Para obtener más información acerca de la seguridad
industrial, visite: http://www.siemens.com/industrialsecurity.",
"fr-FR": "Vous êtes dans un environnement protégé.
Pour sortir, vous devez vous déconnecter: la fermeture de

UMC - Central User Management

46 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

l’explorateur n’est pas suffisante pour garantir votre sortie

de cet environnement.\n<br/><br/>\n<b>Informations sur la sécurité</
b>\n<br/>\nPour protéger des plants, des systèmes, des machines
et des réseaux contre des menaces cyber, il est nécessaire
d’implémenter (et maintenir de manière permanente) une optimisation
globale du concept de sécurité industrielle. Les produits et
solutions Siemens représentent seulement un élément de ce concept.
Pour de plus amples informations sur la sécurité industrielle,
voir http://www.siemens.com/industrialsecurity.",
"it-IT": "Vi trovate in un ambiente protetto. Per
uscire è necessario disconnettersi: la chiusura del browser
non è sufficiente a garantire l’uscita dall’ambiente.\n<br/
><br/>\n<b>Informazioni sulla sicurezza</b>\n<br/>\nPer proteggere
impianti, sistemi, macchine e reti dalla minaccia cyber, è
necessario implementare - e mantenere continuativamente - un
concetto di sicurezza industriale olistico e all’avanguardia.
I prodotti e le soluzioni Siemens rappresentano soltanto un
elemento di tale concetto. Per maggiori informazioni sulla
sicurezza industriale, visitare il sito http://www.siemens.com/
industrialsecurity.",
"zh-CN": "您已经进入了一个受保护的环境。如要退出，您必须注销：关闭浏览器
不足以保证已退出环境。\n<br/><br/>\n<b>安全信息</b>\n<br/>\n 为了保护工厂、系
统、机器和网络免受网络威胁，有必要实施——并持续维护——一个全面、最先进的工业安全概念。
西门子产品和解决方案只是这种概念的一个要素。有关工业安全的更多信息，请访问 http://
www.siemens.com/industrialsecurity。"
},
"disclaimerEnabled": false,
"enableWhitelist": false,
"idpUI": "/umc-idp/idpauthsite",
"languages": {
"de-DE": {
"id": "de-DE",
"name": "Deutsch"
},
"en-US": {
"id": "en-US",
"name": "English US"
},
"es-ES": {
"id": "es-ES",
"name": "Español"
},

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 47
Installing and configuring UMC
3.3 Configuring UMC

"fr-FR": {
"id": "fr-FR",
"name": "Français"
},
"it-IT": {
"id": "it-IT",
"name": "Italiano"
},
"zh-CN": {
"id": "zh-CN",
"name": "中文"
}
},
"maxCachedSessionsPerUser": 100,
"reverseProxy": zero,
"reverseProxyPort": zero,
"sessionAge": 1800000,
"ssoService": "/umc-sso"
},
"label": "$default$",
"version": 0
}

Field Description Value

disclaimerContent Contains the text to be displayed for The text of the disclaimer for each lan‐
each language. guage. Consists of a two-letter language
code and a country code, for example
"de-DE": Example text, "en-US": Example.
disclaimerEnabled Allows the visualization of disclaimers If "true", the disclaimer is displayed, if
during the registration. "false" (default), it is not displayed.
enableWhitelist Enables the UMC allowlisting. If "true" (default) the allowlist is enabled,
if "false" it is disabled.
sessionAge Specifies the amount of time that elap‐ The default setting is 1800000 ms.
ses before the sessions expire.
reverseProxy The address of the reverse proxy. If this value is set in the central configu‐
ration, the local value is ignored even if
"override" is set to "true".

UMC - Central User Management

48 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

Field Description Value

reverseProxyPort The port of the reverse proxy. Default setting 443. If this value is set in
the central configuration, the local value
is ignored even if "override" is set to
"true".
Service The endpoint of the log for a one-time /umc-sso
login.
idpUI The address of the IdP UI. Set to default value "/ipsimatic-logon/
idpauthsite"
maxCachedSessionsPerUser The number of sessions logged in the Set to default value of 100. Value range
cache for each user. If the number of ses‐ of 10-1000.
sions in the cache exceeds the limit, the
oldest entry is removed.
cookiePath The path of the domain in which the Default value "/umc-sso".
cookie is valid. This value must be set in
the case of a reverse proxy.
clusters Determines how many node processes 1 min. and the maximum value should
in IdP must be started. reflect the total number of processor
cores.

Table 3-1 Authentication options

Field Description Value

authenticationLevelCredentialsLogin The security level of the authentication • weak
based on password authentication. • standard
• strong (default setting)
authenticationLevelWindowsLogin The security level of the Windows au‐ • weak
thentication. • standard
• strong (default setting)
enableIWA Enables the Windows authentication in "true" or "false" (default).
the IdP.
enablePKI Enables the smartcard authentication. "true" or "false" (default).
enableFlexAuth Enables flexible authentication. "true" or "false" (default).
enable2FactorAuth Enables two-factor authentication. "true" or "false" (default).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 49
Installing and configuring UMC
3.3 Configuring UMC

Field Description Value

disableCredentialsLogin When this setting is set to "true", the log‐ "true" or "false" (default).
in information fields on the IdP page are
hidden so that only integrated authenti‐
cation, such as Windows or smartcard
authentication, can be used.
autoLogin Activates autologin. • Windows authentication: "iwa"
• Smartcard authentication: "pki"
• Desktop <pluginname>
• Web <pluginname>
• Flexible authentication <flex‐
auth:<pluginname>
Multiple methods can be used for au‐
thentication by separating each method
with "||".
"<pluginname>||<pluginname>"

Central configuration file

The central configuration file contains the configurations that can be applied to multiple
computers. All settings made in the central file are used by all computers in the scenario, unless
"override" is set to "true" in the local file.
You can use a UMCONF command to get the current central configuration and set a central
configuration. The values that can be set in the central configuration are listed in the
description of the fields of the standard configuration file.
A centralized configuration is done via UMCONF or when certain configurations are made via
the UMC Web UI, such as configuring a disclaimer or authentication options.
The following JSON file is an example of a configuration with some configurations that can be
set centrally.
{
"conf": [
{
"configdata": {
"sessionAge": 600000,
"reverseProxy": "https://IDPTEST3",
"reverseProxyPort": "",
"ssoService": "/umc-sso",
"idpUI": "/umc-idp/idpauthsite",
"cookiePath": "/",
"clusters": 1,
"cookieFlags": {
"httpOnly": true,

UMC - Central User Management

50 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

"secure": true,
"domain" : "umdom1.net"
},
"authenticationOptions":{
"enableIWA":true,
"enablePKI":false,
"enableFlexAuth":true,
"enable2FactorAuth":false,
"disableCredentialsLogin":false,
"autoLogin":""
}
},
"label": "$default$",
"version": 2
}
]
}

Configuring smartcard authentication (PKI)

The following configuration steps must be performed to enable authentication via smartcard.
The operations can be performed in any order.

Workflow
• Configure the infrastructure for the smartcard authentication.
• Configure the smartcard web application (not required if UMC is configured via a script).
• Enable the login via smartcard authentication either locally or centrally.
• Set the account policies for smartcard authentication.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 51
Installing and configuring UMC
3.3 Configuring UMC

Configuring infrastructure for the smartcard authentication

On the server side

The smartcard authentication can only be configured on computers on which the identity
provider has been configured. IIS certificate authentication must be configured correctly for it to
work.

Note
The following recommendations for the IIS configuration must be considered:
• A check of the blacklist must be supported.
• The certificate for the "Client Authentication Issuer" in the certificate manager must be
installed.
• The store of the trusted root certificate authorities may only contain self-signed certificates.
• The use of the "Client Authentication Issuer" on port 443 or on the IdP port must be enabled.

On the client side

The following steps are required to configure client-side smartcard authentication:
• Smartcard drivers must be installed on each client computer.
• If you use Firefox, the additional configuration for security devices must be carried out.

Configuring smartcard web application

This procedure is not required if you used the "IdP_WebUI_configurator.bat" script to configure
UMC.

Procedure
1. Open the IIS Manager.
2. Right-click the "IPSimatic Logon" node and select "Add application" to add the "PkiAuthSite"
application. For example, the path is C:\Program
Files\Siemens\UserManagement\web\ipsimatic-logon\PkiAuthSite. Then, click "OK".

UMC - Central User Management

52 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

3. Select the "PkiAuthSite" node in the tree topology on the left side.

4. Double-click "SSL settings" and set the values as follows.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 53
Installing and configuring UMC
3.3 Configuring UMC

5. To check whether the smartcard authentication application has been configured correctly,
open a browser instance.
6. Insert a smartcard into the smartcard reader.
7. Open the page at the following address: https://<address>/umc-idp/pkiauthsite/info.aspx.
A JSON file opens with smartcard information.
If the JSON file is not displayed correctly, we recommend that you enable detailed error
messages in IIS and carefully check the configuration of the smartcard authentication
infrastructure.

Setting account policies for smartcard authentication

The smartcard authentication mechanism is based on a comparison between the user data
stored on the smartcard and the data stored in UMC.

Procedure
1. To configure data synchronization, go to the "Account policies" page of the UMC Web UI with
the appropriate access rights.
2. Define the field to be retrieved from the smartcard to identify the user in UMC.
3. Select one of the following authentication options:
– Simple authentication (no alias): In this case the selected field, CN (common name),
subject, alternative subject, is compared with the UMC user name. If these match, the
user is authenticated.
– Alias authentication: In this case, you must define an alias for a user in the user details
dialog. The value stored in the field is compared with the UMC alias. If these match, the
user is authenticated.
For more information, see Managing account policies (Page 123).

UMC - Central User Management

54 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

Enabling HTTPS in an HTTP UMC scenario

Depending on the configurations you have made on the UMC web components, you must
perform one of the following alternative procedures:
• Configure UMC web components using the "IdP_WebUI_configurator.bat" script.
• Configure UMC web Components manually or customize them.

Requirements
• A UMC web component is installed and configured on your computer
• IIS is not configured for HTTPS

Configuring UMC web components via a script (no customization)

1. Configure IIS for the HTTPS protocol.
2. Start the "REMOVE_IdP_WebUI_configurator.bat" script. The batch file is located in
"C:\Program Files\SIEMENS\UserManagement\BIN" if the default installation folder was
selected. Note that the script only works on a 64-bit computer.
3. Start the "IdP_WebUI_configurator.bat" configuration script to configure UMC web
components.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 55
Installing and configuring UMC
3.3 Configuring UMC

Configuring UMC web components manually

1. Configure IIS for the HTTPS protocol.
2. If you have made changes to the IIS configuration after starting the
"IdP_WebUI_configurator.bat" configuration script or have not configured UMC with this
script, you must enable the HTTP protocol manually.

Configuring two-factor authentication with a temporary one-time password

The following configuration steps must be performed to enable two-factor authentication via
TOTP (Time-based One-Time Password). This can be used to increase the level of security of an
authentication method that would otherwise be "standard" or "weak". You can find more
information on the website of RFC (https://www.rfc-editor.org/rfc/rfc6238).
To use two-factor authentication via TOTP, a time synchronization (Page 23) of the UMC
computers is required.
The two-factor authentication of UMC consists of the first authentication method using
Windows or password authentication and the second method using a token (TOTP) with
encryption by the user's secret key to increase the security level of the user to "strong".
Two-factor authentication allows the user to log in with restricted access after it has been
enabled, allowing the user to generate the first secret key.

See also
Enabling two-factor authentication (Page 56)
Using two-factor authentication (Page 58)

Enabling two-factor authentication

The two-factor authentication via TOTP can be enabled via the UMC Web UI or UMX
and UMCONF.

Workflow
• Enable SADS in the account policies via the UMC Web UI or UMX.
• Enable the two-factor authentication for the user in their account policies via the UMC Web
UI or enable the encryption for the user via UMX.

Enabling SADS via the UMC Web UI

1. Log in to the UMC Web UI with a user who has the UM role "UMC Admin".
2. Open the "Account policies" menu.

UMC - Central User Management

56 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

3. On the "Advanced" tab, select the "Enable secure application data support for users and
groups" checkbox.
At application level, SADS can be enabled via UMX or the UMC Web UI by changing an
account policy.
See the UMCONF reference for more details.
4. Click "Save".

Enabling two-factor authentication as authentication method

1. Log in to the UMC Web UI with a user who has the UM role "Administrator" or "UMC Admin".
2. Open the "IDP configuration" menu.
3. Switch to the "Authentication options" tab.
4. In the "Integrated authentication methods" area, make the following settings:
– For "Password authentication", set the "Enable" option and select the value "weak" or
"standard" under "Authentication level".
– For "Windows authentication", set the "Enable" option and select the value "weak" or
"standard" under "Authentication level".
5. Select the "Enable two-factor authentication" checkbox.

6. Click "Save all changes".

Enabling two-factor authentication for a user

1. On the "Users" page, select a row and click "Details" in the upper left corner of the grid.
The "Account policies" tab is displayed.
2. Select the "Enable 2FA" checkbox.
3. Click "Save".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 57
Installing and configuring UMC
3.3 Configuring UMC

Using two-factor authentication

Two-factor authentication via TOTP makes login more secure. When you log in the first time, you
gain access in order to retrieve the secret key. If two-factor authentication has been enabled, you
are prompted at every subsequent login to use a token.

Workflow
1. Log in with an authentication method that is either "weak" or "standard".
2. From the second login, you will be asked for a TOTP (temporary one-time password).
3. Generate a TOTP (temporary one-time password) with the previously retrieved secret key.
4. Enter the password and click "Login".

Generating and resetting secret keys

Call up the UMC Web UI and select the "User profile" option from the menu at the top right of the
UMC home page or click the "User profile" button on the home page.
The "User profile" page is displayed.

UMC - Central User Management

58 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

Requirements
• SADS has been enabled in the account policies via the UMC Web UI (see Managing account
policies (Page 123)) or UMX.
• The two-factor authentication has been enabled as the authentication method via the UMC
Web UI (see Configuring authentication options (Page 131)) or the central configuration
management UMCONF.
• The two-factor authentication has been enabled for the user in his account policies via the
UMC Web UI (see Managing account policies (Page 123)) or the encryption has been
activated for the user via UMX.

Procedure
1. Click the "Manage 2FA" tab.
2. Click "Display QR code".
3. If required, click "Show secret key" or "Reset secret key".

Configuring UMC web requirements via a script for GUM and DSSO
UMC provides special batch files for the configuration of the UMC web requirements for GUM
and DSSO on a UMC runtime server.
These batch files are located in "C:\Program Files\SIEMENS\UserManagement\BIN" if the
default installation folder was selected.
To configure the UMC web requirements for GUM and DSSO on a ring or a server, configure
the UMC web components as described in "Configuring UMC web components via a script
(Page 55)".

Requirements for GUM

• The computer is configured as a UMC runtime server.
• IIS has been previously configured to work with the HTTPS protocol.

Requirements for DSSO

• The computer is configured as a UMC runtime server.
• IIS has been previously configured to work with the HTTPS protocol.
• The requirements for the identity provider (Page 25) are met.

Requirements for GUM

To configure the UMC web requirements for GUM on a UMC runtime server, UMC provides the
script "gum_iis.bat".
This batch file is located in "C:\Program Files\SIEMENS\UserManagement\BIN" if the default
installation folder was selected.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 59
Installing and configuring UMC
3.3 Configuring UMC

The first parameter of the command can be "enable" or "disable":

• Execute the "gum_iis.bat enable" command to configure the UMC web requirements for GUM
for the "Default website".
• Execute the "gum_iis.bat disable" command to clean up the UMC web requirements for GUM
for the "Default website".
If you want to make the changes for a website that is not the "Default website", you must
open a command prompt as administrator in the installation folder of the BAT file and specify
the name of the website as the second parameter.

Example
C:\Program Files\Siemens\UserManagement\BIN>gum_iis.bat" enable "Your website name"

Script for DSSO

To configure the UMC web requirements for DSSO on a UMC runtime server, UMC provides the
script "dsso_prereq.bat".
This batch file is located in "C:\Program Files\SIEMENS\UserManagement\BIN" if the default
installation folder was selected.
The first parameter of the command can be "enable" or "disable": dsso_prereq.bat enable to
configure the UMC web requirements for DSSO for the "Default website" or dsso_prereq.bat
disable to clean up the UMC Web requirements for DSSO for the "Default website".
If you want to make the changes for a website that is not the "Default website", you must
open a command prompt as administrator in the installation folder of the BAT file and specify
the name of the website as the second parameter.

Example
C:\Program Files\Siemens\UserManagement\BIN>dsso_prereq enable "Your website name"
If you want to specify a different "reverseProxy" value than the value retrieved by the script
and use it in the configuration, you can specify this value as the third parameter when
starting the "dsso_prereq.bat" script.

Example
C:\Program Files\Siemens\UserManagement\BIN>dsso_prereq.bat enable "Your website
name" "Your reverse proxy address"
By default, the identity provider process "node.exe" is monitored at port 8443. If you want
to change this default value, you can specify the desired port value as the fourth parameter
when starting the "dsso_prereq.bat" script.

Example
C:\Program Files\Siemens\UserManagement\BIN>dsso_prereq.bat "Your website name" "Your
reverse proxy address" "Port number"
If you want to specify a particular parameter while keeping the default values of the previous
parameters, you must pass an empty string for the parameters you do not want to adjust.

Example
C:\Program Files\Siemens\UserManagement\BIN>dsso_prereq.bat enable "" "" "Port number"

UMC - Central User Management

60 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

The empty quotes indicate an empty value for the parameters that are transferred to the
script.

Workflow
On all UMC runtime servers on which you want to configure the GUM, execute the following
command as an administrator:
gum_iis.bat enable
To remove the previous GUM settings, execute the following command as an administrator:
gum_iis.bat disable
On all UMC runtime servers on which you want to configure the DSSO, execute the following
command as an administrator:
dsso_prereq.bat enable
To remove the previous DSSO settings, execute the following command as an administrator:
dsso_prereq.bat disable

3.3.2.4 Configuring the UMC station client

Note
No checks are currently performed at the installation level of the UMC station client. An
overinstallation of the UMC station client leads to a serious malfunction in the system. In
particular, the UMC station client must not be installed on a computer on which UMC has already
been fully installed.

The UMC station client can be configured via a script.

Requirements
• The logged-in Windows user must have administrator rights.
• A complete installation of UMC or the UMC station client has been performed on your
computer. During the installation, you simply need to proceed with the wizard.
• The UMC Web UI must be properly configured for the UMC system in HTTPS (see
AUTOHOTSPOT). HTTPS is mandatory, therefore a valid SSL certificate must have been
acquired from a certificate authority or a self-signed SSL certificate must have been created.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 61
Installing and configuring UMC
3.3 Configuring UMC

Configuration of UMC station client via a script

1. Start the "regx.ps1" script, which is located in the \BIN subdirectory of the 32-bit installation
folder.
2. The script requires the following parameters:
– UMC server name (only one ring master)
– User (who has the UM function right "UM_REGCLIENT")
– Password
3. The script also supports the following optional parameters:
– workstationAlias: Alias that is used instead of the host name in the registration phase. The
alias must not contain any special characters.
– force: Forces the registration for an alias that is already registered
– update: Update the registration for an already registered customer

Result
The system registers the computer as a UMC station client, which makes a claim that contains
certified login station data.

3.3.2.5 Configuring Simatic Logon Remote Authentication (SLRA)

UMC offers support for Simatic Logon Remote Authentication (SLRA) for logging on to Simatic.

Requirement
• The computer is configured as a UMC ring server or UMC server

Procedure
Use the UMCONF utility. For more details, see the UMCONF reference (Page 188).

Note
Certificates
If TLS is needed, create the certificates and save them in the default folder for "CERT/SLRAUTH"
certificates in "C:\ProgramData\Siemens\UserManagement".
The default folder for "CERT/SLRAUTH" certificates inherits the access rights of the parent "CERT"
folder. The authorizations for the folder may have to be changed.

UMC - Central User Management

62 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.3 Configuring UMC

3.3.2.6 Configuring Desktop Single Sign-on (DSSO)

Requirements
• The computer is configured as a UMC ring server, UMC server or UMC runtime server.
• The requirements for the identity provider (Page 25) are met.
• UMC web components are configured with HTTPS on the computer if it is a UMC ring server
or UMC server. The DSSO web settings have been enabled in the case of a UMC runtime
server, as described in "Configuring UMC web requirements via a script for GUM and DSSO
(Page 59)".

Procedure
To enable DSSO, use the UMCONF utility. For more details, see the UMCONF reference
(Page 188).

3.3.2.7 Configuring Global User Management (GUM)

Requirements
• The computer is configured as a UMC ring server, UMC server or UMC runtime server.
• UMC web components are configured with HTTPS on the computer if it is a UMC ring server
or UMC server. The GUM web settings have been enabled in the case of a UMC runtime server,
as described in "Configuring UMC web requirements via a Script for GUM and DSSO
(Page 59)".

Procedure
To configure the GUM server list, use the UMCONF utility. For more information, see
"Commands for managing the GUM server list (Page 189)".

Utility for GUM fingerprint

To retrieve the GUM fingerprint, UMC provides a special Powershell file, which is located in
"C:\Program Files\SIEMENS\UserManagement\BIN" if the default installation folder was selected.
The GUM fingerprint is described in the "Creating a GUM list entry" section of the manual.
This script returns the fingerprint of the certificate that is used for https binding on the local
computer. If there is only one https binding in the IIS configuration, the script can be called
without specifying IP address and port parameters. If you have multiple https bindings, you
must specify the IP address and TCP port of the binding used for the GUM protocol in order to
retrieve the correct fingerprint.

Syntax
get_gum_fingerprint.ps1 [-ipaddress ipaddress] [-port tcport]

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 63
Installing and configuring UMC
3.3 Configuring UMC

Parameters
• ipaddress is the IP address of the IIS binding. It is 0.0.0.0 if the "All unassigned" option is
set under "Edit site" in the IIS Manager.
• tcpport is the TCP port of the IIS binding. The default TCP port for https is 443.

UMC - Central User Management

64 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.4 Configuring the identity provider

3.4 Configuring the identity provider

The high availability and reliability of the identity provider (IdP) is supported by NLB technology
(Network Load Balancing). The Network Load Balancing is a clustering technology that improves
the scalability and availability of TCP/IP based services such as web applications (e.g. UMC
identity providers). To scale performance, the Network Load Balancing (NLB) distributes the
inbound IP traffic to multiple web servers by using a virtual IP address and a reverse proxy, which
must be specified in the central UMC configuration, for the entire web server group and redirects
client requests to the servers in the group. Each server is identified by a network address that
identifies the entire group and its own network address. It also ensures high availability by
detecting host failures and automatically redistributing data traffic to reachable hosts.
For UMC-specific information about configuring Network Load Balancing (NLB), see the
following sections:
• High availability / reliability general issues (Page 65)
• NLB and health state integration (Page 67)

3.4.1 High availability / reliability general issues

• The degree of availability/reliability of the system depends on many factors, such as IT
infrastructure, redundancy of the UMC architecture and the selected NLB service.
• The decisions related to the aforementioned factors have a strong impact on the system
security. The triad of security quality features is ensured as follows:
– Integrity, i.e. the certainty that the information is trustworthy and correct, is ensured by
our system;
– Confidentiality, i.e. a set of rules restricting access to information, is ensured by third-
party software that manages redundancy, e.g. Network Load Balancing (NLB);
– Availability, i.e. reliable access to the system by authorized persons, is ensured by third-
party software that manages redundancy, e.g. Network Load Balancing (NLB).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 65
Installing and configuring UMC
3.4 Configuring the identity provider

• If you want the integrated Windows authentication mechanism to work properly without
prompting for user credentials, you must use Kerberos to authenticate to IIS. Kerberos
requires a special configuration in an NLB scenario. For more details, see the technical
documentation of Microsoft (see e.g. http://blogs.msdn.com/b/vivekkum/archive/
2008/06/15/step-by-step-kerberos-in-nlb-with-shared-content.aspx).
• If you configure a reverse proxy to use multiple web servers, you need to increase the query
string length value on all web servers via the IIS Manager to the values shown in the following
screenshot.

3.4.2 Health state service

UMC Health State is an HTTP/HTTPS service that provides information on the health state of the
authentication via UMC Identity Provider. The protocol depends on IIS configuration.
The value of the health state is contained in the field status of the HTTP response header:
• status = 200, the authentication can be performed successfully;
• status = 404, the authentication cannot be performed.

UMC - Central User Management

66 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.4 Configuring the identity provider

The health state information is derived from the one provided by the Health Check Service
described in UMC Release Notes.

Example URL
https://<host_name>/umc-sso/GetHealthState

3.4.3 NLB and health state integration

UMC health state service can be used in a high availability/reliability scenario based on NLB
technology to start/stop the use of UMC machines running the Identity Provider according to the
result provided by the health state. We here provide an example script developed in PowerShell
that queries the status of a node and stops or starts it according to UMC status using Microsoft
Windows Server NLB powershell commands. The script can be scheduled to run periodically via
Windows task scheduler.

PowerShell Script Example

Note
The sample code is provided for illustrative purposes only. It has not been thoroughly tested
under all conditions. Therefore, we cannot guarantee or imply its reliability, serviceability, or
function.

In the example two machines VM-UMC-N1 and VM-UMC-N2 are configured in NLB and their
status is checked via the PowerShell function CheckNodeHS. According to the status, the
node is stopped or started.

CheckNodeHS
Function CheckNodeHS([string]$nodeToCheck)
{
$url="https://"+$nodeToCheck+"/umc.idp/GetHealthState"
$r = [System.Net.WebRequest]::Create($url)

#Ignore certificate exception

[System.Net.ServicePointManager]::ServerCertificateValidationCall
back = {$true}
try
{
$resp = $r.GetResponse()
}
catch [Net.WebException]

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 67
Installing and configuring UMC
3.4 Configuring the identity provider

{
#404 is handled with an exception
}
if($resp.StatusCode -match "OK")
{
#200 returned
Write-Host "Node "+$nodeToCheck+ " OK"
Start-NlbClusterNode $nodeToCheck
}
else
{
#any other value than 200
Write-Host "Node "+$nodeToCheck+ " NOT OK"
Stop-NlbClusterNode $nodeToCheck
}
}

Script
#MAIN
cls
Import-Module NetworkLoadBalancingClusters
$node1="VM-UMC-N1"
$node2="VM-UMC-N2"
$nodeStatus = Get-NlbClusterNode -hostname "VM-UMC-N1"
$status1 = $nodeStatus[0].State.ToString()
$status2 = $nodeStatus[1].State.ToString()
if ($status1 -match "converged" -and $status2 -match "converged")
{
Write-Host "NLB status is good"
}
else
{
Write-Host "NLB status is NOT good"
Write-Host "Node 1: status is" $status1
Write-Host "Node 2: status is" $status2

UMC - Central User Management

68 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.4 Configuring the identity provider

}
CheckNodeHS($node1)
CheckNodeHS($node2)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 69
Installing and configuring UMC
3.5 Updating UMC

3.5 Updating UMC

3.5.1 General Recommendations

On this page you will find a set of notes that must be observed for a correct update of UMC.

Before you start

• To check the computer role, you can use the UMCONF "Show Status" command. See the
UMCONF reference for more details.
• During the update process, no UMC commands can be executed that are not part of the
process.

Version-specific notes
This section contains a list of notes that apply only to the upgrade of certain UMC versions.
• Update from 1.0: If you have installed and configured UMC 1.0, you must first upgrade to
UMC 1.1 (see UMC 1.1 Release Notes) and then update the system.
• Update from 1.1: If you have installed UMC 1.1 in an HTTP scenario, you must change the
scenario from HTTP to HTTPS after the update.
• Update from versions prior to 1.6: In mixed-version scenarios, problems can occur if a user
name longer than 30 characters is used. We strongly recommend updating the installations
to the latest UMC version.
• Update from versions prior to 1.9.1: Starting with version 1.9.1, the password expiration
value in the global account policy cannot exceed 1827 days. If the value is greater than 1827,
you must reset the value after the update.
• Update from versions prior to 2.0: Since significant changes would be made to the IdP, you
must make all the settings that were made in the webconfig again after updating your
installation, see Migrating IdP configurations.
• When versions prior to 2.0 are updated on UMC servers and the secondary UMC ring server,
the configuration script of the web component cannot update the allowlist. UMC servers and
the secondary UMC ring server must be added to the allowlist with UMCONF on the primary
UMC ring server.
• When versions prior to 2.0 are updated, the "Application Request Routing" package must be
downloaded and installed.
For IIS 8 and higher: Download (https://www.microsoft.com/en-US/download/details.aspx?
id=47333)

UMC - Central User Management

70 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.5 Updating UMC

Long-term scenarios with mixed versions

The following notes refer to long-term scenarios with mixed versions, i.e. scenarios in which the
installed UMC version is not identical on all computers in the scenario:
• As of UMC 1.9, we support long-term mixed decentralized scenarios. For scenarios with a
version earlier than 1.9, all UMC installations must be updated to at least UMC 1.9.
• A long-term mixture of versions is not supported on UMC ring servers, therefore the version
of UMC installed on UMC ring servers must be aligned as quickly as possible.

3.5.1.1 Migrating IdP configurations

When migrating from versions prior to UMC 2.0, you must make all the settings that were made
in the webconfig again after updating your installation, as significant changes have been made
to the IdP.
The following configurations correspond to the configurations that exist in the new IdP.

Functionality Old web configuration New IdP JSON file

Enable the anti-forgery token UseAntiForgeryToken not applicable
Enable the use of allowlisting EnableWhitelistMembershipService Enabled by default
See also Managing the configuration of
the identity provider (IdP) (Page 41)
Enable the use of paths to cookies ClaimIssuerAuthority not applicable, is now always activated.
Enable the identity provider log LogFileName not applicable, is now always enabled
and is stored in the um-sso log, which
can be found, for example, under C:\Pro‐
gramData\Siemens\UserManage‐
ment\Log
Enable the automatic login AutoLoginMode See also Managing the configuration of
the identity provider (IdP) (Page 41)
Enable login via smartcard authentica‐ EnablePKI Disabled by default
tion See also Managing the configuration of
the identity provider (IdP) (Page 41)
Enable login via cookie adapter or cus‐ EnableFlexAuth Disabled by default
tom plug-in See also Managing the configuration of
the identity provider (IdP) (Page 41)
Disable the use of the login station in EnableLogonStation not applicable, is now always activated.
claims
Disable the display of the security infor‐ UseDisclaimerMessage not applicable
mation
Disable and hide the link for the Win‐ EnableIWA Enabled by default
dows authentication See also Managing the configuration of
the identity provider (IdP) (Page 41)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 71
Installing and configuring UMC
3.5 Updating UMC

3.5.2 Updating the secondary UMC ring server

General recommendations
• During the update process, only the primary UMC ring server is available, which means no
system redundancy support is available for a minimum time period.
• Session losses may occur during the update.
• The primary UMC ring server and the secondary UMC ring server do not support a long-term
mixture of versions, therefore installations must be aligned as quickly as possible.

Procedure
1. If Network Load Balancing (NLB) is configured, remove the secondary UMC ring server from
the NLB cluster.
2. If UMC web components have been configured on the computer, run the file
"Remove_IdP_WebUI_configuration.bat".
3. Close all applications that are running.
4. Start the installation program and select the option to update the system. If you are prompted
to restart the system during installation, restart it. When the system restarts, the installation
program starts automatically.
5. Execute the command "umconf -U" to update the system. For more details, see the UMCONF
reference.
6. If UMC web components have been configured on the computer:
– Run the file "IdP_WebUI_configurator.bat" or configure the IdP manually.
– Manually adapt the settings in the identity provider webconfig on the .json configuration
file.
7. If Network Load Balancing (NLB) has been configured:
– Reconnect the computer to the NLB cluster;
– remove the primary UMC ring server and all other UMC servers (if any) from the NLB
cluster.
8. If an update to version 2.7 SP1 is being performed, execute the command to add the correct
dependency to the "UP Service" service:
sc config "up service" depend="UMC service"

Note
If you use the UMC Web UI, clear the browser cache on all computers that access the UMC Web
UI.

UMC - Central User Management

72 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.5 Updating UMC

3.5.3 Updating the primary UMC ring server

General recommendations
• During the update process, only the secondary UMC ring server is available, which means no
system redundancy support is available and no UMC database changes can be made for a
minimum time period.
• Session losses may occur during the update.
• The primary UMC ring server and the secondary UMC ring server do not support a long-term
mixture of versions, therefore installations must be aligned as quickly as possible.

Procedure
1. If UMC web components have been configured on the computer, run the file
"Remove_IdP_WebUI_configuration.bat".
2. Close all applications that are running.
3. Start the installation program and select the option to update the system. The system may
prompt you to restart before or after updating UMC. In this case, restart the system. If the
restart is performed prior to the update, the installation program starts automatically when
the system is restarted.
4. Execute the command "umconf -U" to update the system. For more details, see the UMCONF
reference.
5. If UMC 1.1 is installed in a standalone scenario with HTTP, and HTTPS is to be enabled when
updating to UMC 1.4, this additional procedure is required.
6. If UMC web components have been configured on the computer:
– Run the file "IdP_WebUI_configurator.bat" or configure the IdP manually.
– Manually adapt the settings in the identity provider webconfig on the .json configuration
file.
7. If Network Load Balancing (NLB) has been configured, reconnect the computer to the NLB
cluster.
8. If an update to version 2.7 SP1 is being performed, execute the command to add the correct
dependency to the "UP Service" service:
sc config "up service" depend="UMC service"

Note
If you use the UMC Web UI, clear the browser cache on all computers that access the UMC Web
UI.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 73
Installing and configuring UMC
3.5 Updating UMC

3.5.4 Restarting the secondary UMC ring server

If the validity of the certificates is already more than two years prior to the expiration date, a
restart of the secondary UMC ring server is required after updating the primary UMC ring server
in order to perform the automatic certificate renewal in the correct order.
For more details, see "Performing the automatic certificates renewal (Page 91)".

3.5.5 Updating a UMC server

Procedure
1. If UMC web components have been configured on the computer, stop the application pools
of the UMC applications in IIS Manager and execute the
"Remove_IdP_WebUI_configuration.bat" file.
2. Close all applications that are running.
3. Start the installation program and select the option to update the system. If you are prompted
to restart the system during installation, restart it. When the system restarts, the installation
program starts automatically.
4. Execute the command "umconf -U" to update the system. For more details, see the UMCONF
reference.
5. If UMC web components have been configured on the computer:
– Run the file "IdP_WebUI_configurator.bat" or configure the IdP manually.
– Manually adapt the settings in the identity provider webconfig on the .json configuration
file.
6. If the UMC server was connected to the NLB cluster, reconnect the computer to the cluster.
7. If an update to version 2.7 SP1 is being performed, execute the command to add the correct
dependency to the "UP Service" service:
sc config "up service" depend="UMC service"

Note
Session losses may occur during the update.

UMC - Central User Management

74 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.5 Updating UMC

3.5.6 Updating a UMC agent

Procedure
1. Close all applications that are running.
2. Start the installation program and select the option to update the system. If you are prompted
to restart the system during installation, restart it. When the system restarts, the installation
program starts automatically.
3. Execute the command "umconf -U" to update the system.
For more details, see the UMCONF reference.

3.5.7 Updating the UMC station client

Procedure
1. Close all applications that are running.
2. Start the installation program and select the option to update the system.
If you are prompted to restart the system during installation, restart it. When the system
restarts, the installation program starts automatically.

Result
The computer is automatically registered, and no further steps are required.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 75
Installing and configuring UMC
3.6 Deleting UMC configuration

3.6 Deleting UMC configuration

When you uninstall UMC, the configuration of the UMC web components as well as the data of
the UMC database and the entries of the registry are not deleted. This data remains on your
computer.
The following procedure describes how you can completely delete the UMC configuration.
The procedure must be performed on all computers (UMC ring server, UMC server, UMC
agents). It is recommended that you first perform the procedure described on the UMC
agents. You can then uninstall UMC via the Control Panel.

Procedure
1. To remove the configuration of the UMC web components, run the
"REMOVE_IdP_WebUI_configurator.bat" script.
You can find the script in "C:\Program Files\SIEMENS\UserManagement\BIN" if you have
selected the default installation folder.
2. To remove the data of the UMC database and the entries of the registry, execute the umconf
-D -f command.

Result
The configuration of the UMC web components as well as the data of the UMC database and the
entries of the registry are deleted.
For more information, see the UMCONF reference (Page 178).

UMC - Central User Management

76 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.7 Uninstalling UMC station client software

3.7 Uninstalling UMC station client software

The UMC station client software can be uninstalled via the Control Panel.

Procedure
1. Open the Control Panel.
2. Click on the "Programs and Features" item in the Control Panel.
3. In the "Uninstall or change program" dialog, select the UMC station client software and click
the "Uninstall" button.
A confirmation prompt appears.
4. Confirm the confirmation prompt by clicking "Yes".
The uninstall program starts.
5. Select the installation language and click "Next".
6. Select UMC to uninstall and click "Next".
7. Click "Uninstall".
8. Click on "Exit" to close the setup program.

Result
The UMC station client software is uninstalled from your computer.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 77
Installing and configuring UMC
3.8 Troubleshooting

3.8 Troubleshooting

General

Problem definition Solution

Authentication not possible due to unexpected problem. "um‐ Give the user executing the command access to the CONF
tracer gpclib" shows an attempt to use pipes to open a con‐ directory of UMC (e.g. auth. users).
nection to the local computer.
IdP displays a compilation error and issues an error message IIS_IUSRS does not have access to the Windows folder TEMP.
when an attempt is made to access a temporary folder (Win‐
dows Temp or temporary asp.net files)
Call of the UMC Web UI not possible with error message "Un‐ umc_pool application pool has been configured to run in 32-
able to establish connection to server" bit mode. Set the "Enable 32 bit" flag to FALSE in the umc_pool
configuration.
The UMC Web UI displays the following error when logging IIS functions are missing: Basic authentication, Windows au‐
in: An error occurred during communication with the server. thentication, asp.net 4.5 has not been installed.
The login pages of the identity provider show an error related IIS functions are missing: Basic authentication, Windows au‐
to unknown keys or a security error related to "webconfig". thentication, asp.net 4.5 has not been installed.
Restart Idp_webui_, etc.
UMCONF error 4 when connecting. The list of UMC rings is already full - check the ring master with
"umconf -t" and disconnect the secondary ring.
Windows 7 OS, authentication error (4 or 1) when attempting Security KB is missing - see the installation manual of the User
to authenticate, crash of um.server.exe, error at LadLibrar‐ Management Component.
yEX()
Integrated Windows authentication The IdP page asks for login The AD (Kerberos) is configured incorrectly. See the link below
information even if the user is correctly logged in to the AD to avoid problems in our test domain controller:
(the client is connected to the same AD as the web server). https://techcommunity.microsoft.com/t5/iis-support-blog/
setting-up-kerberos-authentication-for-a-website-in-iis/ba-p/
347882
Setting the Service Principal Name (SPN) requires Windows
domain administrator rights.
Set the IIS authenticated user override to "useauthenticate‐
dUser" as described here: https://docs.microsoft.com/en-us/iis/
configuration/system.webServer/serverRuntime with this
command: "appcmd.exe set config "Default Web Site" -sec‐
tion:system.webServer/serverRuntime /authenticatedUserO‐
verride: "UseAuthenticatedUser" /commit:apphost"
SMARTCARD: Error 403.7 forbidden when attempting to open Enable CRL (Client Revocation List), contact your IT depart‐
the info.aspx page and/or attempting to authenticate. ment for more information.
The "Maximum request length exceeded" server error is issued. A request that exceeds the maximum IIS configuration limits
has been sent to the server. You can change the IIS configura‐
tion if required.
UMC operations freeze and display a general or wrong error Check whether all UMC processes are active.
message.
Operations that require changes to the UM configuration fail Check whether the UMC master server is running correctly and
with the error SL_NOTAMASTER. is reachable.
If the problem also occurs on the primary UMC ring server,
restart the "um.ring.exe" service.

UMC - Central User Management

78 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.8 Troubleshooting

Problem definition Solution

Some operations fail sporadically with a general error. The "um.racrmtsrv.log" file contains an error when accessing
UMC DB files. Please check the cause of the file system error
(antivirus, backup etc.).
Error at login: "Validation of the 'service' parameter failed" The service is not in the allowlist (the service is a parameter
that is transferred to the login request and identifies the call‐
er). Use "umconf" to add an allowlist entry, or log in the first
time with the user with the role "UMC Admin" (this will auto‐
matically add the service to the allowlist)
The same error appears when the user attempts to open the
idp page directly: "https://vm-umc6.umdom1.net/umc-idp/
idpauthsite/index.html" without starting "https://vm-
umc6.umdom1.net/umc"
Problem with the visualization of the login screen (2.x) Check if ARR is installed and also "ciis component url rewrite".
If yes, check the address and the redirection within the rule. It
must be consistent with the entry for web settings in the Win‐
dows Registry database.

Reference

Problem definition Solution Additional links

Unable to configure provisioning. Ensure that the UMC ring server belongs not applicable
to the Windows domain.
In the UMC Web UI, "undefined" is dis‐ Ensure that the UMC ring server belongs not applicable
played in the domain drop-down list for to the Windows domain, that you have
importing users/groups. configured the "UP Service" service and
that the Windows user associated with
the service has access rights to Active Di‐
rectory.
The import buttons are not displayed in Make sure that you have configured the The commands can be found in the UM‐
the UMC Web UI. UMC provisioning service "UP Service" CONF reference and UMX reference.
and check whether the value of the
HKEY_LOCAL_MACHINE\SOFTWARE\Sie‐
mens\User Management\WebUI\Set‐
tings\domains_support registry key is
set to "yes".
You import an AD group and the mem‐ Make sure that you have configured the See "Link between Active Directory Win‐
bers are not imported. UMC provisioning service "UP Service" dows user and provisioning service."
with the user who has write access to the
UMC folder "C:\ProgramData\Sie‐
mens\UserManagement\CONF". Alterna‐
tively, the user must belong to the "UM
service accounts" Windows group.
You import an AD group and the mem‐ Make sure that the area of the group is See UMCONF reference
bers are not imported. universal.
The search for the import of AD users/ You may need to change the "MaxPage‐ See the restricted functions in the Re‐
groups yields 0 results, and you assume Size" management limit of Active Direc‐ lease Notes.
that your search criteria will provide a lot tory. Note that the default AD value is
of data. 1000. If your search returns more than
1000 results, you must change this value
to a value higher than the number of
search results.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 79
Installing and configuring UMC
3.8 Troubleshooting

Problem definition Solution Additional links

The import of an AD group with a large You may need to change the "MaxVal‐ See the restricted functions in the Re‐
number of associated users is unsuccess‐ Range" management limit of Active Di‐ lease Notes.
ful. rectory.
The AD provisioning (e.g. import of Check the CPU usage of your antivirus not applicable
users, reconciliation of AD changes, etc.) program, as the antivirus program can
is performed extremely slowly. affect the performance of the AD provi‐
sioning.
The search for importing AD users and Make sure that the name you enter not applicable
AD groups does not yield any results, matches the "Name" parameter in Active
even though the entered user name or Directory. The "displayName", "display‐
group name exists in Active Directory. NamePrintable" and "sAMAccount‐
Name" parameters are not checked.
The import of groups with the same The names of imported groups of the not applicable
name but from different organizational same domain must be unique.
units fails. If the group does not yet exist in UMC,
only one of the groups is imported, even
if the error message states that the ob‐
ject cannot be created.

Use of the Health Check Service

As of UMC 1.8, it is possible to use a local endpoint to check the UMC system status (https://
localhost:16/healthcheck).

UMC - Central User Management

80 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.9 Additional information

3.9 Additional information

3.9.1 Importing a local Windows user into a UMC agent

Local Windows users can be imported on a UMC agent computer using the
"Siemens.UMC.ImportUser.ps1" Powershell script, which is located in "%ProgramFiles%
\Siemens\UserManagement\BIN".

Procedure
1. Run Powershell as an administrator.
2. Insert "-server" followed by the name of the UMC server.
3. Insert "-user" followed by the user name of the UMC user executing the command. The
specified user must have the UM function right "UM_Admin".
4. Insert "-pwd" followed by the password of the UMC user executing the command.
5. Insert "-username" followed by the user name of the local Windows user you want to import.
The user name of the local Windows user to be imported must be structured according to one
of the following patterns:
– "<computer name\name" of the local Windows user to be imported in the case of a
Windows user.
– "NT SERVICE\<SERVICE NAME>" in the case of a virtual Windows service account.
6. Click "Input".

Example
.\Siemens.UMC.ImportUser.ps1 -server myumcservername -user
myumcadminusername -pwd myumcpassword -username
mycomputername\nameofwindowslocaluser

Example for the import of a virtual service account

.\Siemens.UMC.ImportUser.ps1 -server myumcservername -user
myumcadminusername -pwd myumcpassword -username "NT SERVICE\<SERVICE
NAME>"

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 81
Installing and configuring UMC
3.9 Additional information

3.9.2 UMC processes

Table 3-2 UMC-S

Service name Service description Process name Process description

UMC Secure Communication UMC communication service IPCSecCom.exe UMC Secure Communication
Service
um.Ris.exe UMC RIS server
um.ffsyssrv.exe UMC FFSYS server
um.kei.exe UMC certification server
um.sso.exe UMC single sign-on server
um.jei.exe UMC join server
um.ess.exe UMC session identity
UMC Service UMC core service UMCService.exe UMC core service
um.server.exe UMC agent server
um.RACRMSRV.exe UMC RACRM server
um.ring.exe UMC ring server
um.ssrem.exe UMC Secure Socket Request
Server
um.ELGSrv.exe UMC event log server
UP Service UMC provisioning service UPService.exe UMC provisioning service
um.piisrv.exe UMC provisioning server

3.9.3 Event logging

UMC provides event logging. UMC event logging provides a mechanism for storing the history
of events raised by the UMC component. The event data is stored in one or more files.
The um.ELGSrv.exe server is available for the management of the event logging.
The following table summarizes the logged events.

Event Logged
Authentication Successful login
Failed login
Change password
Ticket validation
Management of sessions Creation of sessions
Deletion of sessions

UMC - Central User Management

82 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.9 Additional information

Event Logged
Configuration Create/delete/change UM user (only via UMC Web UI)
Create/delete/change UM role (only via UMC Web UI)
Create/delete/change UM group (only via UMC Web UI)
Unlock the user (only via UMC Web UI)
User locked (if automatic release
is configured)
Changes of the global account
policies
Two-factor authentication Creation of secret key (only via UMC Web UI)
Reset of secret key (only via UMC Web UI)
Temporary one-time password
(TOTP) successfully checked
Temporary one-time password
(TOTP) not successfully checked
SADS Encryption enabled for subject
(UM user or UM group)
Failed decryption of the applica‐
tion key due to user authentica‐
tion failure
Identity provider Host automatically added to the
identity provider's allowlist
Identity provider starts

Identity provider stops

Event logging provides the following functions.

• In a redundant scenario, log files may be generated by different servers. There are
mechanisms to manage the reconciliation of data coming from different servers.
• Internal APIs make it possible to write UMC events and search for UMC events on a specific
date.
• A UMC Web UI page (with limited reading capabilities) has been created to view event data
and search it by an entered date. The old value and the new value of the UMC data associated
with the event are displayed.
• A UMX command to list event log records is available.

3.9.3.1 Event logging security notes

The following security strategies have been implemented to ensure system integrity for each
server computer:
• Automatic cleanup of the archive folder to remove old archives before the hard drive is full.
• Protection against excessive log activity to prevent the archive size from increasing too
quickly.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 83
Installing and configuring UMC
3.9 Additional information

Automatic cleanup of the archive folder

The archive folder contains a list of archive files, each of which has a maximum size of 1 GB
(~500000 records). Each time this limit is reached, a new archive file is created and the files that
are older than 30 days are deleted. This means that archive files are only deleted if there is actual
log activity and storage space is needed.
Change the 30-day limit:
1. Go to the "ELG" registry key: "HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User
Management\ELG\Settings"
2. Add the "DWORD" value to "max_archive_time" or update it with the new duration in seconds.

Protection against excessive log activity

Excessive log activity can result from an attempt to fill up the hard drive of the server and impair
the availability of the system.
To mitigate this attack, the archive files cannot store more than 100000 records per day (but
log forwarding still works).
When this limit is reached, an event log is written with the "ELG CLOSE" action and all
subsequent event logs are no longer archived.
To restore the log archiving:
1. Go to the "ELG" registry key: "HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User
Management\ELG\Settings"
2. Delete the value "DWORD" "num_archive_records_in_last_day".
3. Restart the UMC service.
If the excess log activity is generated on an unconnected server, the "ELG CLOSE" event log is
written and the subsequent (local) event logs are no longer archived.
To restore the (local) log archiving:
1. Go to the "ELG" registry key: "HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User
Management\ELG\Settings"
2. Delete the value "DWORD" "num_archive_records_in_last_day_no_index".
3. Restart the UMC service.
To change the limit of 100000 records per day:
1. Go to the "ELG" registry key: "HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User
Management\ELG\Settings"
2. Add or update the "DWORD" value to "max_archive_records_by_day" with the new number of
records.

3.9.4 Additional provisioning configuration

To make the import of AD users and AD groups configurable, a file with the name
"piisrv_config.json" is created in "%Program Data%\siemens\usermanagement\conf".

UMC - Central User Management

84 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.9 Additional information

Editing this file is optional. When creating the list of domains from which users and/or groups
can be imported, the following rules apply:
• if the "domains" property is not empty, this list is taken into account for the import, otherwise
• the "query_for_domains" field defines the AD input query for calculating the domain list.
Required after modifying the file:
• Copy the file to each computer where the provisioning has been configured, and
• perform a manual restart of the "UP Service" service.
The file requires the following JSON format.

Example configuration JSON

{
"add_alias_to": "",
"domains": [{
"name": "domain1"
}],
"purge_time": "720",
"query_for_domains": "(objectcategory=crossref)",
"query_for_groups": "",
"query_for_user": "",
"query_for_users": "",
"recycle_time": "1440",
"update_mode":"noupdate",
"polling_umc":"60",
"polling_ad":"300",
"import_users_from_nested_groups":"no",
"ldaps":"yes"
}

Note
• If "polling_umc" and "polling_ad" are missing, the following polling values are used by
default:
– polling_umc 60 sec
– polling_ad 600 sec
• "update_mode": "noupdate": (optional) If this option is set to "noupdate", no update of AD is
performed.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 85
Installing and configuring UMC
3.9 Additional information

JSON description

Property Type Description

add_alias_to String The name of the LDAP attribute that cor‐
responds to the AD field to be used as an
alias.
domains String An array of domains, where each do‐
main object contains the name. Format‐
ted as follows: [{"name": "domain1"},
{"name": "domain2"}] }, where it should
be noted that the domain suffix should
not be used. By default, the array is emp‐
ty.
purge_time String When a user is deleted from AD, they are
marked as offline. Offline users are per‐
manently deleted from the UMC data‐
base after a number of minutes specified
in this field. The default is 24 hours
(1440 minutes). The following restric‐
tion must be valid: "purge_time<recy‐
cle_time".
query_for_domains String AD query, see Microsoft documentation
for more details. The query "(objectcate‐
gory=crossref)" is the standard query. If
the query in the file contains an error, the
standard query is executed.
query_for_users String Not used.
query_for_groups String Not used.
query_for_user String Not used.
recycle_time String Number of minutes until the restart of
the provisioning server. The default is 24
hours (1440 minutes). The following re‐
striction must be valid: "purge_time<re‐
cycle_time".
polling_umc String The interval at which the polling is exe‐
cuted in UMC (default value: 60 seconds)
The polling checks whether users that
were imported from AD to UMC still exist
in AD. If a user no longer exists in AD, it
can be deleted in UMC.
polling_ad String The interval at which the polling in AD is
executed (default value: 600 seconds)

UMC - Central User Management

86 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.9 Additional information

Property Type Description

update_mode String Update mode for imported users and
groups. The possible values are: "nore‐
move", "noupdate" or an empty string.
The default value is "noremove".
If the parameter is set to "noremove", a
user remains online after removal from
an AD group in UMC. The authentication
still works.
If the property "update_mode":"" is set,
then the property "polling_ad>600"
must be set.
import_users_from_nested_groups String Allowed values are "yes" or "no". If the
property is not present, the default is
"no". If the value of the property is "yes",
the provisioning searches for all users in
the subgroups of the group, imports
them and assigns them to the parent
group.
ldaps String Allowed values are "yes" or "no". If the
property is not present, the default is
"yes". If the value of the property is "yes",
the provisioning switches to the connec‐
tion type "ldaps", otherwise to the con‐
nection type "ldap".

Update behavior

update_mode Object AD command UMC command Result

not present or empty User imported manual‐ Rename/remove user not applicable The user is online, but
string ly from AD authentication fails.
not present or empty User import by groups Remove binding be‐ not applicable The user is taken off‐
string tween user and group line, authentication
fails.
not present or empty User import by groups Rename / delete group not applicable The user is taken off‐
string line, authentication
fails.
not present or empty User import by groups Remove user from AD not applicable The user is taken off‐
string line, authentication
fails.
not present or empty User import by groups Rename user from AD not applicable The user is taken offline
string and the authentication
fails, a new, renamed
user is imported into
UMC and the authenti‐
cation is available.
noremove \ noupdate User imported manual‐ Rename/remove user not applicable The user is online, but
ly from AD authentication fails.
noremove \ noupdate User imported manual‐ Rename/remove user umx -sync The user is online, but
ly from AD authentication fails.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 87
Installing and configuring UMC
3.9 Additional information

update_mode Object AD command UMC command Result

noremove \noupdate User import by groups Remove binding of the not applicable The user remains on‐
user group line and the authentica‐
tion succeeds.
noremove \noupdate User import by groups Remove binding of the umx -sync The user is taken off‐
user group line, authentication
fails.
noremove \ noupdate User import by groups Rename / delete group The user is online, the
authentication suc‐
ceeds.
noremove \ noupdate User import by groups Rename / delete group umx -sync The user is taken off‐
line, authentication
fails.
noremove \ noupdate User import by groups Remove user from AD The user is online, the
authentication fails.
noremove \ noupdate User import by groups Remove user from AD umx -sync The user is taken off‐
line, authentication
fails.
noremove \ noupdate User import by groups Rename user from AD The user is online, the
authentication fails, a
new renamed user is
imported into UMC and
the authentication suc‐
ceeds.
noremove \ noupdate User import by groups Rename user from AD umx -sync The user is taken off‐
line, authentication
fails, a new renamed
user is imported into
UMC and the authenti‐
cation succeeds.
noremove User import by groups / Update user The user is updated.
manually
noupdate User import by groups / Update user The user is not updated.
manually
noupdate User import by groups / Updated user umx -sync The user is updated.
manually

3.9.5 Additional provisioning details

The AD domain name is prefixed to the user name and group name when importing into UMC.
Organizational units are ignored.

UMC - Central User Management

88 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.9 Additional information

Requirements
• Requirements in Active Directory
– The "sAMAccountName" user and group attribute must be unique in the domain
– The NETBIOS names of the domain must be unique in the AD forest
• Requirements in UMC
– The user and group name must be unique after the conversion

Import from multiple domains

As there is only one user associated with the "UP Service" service, importing from multiple
domains requires a trusted connection between them.
In addition, the NETBIOS names of all domains in the forest must be unique.
If the right trusted connections are in place, it is possible to import groups with users from
multiple domains.

Example scenarios for the import from multiple domains

Domain 1
Name: domain.local
NETBIOS name: DOMAIN
Groups and users:
• DOMAIN\group1
– DOMAIN\testUser1
• DOMAIN\groupX
– DOMAIN\testUser1
– SUBDOMAIN\testUser1

Domain 2
Name: subdomain.domain.local
NETBIOS name: SUBDOMAIN
Groups and users:
• SUBDOMAIN\group1
– SUBDOMAIN\testUser1

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 89
Installing and configuring UMC
3.9 Additional information

Situation A
• Import AD group "DOMAIN\group1" into UMC
– The UMC group is named "DOMAIN\group1".
– The AD user "DOMAIN\testUser1" is imported and given the name "domain\testUser1".
– The UMC user "domain\testUser1" becomes part of the group "DOMAIN\group1".
• Import AD group "SUBDOMAIN\group1" into UMC
– The UMC group is named "SUBDOMAIN\group1".
– The AD user "SUBDOMAIN\testUser1" is imported and given the name
"subdomain\testUser1".
– The UMC user "subdomain\testUser1" becomes part of the group "SUBDOMAIN\group1".

Situation B
• Import AD groups "DOMAIN\group1" and "SUBDOMAIN\group1" into UMC at the same time
– The UMC groups are named "DOMAIN\group1" and "SUBDOMAIN\group1".
– The AD user "DOMAIN\testUser1" is imported and given the name "domain\testUser1".
– The AD user "SUBDOMAIN\testUser1" is imported and given the name
"subdomain\testUser1".
– The UMC user "domain\testUser1" becomes part of the group "DOMAIN\group1".
– The UMC user "subdomain\testUser1" becomes part of the group "SUBDOMAIN\group1".

Situation C
• Import an AD group "DOMAIN\groupX" that contains users from both AD domains
– The UMC group is named "DOMAIN\groupX".
– The AD user "DOMAIN\testUser1" is imported and given the name "domain\testUser1".
– The AD user "SUBDOMAIN\testUser1" is imported and given the name
"subdomain\testUser1".
– The UMC user "domain\testUser1" becomes part of the group "DOMAIN\groupX".
– The UMC user "subdomain\testUser1" becomes part of the group "DOMAIN\groupX".

UMC - Central User Management

90 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Installing and configuring UMC
3.9 Additional information

3.9.6 Performing the automatic certificates renewal

UMC domain certificates

In a UMC domain, the secure channel between UMC computers is ensured by two types of
certificates that are managed by the communication system:
• The network certificate: This is created on the UMC ring master when the UMC domain is
created. By default, the validity is 10 years, but it can be configured when the UMC domain
is created (see UMCONF reference for details). The network certificate is distributed in the
UMC domain as soon as a UM server/agent joins/attaches to the UMC domain.
• The network certificate: This is assigned to each computer when it joins/attaches to the UMC
domain. The computer certificate is valid for the same amount of time as the network
certificate.

Effects of the expiration of certificates

If a TCP connection between UMC servers already exists, the expiration of the certificates does
not affect the system as long as the connection is maintained. This holds true for both certificate
types (network and computer).
Once a certificate has expired, as soon as the connection is disconnected or the UM RIS
module of one of the connected devices is restarted, communication is no longer established.
In particular:
• If the computer certificate (for a UMC ring server, UMC server, UMC agent) expires, the
communication between that computer and the computer connected to it is affected.
• If the network certificate expires, this problem affects all UMC servers and UMC agents in the
UMC domain (expiration of the network certificate is equivalent to invalidity of all computer
certificates).

Procedure for renewal of certificates

The certificate renewal procedure is performed on a computer when less than two years remain
until expiration of the certificate. The process starts automatically when the device is restarted.
At the first restart of the computer within two years after expiration of the certificate, the
following actions are performed:
• On the primary UMC ring master, a new network certificate and the certificate of the UMC ring
computer are created and stored. Communication with the other computers continues to
take place using the previous certificates.
• On the secondary ring, the network certificate is passed on and stored, a new computer
certificate is assigned and the communication can use the new certificates.
• On the other UMC servers and the UMC agents, the network certificate is passed on and
stored and the new computer certificate is assigned. The communication with the UMC ring
master and with the other UMC servers can use the new certificates.
Until the UMC ring master is restarted, the restart of all other computers in the UMC domain
has no effects.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 91
Installing and configuring UMC
3.9 Additional information

The required order for the restart is the following: primary UMC ring, secondary UMC ring,
UMC servers, UMC agents.
It is assumed that within two years after expiration of the validity period of the certificate, at
least one restart in the required order is performed.
If only the computer certificate expires on a UMC computer (e.g. UMC version ≤ 2.7), the
procedure for certificate renewal only has to be carried out on this computer by restarting the
computer.

Result of the certificate renewal

After the certificate renewal, the following applies:
• The new network and computer certificates have a validity period of 10 years.
• The NETID of each UM computer is changed, therefore the fingerprint is also changed.
• The domain ID of the UMC domain is not changed.
The certificate renewal has no effect on the claim key of the identity provider.

Update of the UMC version

If a UMC domain is updated from an earlier version, it is possible that the validity of the
certificates is already more than two years before the expiration date. In this case, the automatic
procedure for the certificate renewal begins as soon as the domain is updated with the
corresponding command "UMCONF -U". Any restart that may be required during the installation
phase does not trigger the renewal process.

Note
If the update command "UMCONF -U" is not executed on the computer after a UMC update, the
automatic certificate renewal is disabled and a restart of the computer does not trigger the
certificate renewal

Exceptions
• If the certificates have already expired, the automatic renewal cannot be carried out and a
manual procedure is required.

UMC - Central User Management

92 Programming and Operating Manual, 11/2023, A5E52954435-AA
Using UMC Web UI 4
4.1 Quick guide to using the UMC Web UI

Accessing the UMC Web UI

After you have configured the UMC Web UI, you can open the login page of the UMC Web UI
under the "http:/// <myServer>umc" or "https://<myServer>/umc" address, depending on the
configuration.
See also: Logging in to the UMC Web UI (Page 94)

Before the login

Make sure you have followed the general recommendations for security and the correct use of
UMC before accessing the UMC work environment.
See also: General Recommendations (Page 93)

Workflow
1. Logging in to the UMC Web UI (Page 94)
2. Home page of the UMC Web UI (Page 96)

4.1.1 General Recommendations

On this page you will find a number of general recommendations that you should follow in order
for the UMC Web UI to function correctly and securely.

Note
Note that when you log in to UMC, you enter a protected environment. To leave, you must log
out, because simply closing the browser does not guarantee that you have left this protected
environment. In addition, the following security information must be taken into account.

Additional important recommendations

• The browser used to display the UMC Web UI must allow the display of popups.
• When using the UMC Web UI, do not select the "Prevent this page from generating additional
dialogs" option. The selection of this option will result in malfunctions of the UMC Web UI.
• Disable the "Autocomplete" option in the settings of your browser.
• Disable the option to save passwords in the settings of your browser.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 93
Using UMC Web UI
4.1 Quick guide to using the UMC Web UI

• Do not use the "Back" and "Forward" navigation buttons of the browser.
• Do not copy a URL of the UMC Web UI to insert it into other browser windows.

4.1.2 Logging in to the UMC Web UI

Requirements
To log in to the UMC Web UI, you must have at least one of the following UM function rights:
• "UM_ADMIN": You can perform all available UMC Web UI operations.
• "UM_VIEW": You can view the data contained in the UMC Web UI, but you cannot make any
changes.
Depending on the existing UM function right, certain operations may or may not be allowed.
Note that during the use of custom plugins for authentication, some may not have the
required "strong" security level to log in to the UMC Web UI.

Note
The computer is automatically added to the allowlist when you authenticate as a user with the
UM role "Administrator".

Procedure
You can log in to the UMC Web UI in one of the following ways:
• Enter the user name and password of a UMC user.
• Click "Log in with current Windows session".
Depending on the type of authentication method configured (smartcard and/or plugin),
additional selection elements are displayed on the login page.

UMC - Central User Management

94 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.1 Quick guide to using the UMC Web UI

Language of the UMC Web UI

The login page ("Identity provider" component) is displayed in the language you selected in your
browser settings. If no browser settings have been defined, the default language is "English".
From the menu in the upper right corner of the page, you can change the language in which
the login page and the corresponding messages are displayed.
After you log in, the UMC pages are displayed according to the "User language" property of
the logged-in user. If the "User language" property has not been defined, the language of the
UMC pages is the language of the login page.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 95
Using UMC Web UI
4.1 Quick guide to using the UMC Web UI

4.1.3 Home page of the UMC Web UI

After you have logged in, the home page of the UMC Web UI is displayed:

Possible options
You can select the following options from the menu in the upper right corner of the page:
• Logoff
• Access to the "User profile" page
In addition, depending on your UM function rights, you can access the pages of the UMC
Web UI where you have additional options:
• Managing UM users (Page 101)
• Managing UM groups (Page 112)
• Managing UM roles (Page 119)
• Managing account policies (Page 123)
• Managing IdP configurations (Page 130)
• Managing system users (Page 136)
• Viewing event log (Page 137)

Additional functions
If UMC has been installed on the client computer and corresponding user access rights are
available, you can use the "Register client" button in the upper left corner to register the
computer from which login station information can be provided as a trusted computer.
For more information on the UMC station client, see <Topic in the installation guide> section.

UMC - Central User Management

96 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.2 Changing user profile

4.2 Changing user profile

Access to the "User profile" page

Select "User profile" from the menu at the top right of the "UMC home page" or click on the "User
profile" button on the home page. The "User profile" page is displayed.

Possible options
The following options are available on the "Settings" page:
• Changing Password (Page 97)
• Changing Language (Page 98)
• Generating a Secret Key (Page 99)

4.2.1 Changing Password

You have the option to change your password via your user profile. Empty passwords are not
allowed.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 97
Using UMC Web UI
4.2 Changing user profile

Procedure
1. Select "User profile" from the menu at the top right of the UMC home page or click on the
"User profile" button on the home page.
The "User profile" page is displayed.
2. Select the "Change password" tab.
The "Change password" tab is displayed.

3. Enter your old password and your new password twice.

4. Click "Change".

4.2.2 Changing Language

You have the option to change your language and the language of the data via your user profile.

UMC - Central User Management

98 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.2 Changing user profile

Procedure
1. Select "User profile" from the menu at the top right of the "UMC home page" or click on the
"User profile" button on the home page.
The "User profile" page is displayed.
2. Select the "Change language" tab.

3. Select the desired language from the "Language" drop-down list.

4. Select the desired data language from the "Data language" drop-down list.
5. Click "Change".

4.2.3 Generating a Secret Key

Allows you to create or reset the secret key for a UM user. The key can then be used to generate
tokens for the two-factor authentication via TOTP (temporary one-time password).

Requirements
• Secure Application Data Support (SADS) has been enabled in the account policies via the
UMC Web UI or UMX and is required for secret protection.
See also: Managing account policies (Page 123)
• The two-factor authentication has been enabled as an authentication method via the UMC
Web UI or the central configuration management UMCONF.
See also: Configuring authentication options (Page 131)
• The two-factor authentication has been enabled for the user in his account policies via the
UMC Web UI or the encryption has been enabled for the user via UMX.
See also: Editing account policies (Page 106)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 99
Using UMC Web UI
4.2 Changing user profile

Procedure
1. Select "User profile" from the menu at the top right of the UMC home page or click on the
"User profile" button on the home page.
The "User profile" page is displayed.
2. Click the "Manage 2FA" tab.
The "Manage 2FA" tab is displayed.

3. Click on either "Show secret key" or "Reset secret key".

UMC - Central User Management

100 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.3 Managing UM users

4.3 Managing UM users

Access to the "User" page

Select the "User" option from the menu at the top right of the UMC home page. The "User" page
is displayed.

Possible options
Below each column name is a filter box that you can use to filter the content of the selected
column. The following options are available on the "Settings" page:
• Creating UMC users (Page 102)
• Updating UM users (Page 103)
• Importing AD users (Page 108)
• Unlocking UM users (Page 111)
• Delete a user
Note that users imported from an AD group cannot be deleted.
See also: Managing UM groups (Page 112)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 101
Using UMC Web UI
4.3 Managing UM users

When you manage UM users, keep in mind the field restrictions of the corresponding
umx commands.
See also "Importing and exporting UM users and groups (Page 216)" in the UMX reference.

Note
System users that have been imported into UMC (via UMX), such as local Windows users, virtual
service accounts, IIS app pool identities, are not listed on the "User" page. The "System user" page
can be used for the visualization.

4.3.1 Creating UMC users

You can create one or more UMC users on the "User" page.

Procedure
1. Select the "User" option from the menu at the top right of the UMC home page.
The "User" page is displayed.

2. Click "Add user".

3. Insert the user details in the new empty fields that appear above the columns.
4. Optional: You can mark the UMC user as offline in the "Domain" column. Offline users are
automatically enabled.
5. Perform one of the following actions:
– To confirm the creation, click "Update".
– To cancel the insertion, click "Cancel".

UMC - Central User Management

102 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.3 Managing UM users

Note
• The default domain for new users is UMC.
• If "Password must be changed" is selected, the user must set a new password at the next login.
• If "Password can be changed" is selected, the password can be reset by the user.
• The password specified by an administrator when creating or updating a UMC user is not
bound by password policies. This is only the case if the password check has been activated.

4.3.2 Updating UM users

Note
For imported AD and local users, editing restrictions apply. For more details, see the "Updating
AD users" and "Updating local users" sections.

Note that the password that you specify when you edit a UM user is not bound by password
policies. This is only the case if the password check has been activated.

Editing UM users
You can edit the primary information of a UM user directly in the table on the "User" page. To do
this, select the corresponding UM user and click "Edit". If you want to insert or edit additional
user details, first select the UM user and click "Details". The corresponding detail dialog is
displayed.

Possible options
Each tab groups the user details that you can edit in that tab. A description is provided for the
properties whose editing requires additional explanation:
• "Attributes" tab: Editing User Attributes (Page 105)
• "Groups" tab: Display of the group membership of the UM user. To find out how to add a UM
user to a group, see Managing groups (Page 112).
• "Roles" tab: Assigning UM role to a user (Page 106)
• "Account policy" tab: Editing account policies (Page 106)
• "Status" tab: With the "Change user status" function, you can perform the following actions:
– Enable or disable a UM user
– Unlock a user
– Reactivate an expired user
– Define whether a UM user can or must change their password

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 103
Using UMC Web UI
4.3 Managing UM users

Note
No input validation has been implemented in the current version of UMC.

Updating AD users
Imported fields are not editable. Only the following fields, which are not imported, can be
changed:
• "General" tab: "Language" and "Data language"
• "Info" tab: "E-mail2" and "E-mail3"
• "Status" tab: "Enabled"
• "Attributes" tab: User-defined UMC attributes can be created, modified and deleted.
• "Groups" tab: For all users, this tab displays only the membership in a user group. For a
description of how to add a user to a group, see Managing UM groups (Page 112).
• "Roles" tab: UM roles can be changed.
• "Account policy" tab: The "User expiration date" field, the alert fields and the "Password
duration (days)" field are not applicable. Only the "PKI alias" and the "authentication alias" can
be changed.
• "Time (minutes) until autom. logout" tab: Number of minutes before the session will be
automatically ended.
All other fields are imported from AD and cannot be changed via the UMC Web UI. They must
be changed in AD and are automatically synchronized by UMC.

Updating local users

Imported fields are not editable. Only the following fields, which are not imported, can be
changed:
• "General" tab: "First name", "Full name", "Last name", "Initials", "Language" and "Data
language"
• "Info" tab: "Mobile phone", "Telephone", "E-mail1", "E-mail2", and "E-mail3"
• "Status" tab: "Enabled"
• "Attributes" tab: User-defined UMC attributes can be created, modified and deleted.
• "Groups" tab: For all users, this tab displays only the membership in a user group. To find out
how to add a user to a group, see Managing UM groups (Page 112).
• "Roles" tab: UM roles can be changed.
• "Account policy" tab: The "User expiration date" field, the alert fields and the "Password
duration (days)" field are not applicable. Only the "PKI alias" and the "authentication alias" can
be changed.
All other fields are imported from Windows and cannot be changed via the UMC Web UI.

UMC - Central User Management

104 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.3 Managing UM users

4.3.2.1 Editing User Attributes

You have the option to edit the user attributes. You can make the following changes:
• Add new attribute
• Delete attribute
• Edit name or value of an attribute

Procedure
1. Select the "User" option from the menu at the top right of the UMC home page.
The "User" page is displayed.
2. Select the row of the user for whom you want to change the attributes.
3. Click "Details".
A dialog is displayed containing the details of the user.
4. Open the "Attributes" tab.

5. Perform one of the following operations:

– Add new attribute:
Click the "Add attribute" button. Insert the attribute details into the new empty field that
appears at the top of the grid.
– Delete attribute:
Select the row of the attribute you want to delete. Click "Delete".
– Edit the name or value of the attribute:
Click the attribute you want to change. Type the changes you want in the text field.
6. Click the "Apply" button to apply the changes to attributes.
7. Click "Save".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 105
Using UMC Web UI
4.3 Managing UM users

4.3.2.2 Assigning UM role to a user

UMC provides a set of predefined UM roles. You can also define additional UM roles. You can
assign these UM roles to the UM users.
See also: UM role (Page 16)

Note
• You can create new UM roles with the umx command. See the UMCONF reference for more
details.
• The "Administrator" role cannot be linked to UM groups.

Procedure
1. Select the "User" option from the menu at the top right of the UMC home page.
The "User" page is displayed.
2. Select the row of the user to whom you want to assign UM roles.
3. Click "Details".
A dialog is displayed containing the details of the UM user.
4. Open the "Roles" tab.

5. Enter the role name in the field above the table. This field has autocomplete, so you only need
to type the first few letters.
6. Select the desired UM role and click "Save".

4.3.2.3 Editing account policies

You can edit the account policies for user accounts.

UMC - Central User Management

106 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.3 Managing UM users

Procedure
1. Select the "User" option from the menu at the top right of the UMC home page.
The "User" page is displayed.
2. Select the row of the UM user for whom you want to change the account policy.
3. Click "Details".
A dialog is displayed containing the details of the UM user.
4. Open the "Account policy" tab.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 107
Using UMC Web UI
4.3 Managing UM users

5. Fill in the available fields. Pay particular attention to this:

– In the "Auto logoff time (minutes)" field, you can enter a duration (in minutes) for the
desktop session connected to the selected UM user.
– If you select the "Override lock policy on invalid credentials" check box , the user account
will not be locked even if the "Maximum number of errors during login" setting in the
global account policy is exceeded. This field can only be set for users that are created from
scratch in UMC, not for imported UM users.
– The maximum period of validity of a user's password is 1827 days.
– In the "Authentication alias" field, you can specify the alias that will be used to
authenticate the UM user in the following ways:
- Via smartcard authentication: In this case, the "PKI alias" checkbox must be selected and
the smartcard authentication must be configured.
- Via plugin authentication: In this case, the "PKI alias" checkbox must be deselected and
the plugin authentication must be configured.
– If you select the "Enable 2FA" checkbox, you must select "2FA" as the authentication
method in the authentication options and SADS in the global account policies.
See also:
Configuration of authentication options (Page 131)
Management of account policies (Page 123)
6. Click "Save".

4.3.3 Importing AD users

You have the option to import users from Active Directory (AD) into UMC.

General recommendations
• Local users can only be imported using the umx command. For more details, see the UMX
reference under "Import local users or virtual user accounts (Page 226)".
• Editing restrictions apply to imported AD users and local users.
See also: Updating UM users (Page 103)
• The import of users requires a search in Active Directory, which may take a long time and may
not yield results if the AD management limits are exceeded. It is strongly recommended to
limit the search. To import multiple users at the same time, import them via the import of an
AD group.
See also: Managing UM groups (Page 112)

UMC - Central User Management

108 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.3 Managing UM users

Procedure
1. Select the "User" option from the menu at the top right of the UMC home page.
The "User" page is displayed.
2. Click "Import users".
The following dialog opens:

3. Enter the search criteria. The search criteria must contain at least the first three letters of the
user name. Insert a * before the string if you want to search for other characters contained
in the name.
The search is performed in the following Active Directory fields:
– User name (sAMAccountName)
– Full user name (displayName)
– Common Name (cn)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 109
Using UMC Web UI
4.3 Managing UM users

4. Click on "Search".
The following dialog opens:

5. Select the users you want to import and click "Add".

The selected users are displayed as shown in the following example:

6. To import the selected AD users into the UMC database, click "Import".
The Windows groups associated with these users are not imported into the UMC database.
For imported users, user authentication is performed using the Windows system.

UMC - Central User Management

110 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.3 Managing UM users

4.3.4 Unlocking UM users

Note
UM users cannot be explicitly locked. Rather, they are locked if they enter a specified number of
incorrect passwords. The number depends on the global account policies
"SL_ENABLE_LOCK_AFTER_NATTEMPTS" and "SL_MAX_LOGIN_ERRORS".
See also: Managing account policies (Page 239)

Procedure
1. Select the "User" option from the menu at the top right of the UMC home page.
The "User" page is displayed.
2. Select the row of the user you want to unlock.
3. Click "Unlock user".
The "Status" tab in the detail dialog of the user shows whether the user is locked or not.
Alternatively, you can unlock the user in this tab.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 111
Using UMC Web UI
4.4 Managing UM groups

4.4 Managing UM groups

Accessing the "Groups" page

1. Select "Groups" from the menu at the top right of the UMC home page.
The "Groups" page appears.

Possible options
Below each column name is a filter box that you can use to filter the content of the selected
column. The following options are available on the "Settings" page:
• Creating UM groups (Page 112)
• Updating UM groups (Page 113)
• Importing AD groups (Page 115)
• Deleting UM groups (Page 118)
When you manage groups, keep in mind the field restrictions of the corresponding
umx commands.
See also "Importing and exporting UM users and groups (Page 216)" in the UMX reference.

4.4.1 Creating UM groups

You can create one or more groups on the "Groups" page.

UMC - Central User Management

112 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.4 Managing UM groups

Procedure
1. Select "Groups" from the menu at the top right of the UMC home page.
The "Groups" page appears.

2. Click "Add group".

3. Add the group details in the new empty fields displayed at the top of the columns.
4. Optional: You can mark the group as offline in the "Domain" column.
5. Perform one of the following actions:
– To confirm the creation, click "Update".
– To cancel the insertion, click "Cancel".

Offline groups
If the group is created offline, the description may include an LDAP query that is used by the "UP
Service" service to find the Active Directory group and to fill the UMC group with its users.
For more information on offline groups and the format of the description field used to
configure the import, see UM group (Page 15).

4.4.2 Updating UM groups

Editing group details

1. Select "Groups" from the menu at the top right of the UMC home page.
The "Groups" page appears.
2. Select the line of the group for which you want to edit the details.
3. To edit the main information of the group directly in the grid, click "Edit".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 113
Using UMC Web UI
4.4 Managing UM groups

4. If you want to insert or edit additional group details, click "Details".

5. Change the details of the group according to your requirements.

Possible options
Each tab groups the group details that you can edit in that tab. A description is provided for the
properties whose editing requires additional explanation:
• "Members" tab: Assign users to a group
• "Roles" tab: Link UM roles to groups
More details can be found in the section Assigning UM role to a user (Page 106)
• "Group policy" tab: Configure the SADS offline behavior, i.e. secure data support, for the
group.

Assigning a user to a group

1. In the details dialog, open the "Members" tab.
2. In the top box, enter the name of the user you want to add to the group. This field provides
the autocomplete feature, so only the first few letters of the name need to be entered.
3. Select the desired user from the result list and click "Save".

UMC - Central User Management

114 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.4 Managing UM groups

Configuration of SADS offline behavior (secure data support)

On a UMC server, SADS is available if the server is connected to the UMC ring server. If the server
is offline, then SADS is not available. However, you can configure a group to have SADS available
even if the server is disconnected from the UMC ring server. Users of such a group will then be
able to use SADS offline.
You can configure it as follows:
1. In the Details dialog, open the "Group policy" tab.
2. In the "Secure data support - Offline behavior" drop-down list, select "Allow offline protection"
3. Click "Save".

You can reset the offline behavior back to default at any time. Offline use is then no longer
possible.

4.4.3 Importing AD groups

The import of groups requires a search in Active Directory (AD), which can take a long time and
may not yield results if AD management limits are exceeded. It is strongly recommended to limit
the search.

Note
The import of all AD users that belong to a group may take longer (usually a few minutes),
depending on the number of members. During user import, the UMC Web UI can be used to
perform other operations.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 115
Using UMC Web UI
4.4 Managing UM groups

Procedure
1. Select "Groups" from the menu at the top right of the UMC home page.
The "Groups" page appears.
2. Click "Import domain groups".
The following dialog is displayed:

3. Enter the search criteria for the group name in the "Group" field and click "Search".
The following dialog is displayed:

UMC - Central User Management

116 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.4 Managing UM groups

4. Select the group you want to import and click "Add".

The selected groups are displayed as shown in the following example:

5. Click "Import" to import the selected Active Directory groups and their associated Active
Directory users into the UMC database.

Updating AD groups
Recursive AD groups are not imported by default. Members of the imported group and its
recursive groups are imported in to UMC. For these users, authentication is performed using AD.
The imported fields cannot be edited. Therefore, the following rules apply:
• "General" tab: Fields cannot be changed.
• "Group members" tab: Group members cannot be changed, users cannot be added to or
deleted from the group. As a result, users imported from an AD group cannot be deleted.
• "Roles" tab: UM roles can be changed.
See also: Importing AD users (Page 108)

Additional configurations
• Users that belong to nested groups can also be imported. These users are imported and
bound to the parent group. The nested group itself is not imported.
You can find additional information and activation instructions in the section
"AUTOHOTSPOT".
• If an AD group is not allowed to be imported with its Common Name (CN), the group must
be created offline and the description can be used to configure the import criteria.
See also: UM group (Page 15)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 117
Using UMC Web UI
4.4 Managing UM groups

4.4.4 Deleting UM groups

Note
• If a group was created from scratch in the UMC database and is linked to users, all links are
deleted. Users are not deleted.
• If a group was imported from Active Directory into the UMC database and has associated
users, all users not belonging to other groups are deleted.

Procedure
1. Select "Groups" from the menu at the top right of the UMC home page.
The "Groups" page appears.
2. Select the row of the group you want to delete.
3. Click "Delete".

UMC - Central User Management

118 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.5 Managing UM roles

4.5 Managing UM roles

Accessing the "Roles" page

1. Select "Roles" from the menu at the top right of the UMC home page.
The "Roles" page is displayed.

Possible options
Below each column name is a filter box that you can use to filter the content of the selected
column. The following options are available on the "Settings" page:
• Creating UM roles (Page 119)
• Updating UM roles (Page 121)
• Deleting UM role
When you manage UM roles, keep in mind the field restrictions of the corresponding
umx commands.
See also "Importing and exporting UM users and groups (Page 216)" in the UMX reference.

4.5.1 Creating UM roles

You can create one or more UM roles on the "Roles" page. A set of UM roles is automatically
created by the system during the UMC configuration.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 119
Using UMC Web UI
4.5 Managing UM roles

See also: UM role (Page 16)

Procedure
1. Select "Roles" from the menu at the top right of the UMC home page.
The "Roles" page is displayed.

2. Click "Add role".

3. Add the role details in the new empty fields that are displayed above the columns. A
maximum of 200 UM roles are allowed in the system.
4. Perform one of the following actions:
– To confirm the creation, click "Update".
– To cancel the insertion, click "Cancel".

Note
Due to a database limitation for the role IDs, you may receive an error message stating that no
more role IDs are available. If you want to create new UM roles in this case, you must first delete
the existing UM role with the corresponding umconf command.
For more details, see the UMCONF reference.

UMC - Central User Management

120 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.5 Managing UM roles

4.5.2 Updating UM roles

Editing role details

1. Select "Roles" from the menu at the top right of the UMC home page.
The "Roles" page is displayed.
2. Select the row of the UM role that you want to edit.
3. Click "Edit" to edit the main information of the UM role directly in the grid.
4. Click "Details" if you want to insert or edit additional role details.
The following dialog is displayed:

5. Change the details of the UM role according to your requirements.

Possible options
Each tab groups the role details that you can edit on that tab. A description is provided for the
properties whose editing requires additional explanation:
• "Rights" tab: Assigning a UM function right to a UM role

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 121
Using UMC Web UI
4.5 Managing UM roles

Assigning a UM function right to a UM role

1. Open the "Rights" tab in the detail dialog.
2. To assign a UM function right to the selected UM role, select the corresponding check box.

3. Click "Save".

UMC - Central User Management

122 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.6 Managing account policies

4.6 Managing account policies

The policies for authentication are implemented using account policies. These include the
automatic locking of users after incorrect login attempts and the password check. These are
divided into two main groups:
• User account policies: These are defined at the user level, so that each user can have their
own rules for authentication.
• Global account policies: These are defined at the system level and are the same for all users.
The user account policies can also be managed on the "User" page. You can find additional
information in the section Editing account policies (Page 106).
Account policies can also be managed with UMX. For more information, see the Managing
account policies (Page 239) section in the UMX reference.

Note
The maximum duration for password expiration is 1827 days (about 5 years).

Accessing the "Account policies" page

1. Select "Account policies" in the menu at the top right of the UMC home page.
The "Account policies" page is displayed.

Possible options
On the "Account policies" page, you have the following options:
• "Password structure" tab: Definition of the password structure
• "Password lock, duration and reuse" tab: Definition of settings for duration, locking, and
reuse of passwords.
• "Advanced" tab: Configuration of advanced settings

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 123
Using UMC Web UI
4.6 Managing account policies

Definition of the password structure

1. Open the "Password structure" tab.

2. Fill in the available fields with the values you want to set for your passwords. You can also
enable the password policy check during user administration so that administrative users can
only set passwords that comply with the specified policies. This does not apply to password
reuse policies.
The check is disabled if the value in the "Minimum password length" and "Maximum
password length" fields is set to "0". Empty passwords are not allowed.

UMC - Central User Management

124 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.6 Managing account policies

Definition of settings for the password lock, duration, and reuse settings
1. Open the "Password lock, duration, and reuse" tab.

2. Set the maximum number of errors during login that can occur during login before the user
is locked. The user lock is disabled if the value is set to "0".
3. Set the number of days prior to password expiration.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 125
Using UMC Web UI
4.6 Managing account policies

4. Select one of the following options:

– "Enable password history by number of days": Specify the minimum number of days to
wait before reusing a password.
– "Enable password history by number of passwords": Set the number of passwords before
a password can be reused.
5. Set the reset time of the login error counter in minutes for resetting the login error counter.
The reset of the login error counter is disabled if the value is set to "0".
6. Set the automatic user unlock time in minutes. The automatic user unlock is disabled if the
value is set to "0".
7. Set the number of days before Active Directory cache expires. The Active Directory cache is
disabled if the value is set to "0".

UMC - Central User Management

126 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.6 Managing account policies

Configuration of advanced settings

1. Open the "Advanced" tab.

2. Select the field to be used for user authentication via smartcard from the "Built-in filter or
custom filter" drop-down list. The following options are available:
– "Authenticate with common name"
– "Alias authentication using CN"
– "Authentication with filters by subject"
– "Alias authentication with filters for subjects"
– "Authentication with filters for alternative subjects"
– "Alias authentication with filters for alternative subjects"
3. Select the "Enable secure application data support for users and groups" check box to enable
the SADS functionality. At application level, SADS can be enabled via UMX or the UMC Web
UI by changing an account policy. At subject level this is only possible with UMX.
4. Click "Save" to apply your changes.
5. Click "Restore to default" to restore the default values of the global account policy.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 127
Using UMC Web UI
4.7 Managing UMC licenses

4.7 Managing UMC licenses

A valid license is required to use UMC if more than 10 users are managed in the UMC domain.
In such cases, the confirmation that a valid license is in place is required.
If the confirmation is not made, a banner is displayed on each page indicating that a valid
software license is required to use "UMC ring server".

Requirement
You have administrator rights.

UMC - Central User Management

128 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.7 Managing UMC licenses

Confirming UMC licenses

1. Navigate to the "Settings" menu.
The number of users is displayed here.

2. Select the checkbox to confirm that you have a valid license to manage the number of users
in the UMC domain.
3. Click "Save".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 129
Using UMC Web UI
4.8 Managing IdP configurations

4.8 Managing IdP configurations

Accessing the "IdP configuration" page

1. Select the "IdP configuration" option from the menu in the upper right corner of the UMC
home page.
The "IdP configuration" page is displayed.

Possible options
On this page, you can make the following settings:
• Manage authentication options, e.g. enable specific authentication methods and define the
security level.
See also: Configuring authentication options (Page 131)
• Manage disclaimers and customize the content of the disclaimer in the following languages:
English, French, Spanish, German, Italian and Chinese.
See also: Configuring disclaimers (Page 133)
• Manage languages, enable and disable integrated languages and add languages that are not
provided by UMC.
See also: Configuring Languages (Page 133)

UMC - Central User Management

130 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.8 Managing IdP configurations

Note
Enabling or changing the disclaimer establishes a centralized configuration if one does not
already exist. If certain configurations have been made in the local file, these may have to be
applied to the central configuration or overwritten.

4.8.1 Configuring authentication options

You can enable and disable authentication methods and set their security level in the
"Authentication options" tab.

Note
Be careful not to make any configuration that makes it impossible to log in to the UMC Web UI.
In the worst case, even the root user can no longer log in. Therefore, make sure that at least one
authentication level is set to "strong" or that two-factor authentication has been configured and
enabled. For more information, see the installation guide.

Enabling or disabling authentication methods

To enable or disable certain authentication methods, proceed as follows:
1. Select the "Authentication options" tab.
2. Select the check boxes for the desired authentication method.
3. Select the required security level from the drop-down list.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 131
Using UMC Web UI
4.8 Managing IdP configurations

4. Disable the authentication options you do not want to use.

5. If required, enable two-factor authentication (for 2FA through temporary one-time
password) or flexible authentication.
6. Click "Save all changes".

Setting the security level for integrated authentication methods

The strength of the integrated authentication methods and the authentication using third-party
applications can be specified in the configuration.
The UMC Web UI can only be used if the authentication is set to "standard" or "strong".
Possible values are:
• "weak"
• "standard"
• "strong"
To set the security level, proceed as follows:
1. Select the "Authentication options" tab.
2. Select the security level from the drop-down list of the corresponding authentication
method.
3. Click "Save all changes".

Configuring authentication methods for the automatic login

The automatic login is a function that allows you to define one or more authentication methods
that the identity provider uses to attempt an automatic login immediately after the
authentication page loads.
To configure the authentication methods, proceed as follows:
1. Select the "Authentication options" tab.
2. Specify the authentication methods to use for the automatic login by using the following
syntax: <iwa|pki|pluginname>
– Windows authentication: "iwa"
– Smartcard authentication: "pki"
– Desktop plugin, web plugin or flex authentication: "pluginname". The plugin name is the
name used for plugin registration.
It is possible to define multiple authentication methods by separating each method with "|".
The identity provider retrieves the list of methods and uses the first method available in the
list. Example of the syntax to use for automatic login: "iwa|pki|32bitStateless|WebAdapter".
3. Click "Save all changes".

UMC - Central User Management

132 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.8 Managing IdP configurations

4.8.2 Configuring disclaimers

UMC offers the possibility to show or hide disclaimers and to customize the content of the
disclaimer in the following languages: English, French, Spanish, German, Italian and Chinese.

Note
Enabling or changing the disclaimer establishes a centralized configuration if one does not
already exist. If certain configurations have been made in the local file, these may have to be
applied to the central configuration or overwritten.

Enabling disclaimers
To enable the display of disclaimers, follow these steps:
1. Select the "Disclaimer configuration" tab.
2. Select the "Enable disclaimer when a login request is made" check box.

Customizing disclaimers
To customize disclaimers in one of the six standard languages, proceed as follows:
1. Select the "Disclaimer configuration" tab.
2. Select the language from the drop-down list.
3. Change the disclaimer as required and click "Update".
4. Click "Save all changes".

Note
Only the html tags "br" (page break) and "b" (bold) can be used in the disclaimer.

4.8.3 Configuring Languages

In the "Language configuration" tab, you can select the languages to be used from the following
languages provided by UMC:
• English
• French
• Spanish
• German
• Italian
• Chinese
In addition, you can add your own languages. In this case, however, it is necessary that you
provide a resource file with the translations.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 133
Using UMC Web UI
4.8 Managing IdP configurations

Enabling and disabling built-in languages

1. Select the "Language configuration" tab.
The list on the left displays the built-in languages that are currently disabled in the "Built-in
language management" section. The list on the right displays the active languages.
2. Drag a language from one list to the other to enable or disable a built-in language.

Adding custom languages

1. Select the "Language configuration" tab.
2. Click "Add language" in the "Custom languages" area.
3. Enter a language ID and a name under which you want the language to be displayed in the
system. The language ID must comply with RFC 5645.
4. Click "Apply".
5. Click "Save all changes".

UMC - Central User Management

134 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.8 Managing IdP configurations

Creating and providing resource file with translations

After you configure a new language, you must install the resource files that contain the
translations for the new languages in the system.
It is necessary to provide two different resource files: one for the UMC Web UI and one for the
login page of the identity provider. These must be copied to the following paths:
• "C:\Program Files\Siemens\UserManagement\WEB\Umc\js\common\language_files" for the
UMC Web UI.
• "C:\Program Files\Siemens\UserManagement\WEB\IPSimatic-Logon\IDPAuthSite\locales" for
the login page of the identity provider's application.
You can find resource files for existing languages in these two paths and use them as a
template for creating the new resource files for the custom language.

Note
• Each new resource file must be named like the resource files already present in the paths by
adding the language ID inserted during the configuration. In the example below, the file must
be named "umc.ja-jp.json".
• The value of the "language" property in the new resource file must match the value of the
"Language ID" entered in the "Custom languages" tab:

Example:
"language": "ja-jp",
"keys": {
"sessionExpiredLabel": "Session Expired",

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 135
Using UMC Web UI
4.9 Managing system users

4.9 Managing system users

Accessing the "System user" page

1. Select the "System user" option from the menu in the upper right corner of the UMC home
page.
The "System user" page is displayed.

Possible options
On this page, you can view all system users that have been imported into UMC (via UMX):
• Local Windows users
• Virtual service accounts
• IIS app pool identities
These system users are not listed on the "User" page.
Below each column name is a filter box that you can use to filter the content of the selected
column. On the settings page, you can do the following:
• Update user
• Delete user
When you manage users, keep in mind the field restrictions for the corresponding umx
commands.
See also "Importing and exporting UM users and groups (Page 216)" in the UMX reference.

UMC - Central User Management

136 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.10 Viewing event log

4.10 Viewing event log

Requirements
You need the UM function rights "UM_VIEW" and "UM_VIEWELG" or "UM_ADMIN" to access the
"Event log" page.
See also: UM function rights (Page 17)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 137
Using UMC Web UI
4.10 Viewing event log

Procedure
1. Select the "Event log" option from the menu in the upper right corner of the UMC home page.
The "Event log" page is displayed.

2. Select a row and click "Details" to view the details of a record in the event log.
The value is displayed in JSON format on the "Value" tab in the "Log record detail" dialog.

UMC - Central User Management

138 Programming and Operating Manual, 11/2023, A5E52954435-AA
 Using UMC Web UI
4.10 Viewing event log

Error codes
In the event of errors, the UMC Web UI provides one of the following two responses:
• Display of a text error message
• Display of the last error code in hexadecimal format
See UMC APIs error codes (Page 250) for more information.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 139
Using UMC Web UI
4.11 Parameter sizes

4.11 Parameter sizes

Parameter sizes
The following table contains the sizes for the most important UMC database fields:

Name of the API API object Display name in UMX parameter Size in characters
property the UMC Web UI
SL_USER_NAME SLOBJ_USER User name name 100
SL_USER_PASS‐ SLOBJ_USER Password password 120
WORD
SL_USER_FULL‐ SLOBJ_USER Full name fullName 250
NAME
SL_GROUP_NAME SLOBJ_GROUP Group name name 100
SL_GROUP_DE‐ SLOBJ_GROUP Description description 260
SCRIPTION
SL_ROLE_NAME SLOBJ_ROLE Role name name 255
SL_ROLE_DESCRIP‐ SLOBJ_ROLE Description description 40
TION
SL_ATTRIB‐ SLOBJ_ATTRIBUTE Attribute name attribute name 80
UTE_NAME

UMC - Central User Management

140 Programming and Operating Manual, 11/2023, A5E52954435-AA
UMC security concept 5
5.1 Introduction
The following section discusses concepts, procedures and practical configuration settings to
counter the most important security risks and threats to the User Management Component
(UMC). Although user management solutions are often highly customized to meet the needs of
specific industries and projects, some common scenarios are presented to illustrate practical,
security-conscious implementation methods. This section also provides an overview of all
security settings and functions offered by UMC.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 141
UMC security concept
5.2 Security strategies

5.2 Security strategies

5.2.1 Plant security

Plant security covers everything related to physical access protection measures such as fences,
turnstiles, cameras or card-readers and organizational measures, particularly a security
management process, which ensures the long-term security of a plant. Plant security makes it
so that technical IT security measures are more difficult to by-pass physically.

5.2.2 Network security

The central element of the security concept is the network security. This includes measures to
protect the automation networks from unauthorized access and the checking of all interfaces to
other networks, such as an office network and in particular remote access to the Internet. The
network security also includes increasing the protection of communications so that they are less
susceptible to eavesdropping and manipulation, i.e. encryption during data transmission and
authentication of the respective communication nodes as well as network segmentation.
For information on how to implement network security, see Implementation of network
security (Page 144) .

5.2.3 System integrity

Ensuring system integrity should be considered as the third pillar of a balanced security concept.
The system integrity is used to protect against data manipulation and unauthorized access to the
automation process, which can compromise the production process.
Siemens offers:
• Controllers and HMI systems with integrated security functions
• Security functions for PC-based automation systems
• System integrity for motion control and drives
For more information about implementing system integrity, see Implementation of system
integrity (Page 149).

UMC - Central User Management

142 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

5.3 Security implementation

The concepts described in the security strategies require configuration and tools. The pages
listed below contain information about the implementation of the strategies that can be used
to increase the security of a UMC scenario. Note that the implementation of plant security is not
included in the scope of this manual.
• Implementation of network security (Page 144), consisting of:
– Security cells and perimeter network (Page 144)
– Firewalls and VPNs (Page 149)
• Implementation of system integrity (Page 149), consisting of:
– System hardening (Page 150)
– Allowlisting (Page 155)
– Disaster recovery (Page 157)
– Security controller (Page 158)
– Patch management (Page 158)
– Detection and management of malware (Page 159)
– Management of user accounts (Page 160)
– UMC Web UI redirect validation (Page 164)

5.3.1 Step-by-step guide to security implementation

To increase the security of a UMC scenario, you should implement the following security
measures:

Plant security
• Check whether the required organizational and technical security measures are taken and
kept up to date in your company (e.g. security management process).

Network security
• Implement firewalls (Page 149) so that access points are protected and the communication
to and from a security cell is regulated. Only the required ports should be open:
– for UMC, the ports 4002, 4004 and 443
– for GUM, also port 6006
– for SLRA, port 16389
• Implement VPNs (Page 149) to establish secure network connections via public networks.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 143
UMC security concept
5.3 Security implementation

• Create security cells (Page 144) so that the plant is divided into areas that are easier to control
that are logically structured according to function and location.
• Create one or more perimeter networks (Page 144) so that direct communication between
the bottommost and topmost levels of the plant infrastructure is processed in the perimeter
network before the lower levels of the plant are reached.

System integrity
• Harden the system (Page 150) by removing all unnecessary software components and
functions, adding the needed software to the allowlist and then performing the
solidification for the system; in addition, hosts that can connect to an identity provider (IdP)
must be added to the allowlist.
• Enable the code signing check (Page 153) so that the system logs when an executable UMC
file has been modified and thus possibly compromised.
• Create backups (Page 157) of the system and database.
• Set up a patch management (Page 158) to keep the operating system up-to-date and more
secure.
• Implement a management of user accounts (Page 160):
– Configure the authentication and authorization (Page 162) to verify users and restrict
their access.
– Reinforce passwords (Page 162) and implement a password policy.
– Pursue a policy of least privilege (Page 161).

5.3.2 Network security implementation

5.3.2.1 Security cells and perimeter networks

The division of networks and connected systems into security cells includes the division of a
large company network into individual networks that are each used for a specific business
function. This strategy increases the availability of the overall system is an effective way to
reduce security risks. The segmentation of the system into cells is integral to the application of
IEC 62443. With this approach, parts of a network, e.g. an IP subnet, are protected by a security
device and the network is secured through use of segmentation. This allows devices within this
"cell" to be protected from unauthorized access from the outside without impairing real-time
capability, performance or other functions. Security threats that could lead to failure can thus be
limited to the immediate environment.
The various ISA95 levels can be used to designate security cells, e.g. in which ERP functions
(Enterprise Resource Planning) are separated from MES functions (Manufacturing Execution
System). In addition, the example configuration (Page 146) organizes various products into
security cells, each with their own firewall.

UMC - Central User Management

144 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

The ISA95 levels allow differentiation of the following levels:

• Enterprise Resource Planning (ERP) level (Page 145)
• Manufacturing Execution System (Page 145) level
• Manufacturing Control System (Page 145) level
Each level includes one of more networks. Perimeter networks (Page 145) are also
determined.
You should follow a few design principles (Page 146) when creating security cells.
In this section, we also present the example configuration (Page 146), which has been
organized into various security cells.

Enterprise resource planning level

The Enterprise Resource Planning Level includes the Enterprise Control Network that is used to
manage ERP systems, which may need to communicate with both MES and Process Control
Systems located in other networks. This network is generally the outermost network used in a
plant, it is therefore more exposed to potential security risks.

Manufacturing execution systems level

The Manufacturing Execution Systems Level includes the Manufacturing Operations Network
that contains MES/MOM servers. Typically, this network can be connected directly to a Process
Control Network, while the use of a Perimeter Network is recommended with an Enterprise
Control Network instead of direct connections.

Manufacturing control systems level

This level includes:
• Process Control System Network
• Control System Network
• Field Device Network
Because the networks belonging to this level are physically very close to the field, it is
important to keep them as separate as possible from the outer networks, to mitigate security
risks and safeguard plant production. It is out of scope of this document to enter in the
details of the security measures related to this level.

Perimeter network
In addition to the secure lower level networks, we have also Perimeter Networks in our
scenarios, sometimes called DMZs (Demilitarized Zones). These are networks used to isolate
certain applications from outside networks, thereby mitigating security risks.
Typically, Web Servers are placed in this network, so that they can collect data from low level
networks and, at the same time, they can provide web pages to outer networks (for example
an Enterprise Control Network).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 145
UMC security concept
5.3 Security implementation

If you are planning to connect to UMC using the Remote Desktop Service, the Remote
Desktop Service Server should be placed in this network.

Design principles
When creating security cells, you should follow some common guidelines and implementation
best practices, such as the following:
• a security cell is an independent part of the plant;
• all participants inside the cell trust each other;
• access to the security cell is permitted only through clearly-defined access points;
• access points are monitored and access is logged (data traffic, user, hardware);
• all participants of a security cell are directly connected (no bypass to the outside);
• participants with high network load will be integrated into a security cell to avoid bottlenecks.

Example configurations with security cells

The following example illustrates a UMC scenario with the most common networks grouped by
level and product in security cells, where the UMC ring server is on a dedicated computer and
multiple UMC servers are distributed in the scenario.
One of the servers present in the other cells can also be used as a UMC ring server.
The configuration example includes the following UMC computer roles:
• UMC ring server (primary and secondary): The owner of the UMC configuration, which is
responsible for managing the UMC domain and providing the full implementation of the
authentication and user management functions.
• UMC server: A server that provides a full implementation of the authentication functions.
• UMC station client: A computer on which the UMC station client software has been installed
and that has been registered as a trusted computer
• UMC agent: A computer that operates as a client of the UMC server/UMC ring server.
The configuration example includes the following generic computers:
• Web clients: Web computer that is used to access the runtime UI applications and to perform
runtime configurations.
• Generic ERP system: Computer on which an ERP (Enterprise Resource Planning) system is
installed and configured according to the ANSI/ISA95 standard.
• MOM/MES Web clients: Web computer that is used to access the MOM/MES runtime UI
applications and to perform runtime configurations.
• MOM/MES server: Computer that hosts MES/MOM components for a production
environment, with the exception of the data memory.
• MOM/MES data memory: Computer on which the required databases are to be hosted.
Alternatively, the databases can also be created on the production computer (and the
development computer).
• DCS data memory: Computer on which the required databases are to be hosted.

UMC - Central User Management

146 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

• DCS server: Computer that hosts DCS components for a production environment, with the
exception of the data memory.
• SCADA data memory: Computer on which the required databases are to be hosted.
• SCADA server: Computer that hosts the SCADA components for a production environment,
with the exception of the data memory.
• Generic MCS system: Computer/device with a generic Manufacturing Control System (MCS)
according to ANSI/ISA95.
• Generic MCS engineering station: Development computer for the MCS solution.
• Generic MCS client: Client computer for the MCS solution.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 147
UMC security concept
5.3 Security implementation

UMC - Central User Management

148 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

5.3.2.2 Firewalls and VPNs

To ensure network security (Page 142), the access points to the security cells and the
communication between the different access points must be secured. We explore these two
aspects in this section.

Access points to security cells and communications

One of the factors for the design of security cells is that they should have only one access point.
Any access to a security cell via this access point is permitted only after verification of legitimacy
(people and devices require authentication and authorization) and every access must be logged.
The access points help prevent unauthorized data traffic to the security cells, while allowing
authorized and necessary data traffic for the smooth operation of the system. The access
point to a security cell can be designed according to the configuration and functionality
requirements. An example of a security cell with a secure access point is a network in which
all data traffic is protected by a firewall.

Note
Firewalls must be configured with rules to mitigate DDoS attacks.

Access points
In the configuration example (Page 146), the access points to the various security cells are
protected by firewalls that protect the TCP port 4002 and the port used for HTTPS IIS binding
(usually 443) on the computer(s) running UMC.

UMC communication
All UMC communication between servers is carried out using TLS/SSL encryption protocols to
ensure network security, while communication between clients and servers should be carried
out via HTTPS.

5.3.3 System integrity implementation

In information security, the term integrity refers to something, such as data or services, that has
not undergone unauthorized changes. The increase in system integrity should be considered as
the third pillar of a balanced security concept. In order to improve the system integrity, it is
necessary to use automation systems and control components, such as SCADA and HMI
systems, that are protected against unauthorized access and malware or meet special
requirements such as know-how protection.
Customizations can be made by system integrators. However, bear in mind that a distinction
must be made between the effects of the product and the custom code. This distinction can
be made by reviewing the execution and deployment of user-defined code or by providing
coding policies, where the responsibility for code compliance and/or monitoring of the
execution lies with the customer.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 149
UMC security concept
5.3 Security implementation

The system integrity can be improved by:

• System hardening (Page 150)
• Allowlisting (Page 155)
• Disaster recovery (Page 157)
• Security controller (Page 158)
• Patch management (Page 158)
• Detection and prevention of malware (Page 159)
• Management of user accounts (Page 160)
• UMC Web UI redirect validation (Page 164)

5.3.3.1 System hardening

In information security, hardening is the removal of all software components and functions that
are not essential to perform a specific task. In other words: Hardening summarizes all measures
and settings aimed at:
• reducing the possibility of exploiting vulnerabilities in software
• minimizing possible attack methods
• limiting the tools for a successful attack
• minimizing the available rights after a successful attack
• increasing the probability that a successful attack will be detected
This is to increase local security and resistance of a computer to attacks.
Consequently, a system can be said to be "hardened" if:
• the installed software components and services are limited to those required for the actual
operation
• a restrictive user management is introduced
• the local Windows firewall is enabled and configured restrictively
Recommended hardening measures prior to the installation of UMC:
• Uninstall unnecessary programs and Windows components
• Disable unnecessary services
• Harden the computer's BIOS
A system hardening can be achieved by:
• File system configurations (Page 151)
• Creating an allowlist for the identity provider (Page 153)
• Enabling of code signing check (Page 153)

UMC - Central User Management

150 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

• Decommissioning of UMC computers (Page 155)

• IIS hardening, which can be achieved by:
– Configuration of the minimal IIS functions and roles, as described in the UMC installation
manual
– Disabling of TLS 1.0 and 1.1 in the SChannel.
– Disabling the directory entry
– Application of the hardening rules described in the following document: Windows Server
101: Hardening of IIS via configuration of the security controller (https://
techcommunity.microsoft.com/t5/itops-talk-blog/windows-server-101-hardening-iis-
via-security-control/ba-p/
329979#:~:text=Hardening%20IIS%20involves%20applying%20a%20certain%20config
uration%20steps,configuration%2C%20the%20more%20you%20reduce%20functionali
ty%20and%20compatibility.)
Further information can be found on the website of the Federal Office for Information
Security (https://www.bsi.bund.de/EN/Home/home_node.html).

File system
This section describes the security of the file system using the objectives described in the
overview section for system hardening.
UMC has a predefined directory structure that is created during the installation. Folders that
are organized according to the UMC needs are configured with specific permissions during
the installation. These configurations are summarized below in the "Access control table of
UMC" section.
In addition, it is possible to improve the integrity of the file system depending on the security
policies of the customer:
• Encryption of the file system, by using the transparent file system encryption offered by the
operating system
• Configuration of an allowlisting software, for more information, see Allowlisting (Page 155).

Access control table of UMC

The following tables list the product-specific local Windows groups that are automatically
configured for each system folder during the installation. We do not recommend that you
configure additional groups or user rights for these folders. For more details, see the section on
management of user accounts.

Folder path / local Windows Administrators UM service accounts Users

group
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManagement\LOG
%ProgramData%\Sie‐ Full control (cannot write ad‐ Full control Read and execute
mens\UserManagement\DA‐ vanced attributes)
TA

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 151
UMC security concept
5.3 Security implementation

Folder path / local Windows Administrators UM service accounts Users

group
%ProgramData%\Sie‐ Full control Full control Access not possible
mens\UserManage‐
ment\CONF
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\CHANNEL
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\CHANNEL\UN‐
TRUSTED
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\TICKET
%ProgramData%\Sie‐ Full control Full control Access not possible
mens\UserManage‐
ment\CERT\TICKET\PRIVATE
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\XCLIENT
%ProgramData%\Sie‐ Full control Full control Access not possible
mens\UserManage‐
ment\CERT\XCLIENT\PRIVATE
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\SADS
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\SADS\PUBLIC
%ProgramData%\Sie‐ Full control Full control Access not possible
mens\UserManage‐
ment\CERT\SADS\PRIVATE
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\MACHINE
%ProgramData%\Sie‐ Full control Full control Access not possible
mens\UserManage‐
ment\CERT\MACHINE\PRIVATE
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\NETWORK
%ProgramData%\Sie‐ Full control Full control Access not possible
mens\UserManage‐
ment\CERT\NETWORK\PRI‐
VATE
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\CLAIM

UMC - Central User Management

152 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

Folder path / local Windows Administrators UM service accounts Users

group
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\CERT\CLAIM\HISTORY
%ProgramData%\Sie‐ Full control Full control Read and execute
mens\UserManage‐
ment\TEMP

Note
The paths listed in the table above are to be interpreted as follows:
• %ProgramData% and %ProgramFiles% are variables in the Windows environment.

Creating an allowlist for the identity provider

To increase the security of UMC, two types of allowlists can be used:
• Allowlisting of programs to be executed on the computer with McAfee Application Control,
see Allowlisting (Page 155).
• Allowlisting of hosts using UMC functionality that allows you to specify the hosts that can
connect to identity providers in order to protect the computer from potentially malicious
connections.
Allowlisting a host allows you to:
• Call the identity provider (IdP) to validate the service
• Create an iFrame with an embedded IdP to validate the iFrame
If the host is not present in the list, the call will be rejected. The service validation is always
enabled, and if the service is not validated, an error occurs during the authentication phase.
It is possible to automatically add the service present in the login request to the allowlist
during the authentication phase. This is possible if you authenticate with the "Administrator"
role and if the "enableWhitelist" property is set to "true" in the central configuration.

Procedure
1. Add each host to the allowlist by using the required command of the UMCONF utility, as
described on the creation page of the allowlist entry in the UMCONF reference (Page 179).

Enabling code signing check

Code signing is the process of certifying the code of an executable file or script so that it cannot
be altered without invalidating the certificate.
All executable UMC files and dlls are signed and linked to a certificate.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 153
UMC security concept
5.3 Security implementation

UMC provides a security measure that checks whether the executable files are signed when
the services are started and creates a log file with the list of errors found during the check.
This function is disabled by default.

Note
• The operating system may need to use the Internet connection to verify the validity of the
signature.
• In order to enforce this security check, the following procedure must be performed on each
computer on which the UMC is installed.

Procedure
1. Go to "HKEY_LOCAL_MACHINE > SOFTWARE > SIEMENS > User Management > Common" in
the registry editor
2. Right-click on Common, select "New > Key" and insert "SecurityChecks" in the name.
3. Select the "SecurityChecks" key, right-click anywhere in the right window and click "New",
select "DWORD".

UMC - Central User Management

154 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

4. Insert the "VerifySignature" name.

5. Right-click the "VerifySignature" key, select "Modify" and set the value of the key to "1".

Decommisioning UMC machines

If a UMC installation is no longer required, the computer should be removed from server to
reduce the entry points for an attack.
To remove a UMC computer from service, see "AUTOHOTSPOT".

5.3.3.2 Allowlisting

UMC has been tested with McAfee Application Control 6.1.3 as an allowlisting application. For
the management of McAfee Application Control, there are different options:
• Locally on a computer system (standalone)
• Centralized use of McAfee ePolicy Orchestrator (ePO)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 155
UMC security concept
5.3 Security implementation

UMC has been tested with a local administration configuration that can only be operated
via the command line. The commands are understandable and self-explanatory, and McAfee
provides excellent reference material. McAfee Application Control can be managed easily
with batch files or scripts.
In either case, after the installation of McAfee Application Control on the computer, you must
first run the Solidify function on all local disks and partitions, which checks all connected
drives for the presence of executable files. After execution of the Solidify function:
• Only the found programs can be executed in the future
• All executable files found during the check are protected from manipulation (renaming,
deletion, etc.) and new files cannot be executed
The duration of the execution of the solidify function depends on the amount of data and
the computing power and can be several hours.

Executing McAfee Solidify function

During the integration of McAfee Application Control or prior to the installation, you should
follow the following instructions below. This procedure allows all components that are signed
with the selected certificates to make changes to the binaries on the system and start new
applications.

Requirements
You must have the Siemens certificate that is connected to the binary files (for
example, .exe, .dll) that are installed by the UMC installer in the "bin" folder. If you have not yet
retrieved the Siemens certificate, read the section "Obtaining the Siemens certificate".

Procedure
1. Install and configure the operating system.
2. Install all required programs and components.
3. Install all security updates that are available for the operating system and programs.
4. Install a virus scanner and update it with the latest virus signature files.
5. Set up the system architecture to minimize the risks from malware before and during the
integration of McAfee Application Control.
6. You should disconnect the computer from external/foreign networks (e.g. at the front-end
firewall).
7. Run a full virus scan on the computer.
8. Install McAfee Application Control locally.
9. Open the McAfee Application Control command line ("Start > Programs > McAfee > Solidifier
> McAfee Solidifier Command Line").
10.Start the solidification by entering the "sadmin solidify" or "sadminso" command and wait
until the process is completed.

UMC - Central User Management

156 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

11.Add the Siemens UMC certificate as an updater with the "sadmin cert add -u "certificate""
command.
12.Enable the configuration by typing "sadmin enable" (McAfee Solidifier Control is enabled
when the computer is restarted).

Result
All partitions and local disks of the computer system are now scanned for the presence of
executable files (applications), for example, exe, com, bat, dll, as well as Java, ActiveX controls
and scripts. McAfee Application Control then signs and authorizes all files found during the scan
for future use. It also protects the files from manipulations such as deletion and renaming. After
successful completion of the "Solidification", the Solidifier command line reports the number of
scanned files per partition or disk, including the number of files that have been authorized. After
the restart, you can query the status of McAfee Solidifier by entering the "sadmin status"
command in the Solidifier command line.

Retrieving Siemens certificate

All binaries (e.g. exe, .dll), which are installed by the UMC installer in the "bin" folder, are
connected to the Siemens certificate. You can retrieve the certificate from one of these files by
using the following procedure.
1. Select an .exe file (or another binary file) in the "bin" folder of the User Management
Component.
2. Right-click and select "Properties".
3. Select the "Digital signatures" tab.
4. Select the "SIEMENS" certificate and click the "Details" button.
5. Click the "View certificate" button and select the "Details" field.
6. Click the "Copy to file" button and select the "Base-64 encoded X.509 (. CER)" option.
7. Save the file to ".. \Program Files\McAfee\Solidcore\Certificates".

5.3.3.3 Disaster recovery

If a security incident, such as a malware infection or if a storage medium fails (hard disk crash),
the regular creation of backups is essential to ensure that the automation system is cleaned up
and that smooth and trouble-free operation is restored as quickly as possible.

System backup
A system backup stores data in the system partition. In the case of UMC, this is necessary to store
system data related to UMC, such as certificates and allowlisting.
This means that the data storage medium is backed up with the following data:
• hardware-specific files (for example, "Ntldr", "Boot.ini")
• Windows operating system files

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 157
UMC security concept
5.3 Security implementation

• The installation of the operating system

• The installation of all programs
The UMC database can be backed up by executing an export package that stores UMC data.

Note
The database backup is related to the disaster recovery strategies. The prevention of data loss
cannot be ensured and depends strictly on the backup strategy (for example, the selected
interval for creating backups).

5.3.3.4 Security controller

The Security Controller (SeCon) is a program that is integrated into the installation of the User
Management Component by default and configures application-specific security settings during
installation.
SeCon can automatically configure the following settings:
• Group settings
• Settings in the Windows Registry database
• Windows firewall exceptions
• DCOM settings
• File and/or directory permission settings
The configuration of these settings depends on the installation (package selection).

Security settings related to the UMC package

The settings required for UMC are group settings and file and/or directory permissions. Before
the UMC Setup program performs the installation, the Security Controller dialog box appears,
which displays the system settings to be made by the setup on the PC station. Group settings and
file and/or directory permissions can be found at the following link: Configuring Windows
groups. (Page 161) The security controller can also be accessed via "Windows Apps" under
"Siemens Automation" and "Security Controller".

Note
When changing the system configuration or the roles of the users, it must be noted that the
memberships in local groups must be adjusted accordingly. If the working environment is
changed, the settings must be made again.

5.3.3.5 Patch management

Generally, office PC systems are protected against malware, and vulnerabilities identified in the
operating system or user software must be eliminated by installing updates and patches.
Likewise, industrial PCs and PC-based control systems in a plant network require equivalent
protective measures.

UMC - Central User Management

158 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

The systems should be regularly updated and patched to mitigate potential security risks
and eliminate known security vulnerabilities. To achieve this, Microsoft fixes security
vulnerabilities in its products and makes these fixes available to its customers in the form
of official updates/patches.
Installation of patches is recommended to make operation of the UMC solution more secure
and stable. Siemens provides support to customers only if these updates have been installed
and only for problems not addressed by these updates.

5.3.3.6 Malware detection and prevention

This section deals with the protection of the automation system or the computers of the
automation system against malware. Malicious software and malicious programs (malware)
refer to computer programs designed to perform unwanted and potentially harmful functions.
The following types are distinguished:
• Computer viruses
• Computer worms
• Trojans
• and other potentially dangerous programs, for example:
– Rear doors
– Spyware
– Adware
– Scareware
– Grayware
A virus scanner or antivirus program is a software that detects, blocks, and, if necessary,
removes malware.
The use of a virus scanner on the computers of an automation system must not impair the
process operation of a plant. The following two examples illustrate the problems that can
arise in an automation system when using a virus scanner:
• A computer must not be shut down by a virus scanner even if it is infected with malware if
this would lead to a loss of control over the production system (e.g. in the case of an OS
server).
• A project file that is "infected" with malware (e.g. a database archive) must not be
automatically quarantined, locked or deleted.
The virus scanner server is a computer that centrally manages the virus scan clients, loads
virus signature files (virus patterns) from the manufacturer of the virus scanner over the
Internet and distributes them to the virus scan clients. The virus scan client is a computer
that is checked for malware and managed by the virus scanner server. According to the rules
for splitting components into security cells, the virus scanner server must be singled out
on a separate network (perimeter network/DMZ). Although there are currently no known
compatibility issues, UMC only supports Trend Micro OfficeScan 10.6.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 159
UMC security concept
5.3 Security implementation

Virus scanner - Configuration example

In the configuration example (see Example configuration with security cells (Page 146)), the
virus scanner is located in the perimeter security cell.

5.3.3.7 User account management

In the previous sections, it has been shown that a defense concept that confronts an attacker
with multiple hurdles (defense-in-depth concept) is required to defend against the various
threats and achieve an adequate level of protection. At the same time, however, this also means
that authorized personnel must be restricted by some hurdles. In practice, there are usually
different access rights or classes of rights. Certain users can only access certain parts of the
system, devices or applications. Some users are given administrator rights, while others are only
granted read or write rights.
The management of user and operator rights involves the assignment of rights in the
Windows environment (to run UMC modules, Windows users must be granted the rights
that belong to the corresponding UMC group) and the assignment of UM roles to users based
on activities. These procedures are strictly separated from each other, but both are strictly
applied according to the principle of minimum necessary rights.
The user accounts are managed by:
• Assignment of the least privileges (Page 161)
• Configuration of Windows groups (Page 161)
• Authentication and authorization of operators (Page 162)
• Strength of passwords (Page 162)
• Physical protection (Page 163)

Default setting for the deletion of users

When UMC is provisioned, the configuration file "piisrv_config.json" is created in the folder
"ProgramData/Siemens/UserManagement/CONF".
By default, the "update_mode=noremove" value is set in the configuration file. The setting
prevents users from being deleted.
Therefore, keep in mind that when you remove a user from a group, that user is retained.
This user can still log in via UMC. If required, delete this user manually.
If UMC is to delete users by default, remove the "update_mode=noremove" value in the
"piisrv_config.json" configuration file.

UMC - Central User Management

160 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

Least privileges
UMC has a number of integrated UM roles:
• The UM role "Administrator" is assigned to the integrated root administrator. It is used to
grant full rights to a specific user. Use this UM role for installation and disaster recovery
purposes only. Also, use strict password policies for users who are connected to this UM role
and revoke this UM role when it is not required. This UM role cannot be assigned to a UM
group. This UM role cannot be deleted and only UM users with the UM role "Administrator"
can change other UM users with this UM role.
• The UM role "UMC admin" is used to manage UMC users, UMC groups, and all other UMC
units.
• The UMC role "UMC viewer" is used to access the configuration of the user management
without making any changes.
The lowest permissions should be used for management of UMC functions via user accounts
for the purpose of performing administrative operations. To follow this principle, you could,
for example, assign a specific UMC user to the "UP Service" service.

Windows group configuration

The role-based access control strategy involves restricting the minimum required rights and
functions for users, operators, devices, network and software components.
According to Microsoft's recommended decentralized management of users in groups of
the ALP principle (add user account to local group and assign permission), local users must
first be divided into groups so that these groups can be assigned the necessary permissions
(folders, enables, etc.).
If the management is carried out centrally from a domain, the AGLP principle (Access Global
Local Permission) should be followed. According to this principle, user accounts are initially
assigned to the domain global groups in Active Directory. These groups are then assigned to
local computer groups, which in turn receive permissions for the objects.
The creation of UMC Windows groups and the configuration of file permissions take place
automatically during the UMC setup.
To check that all required configurations have been made, see below.

Local UMC Windows groups

The User Management Component must have specific local Windows groups on the computers
on which it runs.
The purpose of these local Windows groups is to:
• Manage file system permissions for UMC folders
• Manage permissions for other Windows resources of the lower level (kernel objects)
This way, when specific Windows users need to interact with UMC folders or other protected
resources, they can be assigned to the appropriate local Windows groups instead of having to

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 161
UMC security concept
5.3 Security implementation

manually configure access rights for each individual user. The following table contains all the
details about the local Windows groups used by UMC.

Name Description Main areas of application

Administrator This group contains the local ad‐ Configuration of UMC
ministrators of the computer and
must be used to configure UMC.
UM service accounts This group is intended for the op‐ Identities used to run services
eration of um services. This
group has access to the content
of incoming folders, see File sys‐
tem (Page 151) for the list of fold‐
ers created by the setup and their
access rights.
Members of this group should
not be configured as interactive
users for security reasons.
UM_USERS For future use. For future use.

Operator authentication and authorization

Systems or people who need to access the functionalities require authentication and
authorization. Authentication means that the system checks the identity of the external system
or the user who wants to access certain functions. In the case of users, the typical login
credentials are username and password. Users access the system by providing their login
credentials. If the authentication is successful, the user is granted access. This process is not to
be confused with authorization, which determines the actions that authenticated users/systems
can perform in the system. A typical way to implement authorization is to define groups and roles
that summarize a user's rights to system resources.

Password strength
The following general recommendations should be followed:
• Keep the default values for password account policies or make them more restrictive.
• Force users to change the password at first login if the password assigned to a new user does
not comply with the password account policies
• Force users to change the password if the password has been reset and does not comply with
the password account policies

UMC - Central User Management

162 Programming and Operating Manual, 11/2023, A5E52954435-AA
 UMC security concept
5.3 Security implementation

We strongly recommend that you follow your organization's password policies to ensure the
strength of the password for the administrator. For example, a password policy may require
that your password meet the following requirements:
• Length of at least 8 characters
• Contains characters from three of the following four categories:
– Uppercase letters of European languages (A to Z, characters with diacritical marks, Greek
and Cyrillic characters).
– Lowercase letters of European languages (a to z, sharp s, characters with diacritical marks,
Greek and Cyrillic characters).
– Decimal numbers (0 to 9)
– Non-alphanumeric characters: ~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/
If a user is created as an administrator and the command is executed via a script, a warning
should be added with the recommendation that a password should be entered according to
the password policy of your company.
In addition, UMC provides the following default values for global user account policies:

Field Description Default values

SL_PWD_MIN_LEN Minimum length of the password 8
(number of characters)
SL_PWD_MAX_LEN Maximum length of the pass‐ 120
word (number of characters)
SL_PWD_MIN_LOW_CHAR Minimum number of lowercase 1
letters in the password
SL_PWD_MIN_UP_CHAR Minimum number of uppercase 1
letters in the password
SL_PWD_MIN_ALPHA_CHAR Minimum number of alphanu‐ 1
meric characters in the password
SL_PWD_MIN_NUM_CHAR Minimum number of numeric 1
characters in the password
SL_PWD_MIN_OTHER_CHAR Minimum number of special char‐ 0
acters in the password

Physical protection
To ensure the security of UMC, the target system on which the UMC server is running must be
configured correctly. The following conditions in particular are mandatory:
• Physical access to UMC servers must be prevented
• The administrator account may only be used for administrative tasks
• Use a special user account for the UM server launcher (this user account must belong to the
Windows group "UM service accounts" created during the UMC setup).
• Avoid changing the files directly in the folders used by the UM server. The data can only be
changed using the tools provided by UMC:
– %ProgramData%\Siemens\UserManagement\CONF
– %ProgramData%\Siemens\UserManagement\CERT

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 163
UMC security concept
5.3 Security implementation

5.3.3.8 UMC Web UI redirect validation

When a login request is made, the UMC Web UI sends a parameter to the identity provider whose
value is the address to which the browser is redirected. To prevent the browser from being
redirected to malicious websites, plausibility checks have been introduced for this parameter
format and content.
These controls monitor:
The structure of the parameter (which is to be written as follows: https://hostname:port/
path). This check is enabled by default and cannot be disabled.
The hostname included in the redirect parameter must match the hostname used in the
network request. This check is disabled by default, but can be enabled using the following
procedure.

Activation of check of the Redirect URL

Manually add a registry key named "ctx_host_check" under the registry path
"HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User Management\WebUI\Settings". This registry
key must be a DWORD variable that can have the following values:
• 0: The check is disabled
• 1: The check is enabled
For scenarios where UMC is installed behind a reverse proxy, follow these steps:
Add a registry key of type STRING named "reverseproxy" under the registry path
"HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User Management\WebUI\Settings". This must
contain the address of the reverse proxy used in the configuration (to be written as
follows: https://hostname:port). This address must be made available to UMC, because in
this scenario the address that comes with the network request is not the address of the
reverse proxy, but that of the internal computer, which of course does not match the redirect
parameter.

UMC - Central User Management

164 Programming and Operating Manual, 11/2023, A5E52954435-AA
References 6
6.1 UMCONF reference

6.1.1 UMCONF overview

The UMCONF utility can be used for the basic configuration of the User Management
Component (UMC). The steps of the basic configuration can be performed with the help of
guided interactive mode (recommended) or with various parameters. Various configuration
commands can also be executed depending on the selected options and parameters. Note that
running the utility without parameters is equivalent to running UMCONF in interactive mode
(umconf -i).
The UMCONF utility, which is distributed with UMC, is installed in the "\BIN"
subdirectory (for example, "C:\Program Files\Siemens\UserManagement\BIN") and must
be run from a command prompt in that directory or in the "C:\Program
Files\Siemens\UserManagement\WOW\BIN" folder. The execution of UMCONF is allowed for
the following users:
• Local users with administrator rights when User Account Control (UAC) is enabled
• UM users belonging to the UM group "um_config"

Note
• Use the UMCONF utility with caution. Incorrect use may result in the system becoming
unavailable.
• Close all applications that use UMC before starting UMCONF and making changes to the
computer configuration.

Basic configuration of UMC

The basic configuration consists of the following steps:
• Create the UM domain
• Create the UM user with the UM role "Administrator"
• Specify the local user assigned to the service "UMC Service". This user must either be a
member of the "UM Service Accounts" UM group or have administrator rights.
• Specify the local user with Active Directory access rights who is assigned to the "UP Service"
service.
This step is mandatory if Active Directory is used.
If you are creating a standalone domain, this option is not enabled.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 165
References
6.1 UMCONF reference

After the initial installation, the above configuration steps must be performed in order to run
UMC on a computer that becomes a UMC ring server after configuration.

Note
To perform the configuration steps, it is highly recommended that you run the "umconf -i"
command to perform all configuration steps.

Configuration options
The following options are supported:
• New configuration: UMC is being configured for the first time.
• Overwrite an existing configuration: You have already configured UMC and want to change
the configuration.
• Upgrade an existing configuration from a previous version: You have already configured
UMC, installed a newer version of UMC and need to upgrade the configuration.
When the UMCONF utility is run interactively, the various options are offered.

6.1.2 Overview of UMCONF commands

6.1.2.1 View help

You can use this command to view a brief overview of the commands with their parameters and
switches.

Syntax
umconf -h

6.1.3 Creating UM objects

6.1.3.1 Create UM domain

You can use this command to create a UM domain that is designated with the input parameter
if no UM domain exists. If a UM domain has already been defined, it can be overwritten with the
parameter "-f". If working in a decentralized environment with an active firewall, the incoming
and outgoing connections must be allowed through port 4002. The command also creates the
private claim key, which is necessary for the proper functioning of the system.

Note
Set up a secure LDAP connection for provisioning services

UMC - Central User Management

166 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Syntax
umconf -c -d name [-e] [-f]

Parameters
• name: String that represents the name of the UM domain. Only alphanumeric characters are
allowed.

Optional parameters

Parameter Description
-e Specifies the number of days until the network certificate expires.
The default validity is 10 years.
-f Forces the creation of a new UM domain. If a UM domain with the same name
exists, it is overwritten.

Examples
umconf -c -d mydomain
Creates a UM domain "mydomain".
umconf -c -d mydomain -e 7300
Creates a UM domain "mydomain" whose network certificate expires after 7300 days.

6.1.3.2 Creating administrator

Note
With UMCONF, only one UM user with the UM role "Administrator" can be created and neither
user nor password can be changed.
The password can be changed with the UMX utility or via the UMC Web UI.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 167
References
6.1 UMCONF reference

General recommendations
It is highly recommended that you adhere to the password policies of your organization to
ensure the strength of the password for the administrator. For example, a password policy may
require your password to meet the following requirements:
• At least 8 characters long.
• Must contain characters from three of the following four categories:
– Uppercase letters of European languages (A to Z, characters with diacritical marks, Greek
and Cyrillic characters).
– Lowercase letters of European languages (a to z, sharp s, characters with diacritical marks,
Greek and Cyrillic characters).
– Decimal numbers (0 to 9).
– Non-alphanumeric characters: ~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/
If a user is created as an administrator and the command is executed via a script, a warning
should be added with the recommendation that a password should be entered according to
the password policy of your organization.

Syntax
umconf -c -u name -p password

Parameters
• name: String that represents the user name. Only alphanumeric characters and the special
character '_' are allowed.
• password: Password assigned to the user. A blank password is not accepted.

Example #1
umconf -c –u administrator -p 123

6.1.3.3 Create claim key

You can use this command to create a new claim private key and generate the corresponding
public key. The new private claim key becomes the current key used by the identity provider to
sign the claims provided to the relying parties. It can only be executed on a primary ring server.
This command cannot be executed on a master ring server that is running in safe mode (write
protection enabled).
The public key for the claim is stored in "%programdata%
\Siemens\UserManagement\CERT\CLAIM" under the file name "key.pub". The key can be

UMC - Central User Management

168 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

exported. When a domain is created, a claim key is created that overwrites the existing claim
key. The applications of the relying party must be updated with the new key if necessary.

Note
In a decentralized environment, after creating a new claim key on one UMC master ring
server/UMC server, the "UMC Service" service of the other UMC ring server/UMC server must be
manually restarted to match the keys.

Syntax
umconf -c -k

6.1.4 Managing UM services

6.1.4.1 Assign Windows user to the "UP Service" service

You can use this command to assign the Windows user designated with parameter "name" to the
"UP Service" service. To assign the Windows user to the service, the password must be specified
as an input parameter.
This Windows user must have the following rights:
• Active Directory access rights
• Write access to the UMC folder "C:\ProgramData\Siemens\UserManagement\CONF" or
alternatively membership in the Windows group "UM Service Accounts"
This command also creates the
registry key "HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User
Management\WebUI\Settings\domains_support" and sets it to "yes". This enables the import
functions for users and groups via the UMC Web UI.

Note
To disable the AD provisioning, the value for the registry key
"HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User
Management\WebUI\Settings\domains_support" must be set to "no" and the "UP Service" service
stopped.

Syntax
umconf -P -u name -p password [-f]

Parameters
• name: String that represents the user name, preceded by a domain.
• password: Password assigned to the user.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 169
References
6.1 UMCONF reference

Optional parameters

Parameter Description
-f If the "UP Service" service is running and is already configured, this parameter allows
you to overwrite the existing configuration.

6.1.4.2 Assign user to the "UMC Service" service

You can use this command to assign the Windows user designated with parameter "name" to the
"UMC Service" service. To assign the Windows user to the service, the password must be
specified as an input parameter. This user must either be included in the "UM Service Accounts"
group or have administrator rights. If an integrated local Windows user is to be assigned, the
configuration tool for Windows services must be used.

Note
The user assigned to the "UMC Service" service may only be changed via UMCONF.

Syntax
umconf -s -u name -p password [-f]

Parameters
• name: String that represents the user name, preceded by a domain. For a local user, the name
must be preceded by the string ".\" or "machinename\".
Example: .\administrator, mydomain\myuser
• password: Password assigned to the user. If the virtual account "NT SERVICE\UMC Service" is
specified, no password is requested.

Optional parameters

Parameter Description
-f If the services are running and are already configured, this parameter allows the
existing configuration to be overwritten.

6.1.4.3 Set secure LDAP connection for the "UP Service" service
You can use this command to set the entry "ldaps" in the configuration file
(C:\ProgramData\Siemens\UserManagement\CONF\piisrv_config.json).
You can also change the configuration file manually:
json
{
"ldaps": "yes|no",
}

UMC - Central User Management

170 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Note that the command will fail if the configuration file does not exist.
The "UP Service" must be restarted after execution of the command in order for the new
setting to take effect.
This setting is not passed to other UMC servers, the command only changes the local
configuration file.

Syntax
umconf -P -ldaps <1|0> [-f]

Parameters
• -ldaps: Enables or disables the LDAPS connection with AD. The parameter is mandatory; it
is case sensitive.
Possible values:
– 1: Enables LDAPS. Converted to "yes" in the configuration file.
– 0: Disables LDAPS (LDAP is used instead). Converted to "no" in the configuration file.

Optional parameters

Parameter Description
-f If the "UP Service" service is running and is already configured, this parameter allows
the service to be restarted.

Examples
umconf -P -ldaps 1
Forces the provisioning server to use an LDAPS connection to AD. The "UP Service" is not
restarted.
umconf -P -ldaps 0 -f
Forces the provisioning server to use an LDAP connection to AD. The "UP Service" is restarted.

6.1.4.4 Query and change GUM port

If the receiving port of GUM (Global User Management) is in use during creation of a domain, the
GUM functionality and the "um.sso" service that is responsible for DSSO is not available.
Following successful creation of the domain, UMCONF displays a warning if the service cannot
be started because the port is not available. The current port setting (default setting is port
6006) can be queried and changed. Use the following two commands for this.

getgumport
umconf -getgumport

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 171
References
6.1 UMCONF reference

setgumport
umconf -setgumport -p <portNr>
Once you have changed the port to an available port, the service starts
immediately. You must, however, update the IIS so that it uses the new port
for GUM. For this reason, you should run the batch files for removing and
adding the IdP configuration after changing the port. The two batch files are
located by default in "C:\Program Files\Siemens\UserManagement\BIN" under the names
"REMOVE_IdP_WebUI_configuration.bat" and "IdP_WebUI_configurator.bat".

6.1.5 Execute binding/unbinding commands

6.1.5.1 Attach UMC agent

You can use this command to join a computer to a UMC domain. The computer is then classified
in the role of UMC Agent. All parameters of the command are optional. If a parameter is not
inserted when the command is started, you will be prompted to enter it. The "serviceUserName"
and "servicePassword" parameters are an exception to this behavior. If nothing is entered, the
built-in Windows user "Local System" is preset.
The command also installs the network and device certificates on your computer. If there
is an active firewall, the incoming and outgoing connections must be allowed through port
4002.

Syntax
umconf -a [-f] [-c computerName] [-u userName] [-p password] [-s
serviceUserName servicePassword] [-v] [-fp fingerprint] [-t]

Parameters
• computerName: Name of a UMC ring server or UMC server of a domain to which you want
to establish the connection. Both the NetBIOS name and the FQDN name can be used.
• userName: Name of a UM user with the UM function right "UM_ATTACH" or the UM role
"Administrator".
• password: Password of the UM user assigned to parameter "userName". If the "-t"
parameter is present, "password" is a ticket generated for this user.
• serviceUserName: Name of a local Windows/domain user (who either belongs to the "UM
service accounts" group or has administrator rights) who is to be assigned to the UMC
services. The "serviceUserName" parameter may remain empty (the password must then also
remain empty). The "UMC Service" service can thus be executed as a LocalSystem user.
• servicePassword: Password of the Windows user assigned to parameter
"serviceUserName".
• fingerprint: Fingerprint of the UMC domain. See Retrieve fingerprint (Page 175).

UMC - Central User Management

172 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Optional parameters

Parameter Description
-f If the computer is already configured, the existing configuration is overwritten.
-v If this parameter is present, the certificates are not installed interactively. The "-v"
parameter must be present if the fingerprint is specified.
-t If this parameter is present, a ticket generated for the user must be provided instead
of the password.

6.1.5.2 Join UMC server

You can use this command to classify a computer as a UMC server or UMC ring server. If the
computer has not yet been joined to the UM domain, it is joined with this command. All
parameters of the command are optional. If a parameter is not inserted when the command is
started, you will be prompted to enter it.
The "serviceUserName" and "servicePassword" parameters are an exception to this behavior:
If nothing is entered, the built-in Windows user "Local system" is preset.
This command installs:
• the network and device certificates on your computer
• the ticket and claim keys
If there is an active firewall, the incoming and outgoing connections must be allowed via the
ports 4002 and 4004.

Note
If you have configured AD provisioning on the primary UMC ring server, the service must also
have been installed on the computer that you want to join. To exclude the configuration for AD
provisioning, see the description of the "-b" parameter below. If this command is to be used via
a script, the "-b" parameter must be used and the "umconf" command must be used for the
configuration of the "UP Service" service in order to link the AD Windows user to the service.

Syntax
umconf -j [-f] [-m serverType] [-c computerName] [-u userName] [-p
password] [-s serviceUserName servicePassword] [-v][-b] [-fp
fingerprint] [-t]

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 173
References
6.1 UMCONF reference

Parameters
• serverType: Type of server to be connected to the ring:
– 0: The computer becomes a UMC server, in which case the "UP Service" is not configured.
– 1: The computer becomes a UMC ring server.
– 2: The computer becomes a UMC runtime server, in which case the "UP Service" is not
configured. The UM ring servers of the domain must be version UMC 2.9 SP3 or higher.
You can find additional information in the section "Computer roles (Page 18)".
• computerName: Name of one of the UMC ring servers of the domain to which the
connection is to be made. Both the NetBIOS name and the fully qualified domain name
(FQDN) can be used.
• userName: Name of a UM user with the UM function right "UM_RINGMNG" (for creating a
UMC ring server) or "UM_JOIN" (for creating a UMC server) or with the UM role
"Administrator". For more details, see UM function rights (Page 17).
• password: Password of the UM user assigned to parameter "userName". If the "-t"
parameter is present, "password" is a ticket generated for this user.
• serviceUserName: Name of a local Windows/domain user (who either belongs to the "UM
service accounts" group or has administrative rights) to be assigned to the UM services. The
"serviceUserName" parameter may remain empty (the password must then also remain
empty). The "UMC Service" service can thus be executed as a LocalSystem user.
• servicePassword: Password of the Windows user assigned to parameter
"serviceUserName".
• fingerprint: Fingerprint of the UMC domain.

Optional parameters

Parameter Description
-f Forces a stop and restart of the "UMC Service".
-m Specifies the type of server to be connected to the ring:
• 0: UMC server
• 1: UMC ring server
• 2: UMC runtime server
-v If this parameter is present, the certificates are not installed interactively. The "-v"
parameter must be present if the fingerprint is specified.
-fp If the "-v" and "-fp" parameters are present, the specified fingerprint is used for
validation.
-b The configuration of the Active Directory provisioning is not performed. The pa‐
rameter is relevant only for the configuration of the UMC ring server. The "UP Serv‐
ice" service is never configured for a UMC server.
-t If the "-t" parameter is present, a ticket generated for the user must be specified
instead of the password.

UMC - Central User Management

174 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

6.1.5.3 Unjoin server

You can use this command to demote a computer from the role of UMC ring server or UMC server
to the role of UMC agent. The "userName" and "password" parameters of the command are
optional. If the parameters are not inserted when you start the command, you will be prompted
to enter them. If you do not include the "computerName" parameter, the command is executed
by default for the computer on which you start it. If the connection of a primary UMC ring server
is disconnected, the system dynamically selects a new primary UMC ring server.
If there is an active firewall, the incoming and outgoing connections must be allowed via the
port 4002.

Note
If this procedure is carried out via remote access ("computerName" parameter is present) for a
device that is disconnected from the network and the device is reconnected to the network after
some time, the UMC configuration must be deleted before reconnecting this computer.

Syntax
umconf -u [-u userName] [-p password] [-c computerName] [-f]

Parameters
• userName: Name of a UM user with the UM function right "UM_RESETJOIN" or with the UM
role "UM administrator".
• password: Password of the UM user assigned to parameter "userName" or a ticket generated
for this user.
• computerName: NetBIOS name of the computer with the role as UMC ring server or UMC
server whose connection is to be disconnected. This parameter is to be used only if the UMC
services of the device on which you are executing the command cannot communicate with
the UMC services of the device whose connection you want to disconnect. This is the case,
for example, if the device that is to be disconnected is no longer available.

Optional parameters

Parameter Description
-f Forces a stop of the "UMC Service" service.

6.1.5.4 Retrieve fingerprint

You can use this command to retrieve the fingerprint (NETID) of the UMC domain from the
specified computer. To obtain the fingerprint from a configured computer for a computer that
has not yet been configured, the "[-c computerName]" parameter can be used. If you do not
specify the computer name, the fingerprint is retrieved locally.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 175
References
6.1 UMCONF reference

Syntax
umconf -fingerprint [-c computerName]

Parameters
• computerName: Name of the computer from which you want to obtain the fingerprint. Both
the NetBIOS and FQDN names can be used for a remote computer.

6.1.6 Managing central configurations

6.1.6.1 Retrieve default configuration file

You can use this command to retrieve the default configuration file in JSON format. The file can
be used as a template from which you can copy the keys for the values to be set in the local or
central configuration.

Syntax
umconf -getdefaultconfig -file fullpath

Parameters
• fullpath: Path and name of the file where the default configuration is to be saved.

6.1.6.2 Set up central configuration

You can use this command to set the specified file as the central configuration file. The
configuration file has a specific version, which is incremented each time a set operation is
executed. Before setting a configuration, you must execute a GET operation to query the latest
version.

Syntax
umconf -setconfig -u username -p password -file fullpath [-label
labelName]

Parameters
• userName: Name of a UM user with the UM function right "UM_ADMIN" or the UM role
"Administrator".
• password: Password of the UM user assigned to parameter "userName". If the optional "-t"
parameter is present, the "password" parameter is a ticket generated for this user.
• fullpath: Full path of the JSON file with the UMC configuration to be set.
• labelName: Name of the configuration.

UMC - Central User Management

176 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Optional parameters

Parameter Description
-label (for future use) Optional, allows a label to be specified for each individual configu‐
ration.

6.1.6.3 Retrieve central configuration

You can use this command to retrieve the central configuration file that is currently in use and
save it to the specified file in the specified location.

Syntax
umconf -getconfig -file fullpath [-label labelName]

Parameters
• full_path: Full path of the file to be retrieved.
• labelName: Name of the configuration.

Optional parameters

Parameter Description
-label (for future use) Optional, allows a label to be specified for each individual configu‐
ration.

6.1.7 Upgrading UM objects

6.1.7.1 Upgrade UM domain

You can use this command to upgrade an existing UM domain. It can be run after the installation
of UMC on a device on which an earlier version was installed and configured.

Note
It is strongly recommended to execute the "umconf -i" command to perform all steps for
upgrading that involve upgrading for this UM domain.

Note
Renewing certificates
If the validity of the network or device certificates is about to expire, the command to upgrade
a UM domain triggers the automatic process for renewing the certificates.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 177
References
6.1 UMCONF reference

Syntax
umconf -U [-f]

Optional parameters

Parameter Description
-f Forces a stop of the "UMC Service" service.

6.1.8 Deleting UMC configuration

6.1.8.1 Delete UMC configuration

You can use this command to delete the UMC configuration and reset the system to the state
right after installation. The command must be executed if the UMC services have been stopped
manually or automatically with the -f parameter. After the execution of the command, the
"Reuse" action is required for the following application pools in IIS manager:
• Web UI pool (umc_pool for the configuration via script)
• Identity provider pool (SimaticLogonPool for the configuration via script)
If a UMC ring server or UMC server is to be removed from the UMC system, the device must
also be disconnected before the delete command is executed. See Unjoin server (Page 175).

Note
A restart of a "UMC service" service and/or the execution of the "Reuse" command in the
application pool can lead to an interruption of the service.

Syntax
umconf -D [-f]

Optional parameters

Parameter Description
-f Forces a stop of the UMC services before deletion of all data.

UMC - Central User Management

178 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

6.1.9 Managing allowlist entries

6.1.9.1 Create allowlist entry

You can use this command to add a host to the allowlist for the identity provider. The command
must be executed on the primary UMC ring server. By means of allowlisting, a list of hosts can
be maintained that have certain privileges. If a host is included in the list, it can perform the
following functions:
• Call IdP (validation of the service)
• Create an iFrame with an embedded IdP (validation of the iFrame)
If the host is not present in the list, the call will be rejected. When the service is validated, a
warning message is entered in the UMC event log and, if enabled, a message is also recorded
in the Identity Provider log file.

Syntax
umconf -c -w -d name

Parameters
• name: String that represents the host in the standard URL format. The string must specify the
exact path of the relying party. Options are:
– https://computername/UMC/slwapi/service
– https://computername.userdnsdomain/UMC/slwapi/service
Alternatively, the computer name can also be specified as IP address or localhost.

6.1.9.2 List allowlist entries

You can use this command to list the hosts in the identity provider's allowlist. The only default
value in the allowlist is the hostname of the computer. This value is added to the allowlist when
the UMC domain is created.

Syntax
umconf -l -w

Example
umconf -l -w

Result:
The allowlist contains the domains depending on the local IT configuration, e.g.:
localhost
myMachine

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 179
References
6.1 UMCONF reference

170.23.1.48

6.1.9.3 Remove allowlist entry

You can use this command to remove a host from the identity provider's allowlist.

Syntax
umconf -d -w -d name

Parameters
• name: String that represents the host in the standard URL format. Options are:
– localhost
– Name of the device (e.g. myMachine)
– Name of the domain (e.g. www.myDomain.net)
– IP address (e.g. 172.23.1.48)

Example
umconf -d -w -d 175.22.3.55

Result:
Domain 175.22.3.55 has been successfully removed from the allowlist.
The UMC service must be restarted for all pending changes to take effect.

6.1.10 Manage plugins

6.1.10.1 Register cookie adapter

You can use this command to register a cookie adapter. It can only be executed on a master ring
server.
After the execution of the command, a "Reuse" for the application pool of the identity
provider (SimaticLogonPool if configured via script) must be carried out in the IIS manager
for each computer on which the identity provider is installed.

Note
The execution of the "Reuse" command in the application pool can lead to an interruption of the
service.

UMC - Central User Management

180 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Syntax
umconf -r -u userName -p password -P url -d plugin_description -w -pk
public_key_path -sl securityLevel [-l languagefile]

Parameters
• userName: Name of a UM user with the UM function right "UM_ADMIN" or with the UM role
"Administrator".
• password: Password of the UM user assigned to parameter userName. If the "-t" switch is
present, "password" is a ticket generated for that user.
• url: URL of the cookie adapter to be registered.
• plugin_description: String that appears in the drop-down menu on the right of the Idp
login page on the client computer.
• public_key_path: The public key generated when setting up the cookie adapter.
• securityLevel: This information is transmitted in the IdP claim so that the third-party
application can determine the security level of the authentication. Possible values are:
– weak
– standard
– strong
• languagefile: Not used.

Optional parameters

Parameter Description
-w Specifies that you are registering a web adapter.
-pk Denotes a public key that is assigned to the plugin.

6.1.10.2 List registered plugins

You can only execute this command on a server. It creates a list of plugins registered on the
master ring server along with the following information:
• Plugin Uid: Unique ID of the plugin that is needed to enable the plugins on clients.
• Path: Path of the plugin
• Description: Description of the plugin
• Class: Specifies the type of plugin: Desktop, web, or hybrid.
• Pub keyid: Id of the public key
• Security level: "weak", "standard", "strong". See "Registering custom plugin" for more
information.
• Plugin Name: Unique name of the plugin. This field is left empty in plugins created before
UMC 1.9.1.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 181
References
6.1 UMCONF reference

• Use alias: Authentication with alias (enabled or disabled)

• Config data: Configuration data of the adapter

Syntax
umconf -l -P

Example
The umconf -l -P command lists the following registered plugins:

#1
Plugin Uid: 5a25fc03-3bd1-479b-9b02-2dcb9f6f60f3
Path: https://mymachine/tcss_web
Description: Teamcenter Web
Class: web
Pub keyid: 88FACEFCD6ED416BC6D516D10E09ABBBDA85FDC6
Security level: strong
Use alias: enabled
Plugin name: Teamcenter Web

#2
Plugin Uid: 113dc9ec-ada6-4f61-b938-9bf2a50b1401
Path: https://vm-chessa/tcss_hybrid
Description: Teamcenter Hybrid
Pub keyid: 88FACEFCD6ED416BC6D516D10E09ABBBDA85FDC6
Security level: strong
Use alias: enabled
Plugin name: Teamcenter Hybrid

6.1.10.3 Deregister plugin

You can use this command to delete the registration of a plugin on a master ring server.
After the execution of the command, a "Restore" for the application pool of the identity
provider (SimaticLogonPool if configured via script) must be carried out in the IIS manager
for each computer on which the identity provider is installed.

Note
Running the "Restore" command in the application pool can cause the service to be interrupted.

UMC - Central User Management

182 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Syntax
umconf -dP -u userName -p password -name pluginname [-P pluginId]

Parameters
• userName: Name of a UM user with the UM function right "UM_ADMIN" or with the UM role
"Administrator".
• password: Password of the UM user assigned to parameter "userName". If the "-t" switch is
present, "password" is a ticket generated for that user.
• pluginname: Name of the plugin, alternatively "pluginId" can be used.
• pluginId: Position of the plugin in the list of registered plugins. See example below.

Example
In the example in "List registered plugins (Page 181)", two registered plugins were listed using
the command umconf -l -P.
The command umconf -dP -u myUser -p 098P@ssword! -name Teamcenter
Hybrid removes the registration for the Teamcenter Hybrid plugin.

6.1.11 Managing log files

6.1.11.1 Archive log files

You can use this command to archive the folder containing system log files in a UMC package.
The UMC package is a UMC proprietary format that is zipped and encrypted. The exported
package is the input for the command to extract the log files.

Syntax
umconf -log -a -f file [-p password]

Parameters
• file: Path and name of the package file, for example "C:\temp\myLogs".
• password: Password for the package. If no password is entered, the user is prompted to
enter a password.

6.1.11.2 Extract log files

You can use this command to extract the system log files that were previously archived in a UMC
package. The UMC package is a UMC proprietary format that is zipped and encrypted. If the
password is not entered when you start the command, you will be prompted to enter it now. The
input password must match the password used for the "Archive log files" command.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 183
References
6.1 UMCONF reference

Syntax
umconf -log -e -f file [-p password]

Parameters
• file: Path and name of the package file, for example C:\temp\myLogs.
• password: Password for the package

6.1.12 Renewing certificates

You can use the following commands to update certificates that are created when a UMC agent
is attached or a UMC server is added as a node. The certificate is an x.509 certificate that allows
SSL communication between UMC computers.

Note
Network and device certificates can be automatically renewed when their expiration date
approaches. You can find additional information under Performing the automatic certificates
renewal (Page 91).

6.1.12.1 Renew certificate

You can use this command to extend the expiration date of the certificate of a UMC computer.
The renewed certificate has the same expiration date as the network certificate.

Note
If this operation is performed on a computer that is not a UMC ring server, the ring server will be
disconnected if the operation fails and must be reconnected to repeat the operation.

Syntax
umconf -rc [-f(orce)] [-c computername] [-u username] [-p password]
[-v] [-fp fingerprint]

Parameters
• computerName: If the computer for which a certificate renewal is requested is a UMC server,
then "computerName" is the name of the master UMC ring server to which the server
computer is connected and on which the certificate is located. Both the NetBIOS name and
the FQDN name can be used.
• userName: Name of a UM user with the UM function right "UM_ATTACH" or the UM role
"Administrator". See also UM function rights (Page 17).

UMC - Central User Management

184 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

• password: Password of the UM user assigned to parameter "userName".

• fingerprint: Fingerprint of the UMC domain.

Optional parameters

Parameter Description
-f Forces a stop of UMC services before renewal of the certificate.
-v If this parameter is present, the certificates are not installed interactively. The "-v"
parameter must be present if the fingerprint is specified.

6.1.12.2 Renew network certificates

This command extends the expiration date of the network and computer certificates of a primary
UMC ring server.

Note
If this operation is performed on a computer that is not the primary UMC ring server, the
operation will fail.

Syntax
umconf -rnc [-f(orce)]

Optional parameters

Parameter Description
-f Forces a stop of UMC services before renewal of the certificate.

See also
UM function rights (Page 17)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 185
References
6.1 UMCONF reference

6.1.13 Starting UMCONF in interactive mode

6.1.13.1 Start interactive operation

You can use this command to execute UMCONF in interactive mode. When starting interactive
operation, the following configuration steps are performed:
• Create UM domain
• Create the UM user with the UM role "Administrator"
The password for this UM user should be at least 8 characters long and contain characters
from three of the following four categories:
– Uppercase letters of European languages (A to Z, characters with diacritical marks, Greek
and Cyrillic characters).
– Lowercase letters of European languages (a to z, sharp s, characters with diacritical marks,
Greek and Cyrillic characters).
– Decimal numbers (0 to 9)
– Non-alphanumeric characters: ~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/
• Assign Windows users to the "UMC Service" service
If the virtual account "NT SERVICE\UMC Service" is specified, no password entry is required.
• Assign Windows user to the "UP Service" service
Required only if Active Directory is to be used.
• Create private claim key
The following options are supported:
• New configuration: The UMC is being configured for the first time.
• Overwrite an existing configuration: You have already configured the UMC and want to
change the configuration.
• Upgrade an existing configuration from a previous version: You have already configured the
UMC, installed a newer version of the UMC and need to upgrade the configuration.

Syntax
umconf -i
or alternative
umconf

UMC - Central User Management

186 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

6.1.14 Delete UM roles

6.1.14.1 Purge Role IDs

You can use this command to purge role IDs. Role IDs are generated in sequential order until the
maximum value of 32600 is reached. Once this value is reached, a new role (regardless of the
maximum number of roles) cannot be added until the roles that were previously deleted with
"Delete" are purged.

Note
This command stops the "UMC Service" service and restarts it after it has been executed. The
stop may cause an interruption of the service.

Syntax
umconf -purge -roles

6.1.15 Show Lists

6.1.15.1 Display server list

You can use this command to view the list of servers with their respective roles. Only computers
that have a role as UMC ring server or UMC server appear in the list. UMC runtime servers do not
appear in the list. The command can only be executed on a UMC server or UMC ring server.

Syntax
umconf -t

Example
umconf -t

Result
The server list contains:
servername: myname1 ring server
servername: myname2 ring server
servername: myname3 server

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 187
References
6.1 UMCONF reference

6.1.16 Enabling or disabling DSSO

You can use this command to enable or disable Desktop Single Sign-on (DSSO) functionality.

Syntax
umconf -dsso [enable|disable] [-f(orce)]

Optional parameters

Parameter Description
-f Forces a restart of the "UMC Secure Communication" service

Examples
umconf -dsso enable
The DSSO functionality is enabled. The "UMC Secure Communication" service must be
restarted manually.
umconf -dsso disable -f
The DSSO functionality is disabled. The "UMC Secure Communication" service is restarted.

6.1.17 Managing SLRA functionality

6.1.17.1 Manage SLRA functionality

You can use this command to manage the Simatic Logon Remote Authentication (SLRA)
functionality.
UMC is able to replace the server part of the SLRA interface provided by the Simatic Logon
component, so that any product using this component can connect to a UMC server without
modification.

Syntax
umconf -slra [enable|disable] [-secure <1|0>] [-localonly <1|0>] [-
certpath <certpath>] [-certname <certname>] [-certkeyname
<certkeyname>] [-f(orce)]

Parameters
• certpath: Full path of the certificate folder
• certname: Name of the certificate (CER file)
• certkeyname: Name of the certificate key (PEM file)

UMC - Central User Management

188 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

Optional parameters

Parameter Description
-secure Enables or disables TLS
-localonly Enables or disables remote connections
-f Forces a restart of the "UMC Service" service

Note
Certificates
If TLS is needed, create the certificates and save them in the default folder for "CERT/SLRAUTH"
certificates in "C:\ProgramData\Siemens\UserManagement".
The default folder for "CERT/SLRAUTH" certificates inherits the access rights of the parent "CERT"
folder. The authorizations for the folder may have to be changed.

Example
UMConf.exe -slra enable -secure 1 -localonly 0 -certpath
"C:\ProgramData\Siemens\UserManagement\CERT\SLRAUTH" -certname
"mycert.cer" -certkeyname "mycertkey.pem"

Result
SLRA functionality has been successfully enabled.
The "UMC Service" service must be restarted manually.

6.1.18 Managing GUM server list

6.1.18.1 Commands for the management of the GUM server list

A data record in the GUM server list has the following fields:
• URL
• Server that can be reached via this URL
• Fingerprint of the server device
An entry in the GUM server list is identified with the URL. The URL is not case-sensitive and
may only appear once in the list.
The GUM protocol supports a discovery command that provides a list of URLs. A client can
use one of these to call additional GUM commands.
To retrieve the URL list in the search result, the GUM server list is merged with the server list
of the current domain.
The search result contains only the URLs from the GUM server list whose server computer
(UMC ring or UMC server) exists in the server list of the current domain.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 189
References
6.1 UMCONF reference

Accordingly, as the server list does not contain any UMC runtime servers, the search result
includes only UMC ring servers or UMC servers.
The names of the servers (from the GUM server list and the server list of the current domain)
are not case-sensitive.

6.1.18.2 Create GUM list entry

You can use this command to create an entry in the GUM list. An entry in the GUM list must be
unique and is defined with the "url" parameter, which is not case-sensitive.
The URL is assigned to the server (also case-insensitive). The server name is used in the GUM
search to check the list of URLs available for the GUM protocol (by means of the server list). The
"fingerprint" parameter refers to the server computer in the list.
This command can be executed for UMC ring servers, UMC servers and UMC runtime servers.
The command fails if the master is not accessible.

Syntax
umconf -c -g -u url -s servername -fp fingerprint -n username -p
password [-t]

Parameters
• url: URL of the computer on which the GUM server runs. The URL is the unique identifier of
the entry in the list. There must not be two entries with the same URL in the GUM list (the
"umconf" command will fail in that case). The "url" parameter is not case-sensitive.
• servername: Host name of the computer to which the URL refers. The server name is used
in the GUM search to create a list of URLs supported by GUM, whereby a check is made to
determine which entry in the GUM list is also present in the UMC server list. For the purposes
of this check, the server name is not case-sensitive.
• fingerprint: SHA1 of the public key for the certificate for the HTTPS binding in IIS. UMC
provides a Powershell script for querying the fingerprint of the GUM server. If the server
certificate must be validated based on the infrastructure of the customer (valid CA), the
"fingerprint" parameter must be empty.
• username: Name of a UM user with the UM role "Administrator". See also UM function rights
(Page 17).
• password: Password of the UM user assigned to parameter "userName". If the parameter "-
t" is present, "password" is a ticket generated for this user.

Optional parameters

Parameter Description
-t If the "-t" parameter is present, a ticket generated for the user must be specified in
place of the password.

UMC - Central User Management

190 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.1 UMCONF reference

6.1.18.3 List GUM list entry

You can use this command to display the contents of the GUM list. It can be executed on UMC
ring servers, UMC servers and UMC runtime servers. The command can also be executed if the
master is not accessible.

Syntax
umconf -l -g

Example
umconf -l -g
The GUM list contains the following values:
url: https://srvname
server: srvname
fingerprint: FDD47C931853722CCD6595A404EA47476793A235

6.1.18.4 Remove GUM list entry

You can use this command to remove an entry from the GUM list. The entry is removed based
on the URL, which is the unique identifier of an entry in the list. The command can be executed
on UMC ring servers, UMC servers and UMC runtime servers. The command fails if the master
is not accessible.

Syntax
umconf -d -g -u url -n username -p password [-t]

Parameters
• url: URL of the GUM service. The URL is the unique identifier of the entry in the list. There
must not be two entries with the same URL in the GUM list (the "umconf" command will fail
in that case). The "url" parameter is not case-sensitive.
• username: Name of a UM user with the role "Administrator".
• password: Password of the UM user assigned to parameter "userName". If the switch "-t" is
present, "password" is a ticket generated for this user.

Optional parameters

Parameter Description
-t If the "-t" parameter is present, a ticket generated for the user must be specified
instead of the password.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 191
References
6.1 UMCONF reference

Example
umconf -d -g -u https://srvname
After execution of this command, the message appears: "gum list delete command
completed successfully"

6.1.19 Error codes

Value Description
0 Success
1 The user entering the command does not have the required administrator rights.
10 Initialization errors, such as missing registry keys
50 Syntax error of the command
100 Command execution error

UMC - Central User Management

192 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

6.2 UMX reference

6.2.1 UMX overview

The UMX utility can be used to manage UM users, UM groups, UM roles, and account policies of
the User Management Component (UMC). Various commands can be executed, depending on
the selected options and parameters. The description of the commands does not contain an
explicit description of the optional parameters if they uniquely identify the parameter they
precede.
This utility is distributed together with UMC, installed in the subdirectory "\BIN" (for example
"C:\Program Files\Siemens\UserManagement\BIN)" and must be executed from the command
line in this directory.
A UMX command can also be executed interactively. You can find more information in the
section "Interactive mode (Page 244)".

Note
Because the UMX utility works with command lines, a parameter with spaces that is to be
inserted must be enclosed in double quotation marks.

Users who are allowed to execute UMX commands

A UMX command can be executed using two login methods:
• Current user: The user who executes the UMC command is the Windows user who opened
the Windows command prompt.
• Specified user: The user who executes the UMC command is explicitly entered in the
command line. The "-x" parameter must be inserted as the first parameter when the
command is started. The second and third parameters are the user name and password.
Regardless of the login procedure used, the execution of the command is bound to the UM
function rights of the user. Examples:
• If the UM user has the UM function right "UM_ADMIN", he can execute all UMX commands.
• Users who have the UM function right "UM_VIEW" can only execute commands that access
the database with read permission only.
• Users who have the "UM_VIEW" UM function right and the UM function right for the
respective action can execute that action.
For a list of UM function rights, see chapter "UM function rights (Page 17)".
The following diagram illustrates the UMC object model, an understanding of which is useful
when working with the umx utility:

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 193
References
6.2 UMX reference

6.2.2 Viewing UMX information

6.2.2.1 View help

You can use this command to display the help for a specific command category. Command
categories are, for example, the creation or updating of objects.

Syntax
umx -h [command]

Parameters
command: Command category for which the help is to be displayed.

Examples
The following examples show the help calls for creating and updating objects:
umx -h -c
umx -h -U

UMC - Central User Management

194 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

6.2.3 Creating UMC objects

6.2.3.1 Create UM user

You can use this command to create a new UM user with the required parameters. To enable the
user parameter "override lock", you must first create the user and then update it.
See also: Update UM user (Page 198)

Syntax
Create user:
umx [-x commandUserName commandUserPassword] -c -u name -p password
[-f fullName] [-m paramMustPwd] [–C paramCanPwd] [–l paramLock] [-e
paramEnabled]
Create offline user:
umx [-x commandUserName commandUserPassword] -c -u name -off
Users created as "offline" are always enabled. See also "Offline users" in UM user (Page 14).

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• name: String that represents the user name. Only alphanumeric characters are allowed.
• fullName: String that represents the full user name, for example, last name and first name.
• password: String that represents the password of the user. Empty passwords are not
allowed. The password entered for the user with this command may not meet the password
policies. You can enable a password check to ensure that the password complies with the
policy.
See also: Change account policies - Enable password check (Page 243)
• paramMustPwd: Can have the values "0" or "1". If the parameter is set to "1", the user must
change his password when logging in for the first time. If the parameter is set to "0", the user
is not required to change his password when logging in for the first time. The default value
is "0".
• paramCanPwd: Can have the values "0" or "1". If the parameter is set to "1", the user can
change the password. If the parameter is set to "0", the user cannot change the password. The
default value is "0".

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 195
References
6.2 UMX reference

• paramLock: Can have the values "0" or "1". If the parameter is set to "1", the user is locked
and cannot perform any action. If the parameter is set to 0, the user is not locked and can
perform actions according to his UM function rights. The user can be locked by the system if
they try to log in with an incorrect password several times. The number of permitted attempts
is specified in the security policies. The default value is "0".
• paramEnabled: Can have the values "0" or "1". If the parameter is set to "0", the user cannot
perform any action. If the parameter is set to 1, the user is enabled and can perform actions
according to his UM function rights. The default value is "0".

Parameter behavior
The following table describes the behavior of the application depending on the values of the
"paramMustPwd" and "paramCanPwd parameters":

Value of "para‐ Value of "para‐ Behavior

mMustPwd" mCanPwd"
0 0 The user cannot change the password.
0 1 The user can change the password at any time.
1 0 The user must change the password when logging in for the
first time. After that, he/she can no longer change the pass‐
word.
1 1 The user must change the password when logging in for the
first time. After that, he/she can change the password again at
any time.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-off The specified user is created as an offline user.
See also: UM user (Page 14).

Examples
umx -c -u myUser -f "Peter Brown" -p default123 -m 1 -C 1 -l 0 -e 1
The user "myUser" is created with the full name "Peter Brown" and the password
"default123". The user must change the password when logging in for the first time, he
is not locked and is enabled.
umx –c –u DOM\userOFF –off
The offline user "DOM\userOFF" is created, all flags are set to "0".
umx –c –u userOn –p a
The online user "userOn" is created with the password "a", all flags are set to "0".

6.2.3.2 Create UM group

You can use this command to create a new UM group.

UMC - Central User Management

196 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

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

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• name: String that represents the group name. Only alphanumeric characters are allowed.
• description: String with a short description of the group. This field is optional when the
group is created offline.
If the group is created offline, the description can include an LDAP query that is used by the
"UP Service" service to search for the AD group and populate the UMC group with the users.
See also: UM group (Page 15)

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-d If the description begins with "{{Q=", the rest of the string is the LDAP query for the
group.
-off The specified group is created as an offline group.

Examples
Create offline group with an LDAP query:
umx -x manager manager -c -g UMC_domain\Group_test -d
{{Q=distinguishedname=cn=colors,ou=other_ou1,dc=umc_domain,dc=net
-off
In the example, an offline group is created with name "UMC_domain\Group_test". The
created group is assigned to the users of the AD group, who are queried with the execution
of the following command:
&(objectCategory=group)
(distinguishedname=cn=colors,ou=other_ou1,dc=umc_domain,dc=net))
It is recommended to use this mode only if a single group is returned as a result of the query,
as is the case when searching for a group with "distinguishedname", for example.

6.2.3.3 Create UM role

You can use this command to create a new UM role. A maximum of 36200 UM roles are allowed
in the system.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 197
References
6.2 UMX reference

In addition, there is a database restriction regarding the role identifiers. If an error message is
displayed that states that no more role identifiers are available for new UM roles, the existing
identifier must first be purged with the corresponding umconf command.
See also: Purge Role IDs (Page 187)

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

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• name: String that represents the role name. Only alphanumeric characters are allowed.
• description: String with a short description of the UM role.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.4 Updating UMC objects

6.2.4.1 Update UM user

You can use this command to update an existing UM user. Note that at least one of the UM user's
properties must be updated.
If a UM user that was imported into UMC from Active Directory or Windows is edited, there
are certain restrictions when updating. These can be found in this chapter in the "Restrictions
when updating imported users" section.

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] [-canchangepsw 0|1] [-mustchangepsw 0|1]

UMC - Central User Management

198 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• user: Represents the user name if "–s" parameter is present, or the internal user ID if "–s"
parameter is not present. The ID is a positive number that uniquely identifies the data record.
• expirationDate: Expiration date of the user account in UNIX time format.
• alertOnExDays: Number of days from which a warning appears to the UM user of the
imminent user account expiration.
• pwdDays: Number of days that the password is valid, max. 1828 days.
• alertOnPwdExDays: Number of days from which a warning appears to the UM user of the
imminent password expiration.
• autologoffMinutes: Number of minutes after which a UM user is automatically logged
out of the system (session-based).
• warningOnAutologoffMinutes: Number of minutes after which a warning appears to
the UM that he/she will be logged out of the system (session-based).
• language: User language in format "<langcode>- <countrycode>", for example "en-GB".
The two components have the following meaning:
– "langcode": Language code according to ISO 639. Two-digit codes (ISO 639-1) and three-
digit codes (ISO 639-2) are accepted.
– "countrycode": Country code according to ISO 3166.
• dataLanguage: Language in which the user data is displayed. The format is the same as for
the "language" parameter.
• fullname: Full name. It must be enclosed in double quotation marks if it contains spaces,
e.g. -fu "Full Name".
• comment: User comment: It must be enclosed in double quotation marks if it contains
spaces, e.g. -co "This User is Used Only For Test".
• emailAddress: Email address of the UM user.
• paramOverrideLock: Can have the values "0" or "1". If the parameter is set to "1", the UM
user cannot be locked. If the parameter is set to 0, the UM user can be locked.
Example: The UM user can be locked by the system if they try to log in multiple times with an
incorrect password. The number of attempts allowed is specified in the general security
policies for accounts. If the value is set to 1, a UM user will not be locked out, even if he/she
tries to log in with an incorrect password several times.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s After the "-u" parameter, the user name must be entered instead of the numeric user
ID.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 199
References
6.2 UMX reference

Restrictions on updating imported UM users

Users imported from Active Directory and local Windows users can be updated in UMX, but the
following restrictions apply:

UMX parameter UMC web name AD name UMC user Active Directory Windows local
expirationDat Expiration date of -/-
e the user
alertOnExDays Alarm when a user -/-
is about to expire
pwdDays Period of validity of -/-
the password
(days)
alertOnPwdExD Alarm when a pass‐ -/-
ays word is about to ex‐
pire
language Language -/-

dataLanguage User data language -/-

fullname Full name Common Name

comment Comment Description

-/- Initials Initials

emailAddress Email 1 Email

paramOverride Override policy for -/-

Lock lock in case of inva‐
lid login credentials
UMC attributes UMC attributes -/-
and their values and their values
User Alias User alias -/-

6.2.4.2 Update UM group

You can use this command to update an existing UM group. Note that at least one of the
properties of the UM group 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>] [-sadsstatus <1(empty)|2(sync)>]

UMC - Central User Management

200 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• group: Represents the name of the UM group if the "–s" parameter is present, or the internal
identifier if the "–s" parameter is not present. The ID is a positive number that uniquely
identifies the data record.
• description: String that contains a short description of the UM group.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s After the "-g" parameter, the UM group name must be entered instead of the ID.

6.2.4.3 Update UM user alias

You can use this command to update the alias of the specified UM user.

Syntax
umx [-x commandUserName commandUserPassword] -U -a -v aliasName -u
user [-s (use username instead of userId)]

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• aliasName: String that represents the alias name.
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record. You can query the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s After the "-u" parameter, the user name must be entered instead of the numeric user
ID.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 201
References
6.2 UMX reference

6.2.4.4 Update UMC user attribute

You can use this command to update the value of an existing attribute of a UM user. The user
attribute "USER_USNCHANGED" is used by the "UP Service" service for AD users. If the value is set
to "0", the user fields are synchronized with the AD fields.

Syntax
umx [-x commandUserName commandUserPassword] -U -A attributeName -v
attributeNewValue -u userId

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• attributeName: String that represents the attribute name.
• attributeNewValue: String that contains the new attribute value.
• userId: Positive number that represents the internal ID of the record that corresponds to
the UM user to whom the specified attribute and its value are assigned. You can query the
user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.5 Polling information about UMC objects

6.2.5.1 Create list with object details

You can use this command to list details about a selected object. These objects can be a UM user,
UM group or UM role. It can be used to query the identifier of an object from the object name.

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

UMC - Central User Management

202 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing
the command.
• user: Represents the user name if the "–s" parameter is present, or the internal user
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.
• group: Represents the group name if the "–s" parameter is present, or the group-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.
• role: Represents the role name if the "–s" parameter is present, or the role-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, the objects are identified with their internal identifier.

6.2.5.2 List event log records

You can use this command to create a list of records in the event log for a specific date, such as
the entire day starting at 00:01. The limit is set to 1001 data records per day. To retrieve all data
records for a day, the "-f" parameter must be used.

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

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• time: Date in Unix time format of the day whose data records are requested in the event log.
String now denotes the current date.
Example: The Unix time 1460939793 corresponds to ISO 8601: 2016-04-18T00:36:33Z

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 203
References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-f Forces the transfer of all data records of the relevant day to a file with the name
"<unixtime>.dat", which is stored in the location from which UMX is started.

Examples
Examples of commands:
umx –i –at now
umx –i –at 1450259593
umx –i –at 1460279589 -f
In the last example, UMX creates a file with the name 1460279589.dat with all data records
for Sunday, April 10, 2016 09:13:09 GMT
Example result:
---- 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

6.2.6 Displaying lists of UMC or Windows objects

6.2.6.1 Create list of objects

You can use this command to create a list of objects and store their details in the database,
depending on the selected parameter. For users, the attributes and their values are also
displayed.

Syntax
umx [-x commandUserName commandUserPassword] -l {-u [-v] | -wu | -du
searchStringUsers | -g | -dg searchStringGroups | -r | -f | -a | -d
domainName | -xc}

UMC - Central User Management

204 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• searchStringUsers: Filters the list of Active Directory users. The wildcard character "*"
is allowed and the search field is the user name.
• searchStringGroups: Filters the list of Active Directory groups. The wildcard character
"*" is allowed and the search field is the group name.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-u Displays the list of UM users.
-v If this parameter is present, additional details about the user are displayed.
-wu Shows the list of local Windows users.
-du Shows the list of Active Directory users belonging to the domain to which the local
computer is attached, filtered with the search string. The first field in the display is
used for import purposes. The name of the domain must be specified with the "-d
domainName" parameter.
-g Shows the list of UM groups.
-dg Shows the list of Active Directory groups belonging to the domain to which the local
computer is attached, filtered with the search string. The first field in the display is
used for import purposes. The name of the domain must be specified with the "-d
domainName" parameter.
-r Shows the list of UM roles.
-f Shows the list of UM function rights.
-a Shows the list of UM account policies. Note that the user assigned to the "UP Serv‐
ice" service is stored as account policy and shown in this list.
-d Shows the list of Windows domains.
-xc Displays the names and fingerprints of the registered clients of the station.

Example
umx -l -du ross*
Shows the list of Active Directory users belonging to the domain to which the local computer
is attached and whose user name starts with the string "ross".

6.2.6.2 Count objects

You can use this command to create a list of the number of the following objects stored in the
database:
• UM users
• UM roles

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 205
References
6.2 UMX reference

• UM groups
• UM function rights

Syntax
umx [-x commandUserName commandUserPassword] -k

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.7 Deleting UMC objects

6.2.7.1 Delete object

You can use this command to delete the object specified as input.

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing
the command.
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record.

UMC - Central User Management

206 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

• group: Represents the group name if the "–s" parameter is present, or the group-internal ID
if the "–s" parameter is not present. The ID is a positive number that uniquely identifies the
data record.
• role: Represents the role name if the "–s" parameter is present, or the role-internal ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-a All UM users, groups and roles are deleted, except for the user who initiates the
command and the UM users with the UM roles "Administrator" and "UMC Admin".
-s If the "-s" parameter is present, objects are identified with their name. If the "-s"
parameter is not present, objects are identified with their internal ID.
-f Forces the deletion of the user who initiates the command.

6.2.8 Executing binding/unbinding commands

6.2.8.1 Overview of binding/unbinding commands

The following commands can be used to perform binding or unbinding operations on UMC
objects, such as the following:
• Adding or removing UM users from a UM group or UM role
• Adding or removing user attributes
• Adding or removing UM function rights for a UM role

Binding commands
• Add attribute to a UM user (Page 208)
• Add attribute to a UM user - Size (Page 208)
• Add a set of attributes to a UM user (Page 209)
• Add alias name to a UM user (Page 210)
• Assign a UM group/UM role to a UM user (Page 210)
• Assign a UM role to a UM group (Page 211)
• Assigning a UM function right to a UM role (Page 212)

Unbinding commands
• Remove UM user from a UM group/UM role (Page 213)
• Remove UM role from a UM group (Page 213)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 207
References
6.2 UMX reference

• Remove attribute of a UM user (Page 214)

• Remove alias name of a UM user (Page 214)
• Remove UM function right from a UM role (Page 215)

6.2.8.2 Add attribute to a UM user

You can use this command to add an attribute with the appropriate value to a UM user.

Syntax
umx [-x commandUserName commandUserPassword] -a -A attributeName -v
attributeValue -u user [-s (use username instead of userId)]

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing
the command.
• attributeName: String that represents the attribute name.
• attributeValue: String that represents the attribute value.
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record. You can query the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, objects are identified with their internal ID.

6.2.8.3 Add attribute to a UM user - Size

This command adds an attribute of a specific size to a UM user. The attribute is assigned a default
value.

Syntax
umx [-x commandUserName commandUserPassword] -a –A attributeName -S
size -u user [-s (use username instead of userId)]

UMC - Central User Management

208 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing
the command.
• attributeName: String that represents the attribute name.
• size: Attribute size in bytes
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record. You can query the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If parameter "-s" is present, objects are identified with their name. If the "-s" param‐
eter is not present, objects are identified with their internal ID. The ID is a positive
number that uniquely identifies the data record.

6.2.8.4 Add a set of attributes to a UM user

This command adds a set of attributes of a specific size to a UM user. The attributes are assigned
a default value.

Syntax
umx [-x commandUserName commandUserPassword] -a –A namePrefix -n
number –S size -u user [-s (use username instead of userId)]

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• namePrefix: Prefix for the name of the attribute set.
• number: Number of attributes that are to be added.
• size: Attribute size in bytes
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record. You can query the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 209
References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, objects are identified with their internal ID.

Example
umx -a -A testAtt -n 10 -s 20 -u myUser
This command adds ten attributes for the UM user "myUser". The attributes have the names
"testAtt1", "testAtt2" and so on, each attribute has a size of 20 bytes.

6.2.8.5 Add alias name to a UM user

You can use the command to add an alias name to a UM user. Only one alias name per UM user
is supported.

Syntax
umx [-x commandUserName commandUserPassword] -a -a -v aliasName -u
user [-s (use username instead of userId)]

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing
the command.
• aliasName: String that represents the alias name.
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record. You can query the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, objects are identified with their internal ID.

6.2.8.6 Assign a UM group/UM role to a UM user

You can use this command to add a UM user to a UM group or to assign a UM role to a UM user.

UMC - Central User Management

210 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record.
• group: Represents the group name if the "–s" parameter is present, or the group-internal ID
if the "–s" parameter is not present. The ID is a positive number that uniquely identifies the
data record.
• role: Represents the role name if the "–s" parameter is present, or the role-internal ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, objects are identified with their internal ID.

6.2.8.7 Assign a UM role to a UM group

You can use this command to assign a UM role to a UM group.

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 211
References
6.2 UMX reference

• group: Represents the group name if the "–s" parameter is present, or the group-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.
• role: Represents the role name if the "–s" parameter is present, or the role-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, the objects are identified with their internal identifier.

6.2.8.8 Assigning a UM function right to a UM role

You can use this command to assign a UM function right to a UM role.

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• functionRightName: Name of a UM function right.
An overview of the UM function rights can be found here: UM function rights (Page 17)
• role: Represents the role name if the "–s" parameter is present, or the role-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, the objects are identified with their internal identifier.

UMC - Central User Management

212 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

6.2.8.9 Remove UM user from a UM group/UM role

You can use this command to remove a UM user from a group or to delete the assignment of a
UM role to a UM user.

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

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• user: Represents the user name if the "–s" parameter is present, or the internal user
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.
• group: Represents the group name if the "–s" parameter is present, or the group-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.
• role: Represents the role name if the "–s" parameter is present, or the role-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, the objects are identified with their internal identifier.

6.2.8.10 Remove UM role from a UM group

You can use this command to delete the assignment of a UM role to a UM group.

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 213
References
6.2 UMX reference

• group: Represents the group name if the "–s" parameter is present, or the group-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.
• role: Represents the role name if the "–s" parameter is present, or the role-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, the objects are identified with their internal identifier.

6.2.8.11 Remove attribute of a UM user

You can use this command to remove an attribute with its value from a UM user.

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• attributeName: String that represents the attribute name.
• userId: Positive number that represents the internal ID of the data record that corresponds
to the UM user to whom the specified attribute and its value were assigned. You can query
the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.8.12 Remove alias name of a UM user

You can use this command to remove the alias name of a UM user.

UMC - Central User Management

214 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Syntax
umx [-x commandUserName commandUserPassword] -R -a -u userId [-s (use
username instead of userId)]

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• userId: Positive number that represents the internal ID of the data record that corresponds
to the UM user to whom the specified attribute and its value were assigned. You can query
the user ID with the "Create list of object details" command.
See also: Create list with object details (Page 202)

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.8.13 Remove UM function right from a UM role

You can use this command to remove an assigned UM function right from a UM role.

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

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• functionRightName: Name of a UM function right.
An overview of the UM function rights can be found here: UM function rights (Page 17).
• role: Represents the role name if the "–s" parameter is present, or the role-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 215
References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s"
parameter is not present, the objects are identified with their internal identifier.

6.2.9 Importing and exporting UMC users and UMC groups

6.2.9.1 Overview of import/export commands

You can use the following commands to perform import or export operations.

Import commands
• Import objects from a file (Page 216)
• Import local Windows users or virtual user accounts (Page 226)
• Import AD users (Page 227)
• Import AD groups (Page 228)
• Import AD Groups with LDAP query (Page 229)
• AUTOHOTSPOT

Export commands
• Export objects to a file (Page 225)
• AUTOHOTSPOT
• AUTOHOTSPOT

6.2.9.2 Import objects from a file

You can use this command to import a set of users or groups into the UMC database. If the user
or group exists in the UMC database, the corresponding data record is updated. If the user or
group does not exist, it is inserted.
The file from which users or groups are imported can have the format "CSV" (Comma
Separated Values) or "JSON" (JavaScript Object Notation). The first row of the CSV file must
contain the column names, the following rows must contain the corresponding values,
separated by a semicolon.

NOTICE
Order of columns
The order of the columns in the file must match the listing.

UMC - Central User Management

216 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

User schema - CSV format

The binding of a user fails if the user's group does not exist. Therefore, before importing the
users, their groups must be imported. The following table displays the names and descriptions
of the data records for the import of users:

Name Description
Name User name
Password User password
This field is empty during export.
Full name Full name of the user
Groups List of group names to which the user belongs, separated by ",". Example: group1,group2,group3. If
the group does not exist, no binding is performed. No error is returned.
Email Email address of the user
Language User language
Data Language User data language
Status A bit mask that represents the following flags:
• USER_IS_ENABLED
• USER_IS_LOCKED
• USER_IS_IMPORTED: indicates that the user was imported from AD. This information is only
relevant in the case of an export.
• USER_HAS_EXPIRATION_DATE
To set a flag to True, the character "x" must be inserted in the corresponding position, otherwise the
character "-" must be entered.
Example: x-xx:
• User is enabled
• User is not locked
• User is imported
• User has an expiration date
The expiration of the validity is stored in a user property. If USER_HAS_EXPIRATION_DATE flag is set
to False, the stored value is ignored.
Mobile Mobile phone number
Phone Telephone number
First name First name
Last Name Last name
Initials Initials
Comment Comment

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 217
References
6.2 UMX reference

Name Description
Policy Bit mask that represents the 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" must be inserted in the corresponding position, otherwise the
character "-" must be entered.
Example: xx-- indicates that a user must have the password to log in for the first time and can change
the password, that the password never expires and that no alarm for password expiration is displayed.
The time until expiration of the password in days is stored in a user property. If the
flag USER_HAS_PASSWORD_EXPIRATION is set to false, the stored value is ignored.
Expiration Date Expiration date of the user
Password Expiration Integer value that displays the days until the password expires
Days
Alarm Password Expira‐ Integer value that displays the alarm message, in days, prior to the expiration of the password
tion Days

NOTICE
Active Directory users
Active Directory users cannot be imported into UMC with a CSV file. If this is attempted, the
newly created UM users are not linked to AD. To import AD users, the UMC Web UI or the
corresponding umx command must be used.
See also: Import AD users (Page 227)

User schema - JSON format

The following schema is used for the import/export of users.
Write-protected fields: These fields are returned during import/export and ignored during
import.
When creating, the following fields must be filled in: "name", "full name", "comment",
"password".
During the import, name parameter is write-protected and is used to identify the object to be
changed. Alternatively, the id can be used.
{
"users": [
{
"result": 0, //read only
"id": 1735, //read only
"name": "Mario Rossi",
"password": "thepassword",

UMC - Central User Management

218 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

"objver": 2,
"fullname": "full name",
"firstname": "Mario",
"lastname": "Rossi",
"initials": "M.R.",
"groups": [ ],
"roles": [ "UMC admin" ],
"alias": [ ],
"attributes": [
{
"name": "attr_name",
"value": "attr_value"
}
],
"canchange": 1,
"mustchange": 0,
"locked": 0,
"override_lock_policy": 0,
"offline": 0,
"comment": "",
"datalanguage": "and",
"language": "und",
"autologoff": 0,
"email1": "",
"email2": "",
"email3": "",
"enabled": 1,
"expirationdate": "",
"expired": 0,
"imported": 0,//read only
"importedfromad": 0,//read only
"importedfromgroup": 0,//read only
"otp_enabled": 0,//read only
"passwordexpirationdays": 60,
"alertbeforepasswordexpirationdays": 0,

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 219
References
6.2 UMX reference

"alertsbeforeexpirationdate": "",
"phone": "",
"mobile": "",
"sid": "",
"timebeforeautologoff": 0
}
]
}

Note
Alias names and groups cannot be imported currently.

User schema - Use of hashes for the password transmission

To reduce the risk of a password breach, a hash value generated with a salt function can be used
in lieu of the full-text password.
Example:
"password" : { "hash" : "vHZsbfcdnw8aPL0Tcc6fW5lBYitRLGusm/
uMcXcOKbmn8nTWZIEk6YZ3M9VFfV4Oqrx2X4CMNaIulEzWOKNfT3Q8ed3zVFAtCIXgmG
iECug=", //encoded base64
"salt" : "ZnVvY28=",//salt encoded as base64 - max
32 byte
"algorithm" : "PBKDF2-HMAC-SHA512", //algorithm
used for hashing (PBKDF2-HMAC-SHA512 unique value supported)
"encoding" : "utf16le",// encoding for the password
before hashing (allowed values: utf8 - utf16le)
"iteration" : 10000, //min accepted 0 - max 100000
"length" : 80 //min 32 bytes - max 256 bytes }
The hash value is generated by hashing the password (without zero end delimiter) with
PBKDF2 (HMAC-SHA512).

Note
• The password cannot be exported (visible or hashed) under any circumstances.
• Recommended values:
– Salt 32 bytes
– Length 128 bytes
– Iterations 1000
• The use of different parameters can have an impact on security (lower) or performance
(higher).

UMC - Central User Management

220 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Group schema - CSV format

The following table shows the names and descriptions of the data records for the import of
groups:

Name Description
Name Name of the group
Description Description of the group

Group schema - JSON format

The following schema is used for the import/export of users.
Write-protected fields: These fields are returned during import/export and ignored during
import.
When creating, the following fields must be filled in: name
During the import, name parameter is write-protected and is used to identify the object to be
changed; alternatively, id parameter can be used.
{
"groups": [
{
"result": 0, //read only
"id": 389, //read only
"name": "groupname",
"objver": 1,
"description": "description",
"users": [ "MarioRossi" ],
"roles": [ "UMC admin" ],
"imported": 0,
"lastSync": 0,
"offline": 0,
"sid": "",
"syncStatus": "SYNC_IGNORE"
}
]
}

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 221
References
6.2 UMX reference

Role schema - CSV format

Note
CSV format is not available.

Role schema - JSON format

The following schema is used for the import/export of UM roles.
Write-protected fields: These fields are returned during import/export and ignored during
import.
When creating, the following fields must be filled in: name
During the import, name parameter is write-protected and is used to identify the object to be
changed. Alternatively, the id can be used.
{
"roles":{
"description":"Who can join a server to the ring",
"name":"Joiner",
"rights":["UM_JOIN","UM_VIEW"]
}
}
UM function rights allow a user to perform certain functions. They are assigned to UM roles,
so that UM users with a specific UM role are allowed to perform the operations assigned to
that role. The following table contains a list of the UM function rights:

Name Description
UM_ADMIN Allows the viewing of data from the UMC database and the configuration of the
UMC database, i.e. create users, groups, etc., import and export data via a file and
register clients at the UMC station. All umx commands can be executed with this
UM function right.
UM_VIEW Allows the viewing of data from the UMC database about UM users, UM groups, UM
roles and account policies.
UM_RESETPWD The user can reset the password of another user. The user must also have the
"UM_VIEW" function right.
UM_UNLOCKUSR The user can unlock another user. The user must also have the "UM_VIEW" function
right.
UM_ATTACH The user can attach a computer to a UM domain, the device is then given the role
of UM agent.
UM_JOIN The user can promote a computer to the role of UM server. If the computer is not yet
joined to the UM domain, it is joined with this command. This UM function right
includes the UM function right "UM_ATTACH".
UM_RESETJOIN The user can demote a computer from the role of UMC ring server or UMC server to
the role of UMC agent.
UM_IMPORT The user can import the UM configuration via a package. The user must also have
the "UM_VIEW" function right.

UMC - Central User Management

222 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Name Description
UM_EXPORT The user can export the UM configuration to a package. The user must also have the
"UM_VIEW" function right.
UM_BACKUP The user can back up the UM configuration (full backup). This UM function right is
not used because the corresponding functionality has not yet been implemented.
UM_EXPORTCK The user can export claim keys. This UM function right is not used because the
corresponding functionality has not yet been implemented.
UM_EXPORTDK The user can export domain keys. This UM function right is not used because the
corresponding functionality has not yet been implemented.
UM_RA Log in via remote authentication. This UM function right is not used because the
corresponding functionality has not yet been implemented.
UM_RINGMNG The user can promote a computer to the role of "UMC ring server". If the computer
is not yet joined to the UM domain, it is joined with this command.
UM_ADSYNC The user can run the synchronization of the AD provisioning service in the back‐
ground.
UM_VIEWELG The user can view event log data. The user must also have the "UM_VIEW" function
right.
UM_CLAIMAUTH The user can create an identity from a valid claim.
UM_REGCLIENT The user can register clients for the UMC station.

Account policy schema - CSV format

Note
CSV format is not available.

Account policy schema - JSON format

The following schema is used for the import/export of account policies.
Write-protected fields: These fields are returned during import/export and ignored during
import.
{
"accpol": {
"globalAccountPolicies": {
"adCacheAging": 30,
"enableLockAfterNumberOfAttempts": 1,
"enablePasswordCheck": 0,
"enablePasswordHistoryByDays": 1,
"enablePasswordHistoryByNumber": 0,
"maxLoginErrors": 5,
"minDaysBeforePasswordReuse": 120,
"numberOfPasswordBeforeReuse": 5,

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 223
References
6.2 UMX reference

"passwordAging": 60,
"passwordMaxLength": 120,
"passwordMinAlphaChar": 2,
"passwordMinLength": 8,
"passwordMinLowerChar": 1,
"passwordMinNumericChar": 1,
"passwordMinOtherChar": 0,
"passwordMinUpperChar": 1
},
"systemPolicies": {
"pki": {
"authmode": 10,
"filter": "test",
"issuer": "anothertest"
},
"sads": { "enableAkp": 0 }
}
}
The following list contains rules for the handling of special characters:
• Semicolon: If a data record value contains a semicolon, it must be enclosed inside quotation
marks. Example: If a full name such as Brown;Peter is to be entered, it must appear in the CSV
file as "Brown;Peter".
• Quotation marks: If a data record value contains a quotation mark, it must be enclosed inside
quotation marks and each quotation mark must be preceded by a quotation mark. Example:
If the value "Peter" is to be entered, the value ""Peter"" must be entered in the CSV file
• Comma: Value lists are separated by commas. If one of the values contains a comma
character, each value must be enclosed inside quotation marks. Example: To enter group,1
and group,2 for a user, enter "group,1","group,2" in the CSV file. If one of the values contains
a quotation mark, this character must be preceded by three quotation marks.

Syntax
umx [-x commandUserName commandUserPassword] -I {-u |-g |-all} -f
fileName -t format -noroot -fout outputfileName

Parameters
• filename: Name of the CSV file, for example: myFile.csv.
• format: File format: 0 for CSV, 1 for JSON.

UMC - Central User Management

224 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-u The data of the csv or json files is imported as UM users.
-g The data of the csv or json files is imported as UM groups.
-all The entire configuration is imported. Is only supported for json format.
-f File name
-t File format, i.e.:
• 0 for csv
• 1 for json
-noroot If this flag is enabled, the password of the root user is not changed.
-fout Name of the result file

For the option -all, the JSON format is a concatenation of the sections for UM groups, UM
users, UM roles and policies.

6.2.9.3 Export objects to a file

You can use this command to export UM users or UM groups to a CSV file (Comma Separated
Values). The file format is the same as when importing. Passwords, attributes and alias names
are not exported. Flag USER_IS_IMPORTED in the "Status" field indicates that the user was
imported from Active Directory.
See also: Import objects from a file (Page 216)

Syntax
umx [-x commandUserName commandUserPassword] -E {-u | -g |-all} -f
fileName -t format

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• filename: Name of the CSV file, for example "myFile.csv".

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-u The data of the CSV or JSON files is exported as UM users.
-g The data of the CSV or JSON files is exported as UM groups.
-all The entire configuration is exported. Is only supported for JSON format.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 225
References
6.2 UMX reference

Parameter Description
-f File name
-t File format:
• "0" for a CSV file
• "1" for a JSON file

6.2.9.4 Import local users or virtual user accounts

You can use this command to import the specified local users into UMC users. Optionally, an
existing UM role can be assigned to the imported user. The user name of the user imported into
UMC follows the pattern "<machineName>\ <localUserName>". In the case of a virtual service
account, the user name of the user imported into UMC is "<machineName>\$VUA$<service
name>". In the case of an IIS APPPOOL identity, the user name of the user imported into UMC
is "<machineName>\$IIS$<apppool identity name>".
The command can only be used to import a local computer user to a UMC server or UMC ring
server. You can find information on how to import a local user into a UMC agent in section
"Importing a local Windows user into a UMC agent (Page 81)".
To import Active Directory users, the UMC Web UI or the corresponding umx command must
be used.
See also: Import AD users (Page 227)
This command can also be used to import integrated local users. The following table specifies
the user name parameter for the integrated local user:

User Parameter user name

Local system "NT AUTHORITY\System"
Local service "NT AUTHORITY\LOCAL SERVICE"
Network service "NT AUTHORITY\NETWORK SERVICE"
Virtual service ac‐ "NT SERVICE\<SERVICE NAME>"
count
IIS APPPool identity "IIS APPPOOL\<application pool name>"

NOTICE
Local users
Local users imported from Windows should only be used for configuration purposes, for
example for assignment to a Windows service running on the computer. Authentication to the
underlying operating system is required.

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

UMC - Central User Management

226 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• userName: String that represents the user name.
• role: Represents the role name. It must be present in UMC.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-w Specifies that the user to be imported is a local user.

6.2.9.5 Import AD users

You can use this command to import an AD user (user of a Windows domain) into a UMC user.
The user name of the user imported into UMC follows the pattern "<ADdomainName>\
<ADuserName>". Imported AD users are authenticated to Windows. The import is based on a
search index returned by the "Create list of objects" umx command. The search index-based
command only works in interactive mode and cannot be used in scripts. Alternatively, AD users
can be imported based on an entered search criterion. Optionally, the imported users can be
assigned an existing UM role.

Syntax
umx [-x commandUserName commandUserPassword] -I -du -s searchString
-d domainName [-r role] [-f]

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• searchString: Filters the list of AD users. The "*" wildcard character is allowed and the
search is performed in the following Active Directory fields:
– user name (sAMAccountName)
– user full name (displayName)
– Common Name (cn)
• domainName: Domain from which the user(s) is/are imported.
• role: UM role that is assigned to the imported user(s).

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 227
References
6.2 UMX reference

Optional parameters

Parameter Description
-f Forces the creation of multiple users.

See also
Create list of objects (Page 204)

6.2.9.6 Import AD groups

You can use this command to import AD groups into UMC groups based on an entered search
criterion. The group name of the groups imported into UMC follows the pattern
"<ADdomainName>\ <ADgroupName>". All users of the group are imported and authenticate
themselves to AD. Optionally, an existing UM role can be assigned to the imported groups.

Syntax
umx [-x commandUserName commandUserPassword] -I -dg -s searchString
-d domainName [-r role] [-f]

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• searchString: Filters the list of AD groups, the "*" wildcard character is allowed, the
search field is the name of the group (cn).
• domainName: Name of the AD domain (without extension) to which the group belongs.
• role: UM role assigned to the imported user(s).

Optional parameters

Parameter Description
-f Forces the creation of multiple groups.

Note
If an Active Directory group is not allowed to be imported with its Common Name (CN), the
group must be created offline and the description can be used to configure the import criteria.
You can find more information in the section "UM group (Page 15)".

UMC - Central User Management

228 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Note
Nested groups of the imported group are not imported. It is possible to enable the import of
users belonging to nested groups so that the users of nested groups are imported and linked to
the parent group.
You can find information and activation instructions in the section "AUTOHOTSPOT".

6.2.9.7 Import AD Groups with LDAP query

You can use this command to create an offline group and assign users to that group after the
query in the description has been executed. The group name of the group imported into UMC
follows the pattern "<ADdomainName>\ <GroupName>". All users who belong to the group
specified in the query are imported. In this way, a group with its users can be imported via an
LDAP query, which is partially included in the group description.
You can find additional information in the section Create UM group (Page 196).

Syntax
umx [-x commandUserName commandUserPassword] -c -g
<ADdomainName>\<GroupName> -d {{Q=<ldap query> -off

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• <ADdomainName>\<GroupName>: String that represents the group name. Only
alphanumeric characters are allowed.
• {{Q=<ldap query>: String with the LDAP query for the group.

Optional parameters

Parameters Description
-x The command is executed by the user specified as the input parameter.
-d LDAP query for the group.
-off The specified group is created as an offline group.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 229
References
6.2 UMX reference

6.2.10 Execute administrative commands

6.2.10.1 Set user password

You can use this command to change the user password. The new password does not necessarily
have to comply with the global account policies. The user who executes the command must
have the UM function right "UM_ADMIN" or the UM function rights "UM_VIEW" and
"UM_RESETPSW". Empty passwords are not allowed.

Syntax
umx [-x commandUserName commandUserPassword] –setpwd userName
newPassword

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• userName: String that represents the user name.
• newPassword: The new password, which may deviate from the global password
requirements. You can enable a password check with the "Change account policies - Set
password check" command.
See also: Change account policies - Enable password check (Page 243)

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

See also
UM function rights (Page 17)

6.2.10.2 Enable UM user

You can use this command to enable a UM user.

Syntax
umx [-x commandUserName commandUserPassword] -enableusr userName

UMC - Central User Management

230 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• userName: String that represents the user name.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.3 Disable UM user

You can use this command to disable a UM user.

Syntax
umx [-x commandUserName commandUserPassword] -disableusr userName

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• userName: String that represents the user name.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.4 Unlock UM user

You can use this command to unlock a UM user.

Syntax
umx [-x commandUserName commandUserPassword] -unlockusr userName

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 231
References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• userName: String that represents the user name.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.5 Disable safe mode

You can use this command to disable safe mode. The UMC ring server on which safe mode is
disabled becomes the master UMC ring server and can write to the UMC database. Note that in
this case, certain actions in the UMC system configuration are not possible, such as editing the
allowlist.
See also:
You can find more information on editing the allowlist in the section Managing allowlist
entries (Page 179).
For more information on the UM roles, see UM role (Page 16).

Syntax
umx [-x commandUserName commandUserPassword] –disablesafe

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

UMC - Central User Management

232 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

6.2.10.6 Show status

You can use this command to have the results of the UMC health check provided as an output.

Note
To retrieve the status of UMC, a user must be specified who is a Windows user with administrator
rights or an elevated user when "User Account Control" (UAC) is enabled.

Info Description
UMC health sta‐ Status of the UMC server.
tus Example: All UMC servers are running.
UMC communica‐ Status of the secure UMC communication services.
tion status Example: All UMC communication are running.
Machine role Possible values are:
• ring
• server
• agent
Example: Machine role is ring
Claim Key A claim key is available or not available. Not available for a UMC agent.
Ticket Key A ticket key is available or not available. Not available for a UMC agent.
UMC databases UMC databases are available or not available. Not available for a UMC agent.
Discovery status Details for the connection between UMC server and UMC client. Not available for a
UMC agent.
Example: Discovery status is connected
Possible values are:
• connected
• standalone (not used)
• no configuration found
• not initialized
• generic error
Workstation sta‐ Not available for a UMC agent.
tus Example: Workstation status is master
Possible values are:
• master: The device is a master UMC ring server.
• online: The device is a UMC ring server (not a master) or a UMC server.
• remote_master_is_in_safe_mode: The device is a UMC server that is connected
to a master in safe mode.
• initializing: The device is initialized.
• degraded: The device is a UMC server and is not connected to a UMC ring server.
• unconnected: Not connected
• segregated: The device is a segregated server.
• error: Generic error

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 233
References
6.2 UMX reference

Info Description
Ring master Name of the UMC ring master.
Example: The UMC ring master is now: vm-umc1.
This field also indicates whether the ring server is in safe mode:
Example: vm-umc1 in safe mode
Proxy server Name of the connected proxy server.
Example: Connected with proxy: vm-proxy1
Authentication The connected authentication server.
server Example: Authentication server is vm-umc1
Network certifi‐ Example, if a certificate has been found: present and it expires in 3649 days
cate Example, if certificate is missing: not present
Machine certifi‐ Example, if a certificate has been found: present and it expires in 3649 days
cate Example, if certificate is missing: not present
Example, if certificate has expired: present and it expires in 0 days

NOTICE
Renewing certificates
Network and device certificates can be automatically renewed when their expiration date
approaches. For more information on renewal of certificates, see section <Topic in the
installation guide>.

Syntax
umx [-x commandUserName commandUserPassword] –status

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

Examples
Example #1: The following example shows the output after a health check for the UMC ring
server.
UMC Health Check information.
UMC Health Status : All UMC servers are running.

UMC - Central User Management

234 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

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
Network certificate: present and it expires in 3649 days
Machine certificate: present and it expires in 3649 days
Time taken: 0.13s
Example #2: The following example shows the output after a health check for the UMC 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
Network certificate: present and it expires in 3649 days
Machine certificate: present and it expires in 3649 days
Time taken: 11.46s

6.2.10.7 Retrieve domain ID

You can use this command to retrieve the ID of the current UM domain.

Syntax
umx [-x commandUserName commandUserPassword] -getdomainid

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 235
References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.8 Get domain name

You can use this command to retrieve the name of the current UM domain.

Syntax
umx [-x commandUserName commandUserPassword] -getdomainname

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.9 Generate or reset secret key for 2FA

You can use this command to generate the secret key for the specified user if it does not already
exist. If it already exists, this command resets it. This command can also be used to set the secret
key for the administrator.

Syntax
umx [-x UserName UserPassword] -resettotp

Parameters
• UserName: String that represents the name of the user for whom the secret key is to be
generated or reset.
• UserPassword: String that represents the password of the user for whom the secret key is
to be generated or reset.

UMC - Central User Management

236 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-resettotp The command is executed to reset the temporary one-time password. (TOTP).

6.2.10.10 Change user language

You can use this command to set the user language of the UM user currently logged in to UMX.

Syntax
umx [-x commandUserName commandUserPassword] -changeUserLang language

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• language: User language in format "<langcode>- <countrycode>", for example "en-GB".
The two components have the following meaning:
– "langcode": Language code according to ISO 639. Both two-digit codes (ISO 639-1) and
three-digit codes (ISO 639-2) are accepted.
– "countrycode": Country code according to ISO 3166.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.11 Change language of the user data

You can use this command to set the language of the data of the UM user currently logged in to
UMX.

Syntax
umx [-x commandUserName commandUserPassword] -changeDataLang
datalanguage

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 237
References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• datalanguage Language of the user data in the format <langcode>-<countrycode>, for
example, en-GB. The two components have the following meaning:
– "langcode": Language code according to ISO 639. Both two-digit codes (ISO 639-1) and
three-digit codes (ISO 639-2) are accepted.
– "countrycode": Country code according to ISO 3166.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.12 Display user properties

You can use this command to display the properties of the user currently logged in to UMX.

Syntax
umx [-x commandUserName commandUserPassword] -showUserProperties

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.10.13 Force synchronization of the "UP Service" service

You can use this command to force a global synchronization for the "UP Service" service.
For more information on how to set the synchronization times for the "UP Service" service,
see section Additional provisioning configuration (Page 84).

UMC - Central User Management

238 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Syntax
umx [-x commandUserName commandUserPassword] -sync

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.11 Managing account policies

6.2.11.1 Change account policies - Passwords

You can use this command to change the account policies for the password management.
If the password history by number of days is enabled ("daysReuse" parameter), the password
history by number of passwords ("numPwd" parameter) 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]
[-maxLoginErrors numErrors]
[-ADCacheAge numDays]

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 239
References
6.2 UMX reference

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• minLen: Minimum permissible password length If "0" is set, this check will be disabled.
Empty passwords are not allowed.
• maxLen: Maximum permissible password length If "0" is set, this check will be disabled.
Empty passwords are not allowed.
• minLC: Minimum permissible lowercase letters.
• minUC: Minimum permissible uppercase letters.
• minAlphaC: Minimum permissible alphabetic characters in passwords.
• minNumC: Minimum permissible numeric characters in passwords.
• minOC: Minimum permissible special characters, i.e. neither alphabetic nor numeric, in
passwords.
• flag: "0" corresponds to "false" and "1" corresponds to "true".
• daysReuse: Number of days before the same password can be used again.
• numPwd: Number of passwords before the same password can be used again.
• numErrors: Number of errors when entering the password, after which the user is locked.
The lock of a user also depends on the value of the "paramOverrideLock" parameter.
See also: Update user (Page 198)
• numDays: Number of days before the AD cache expires. This number must have a value
between "30" and "250" days. The default value is "0" (AD cache disabled).

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.11.2 Change account policies – Assign Windows user to the "UP Service" service
You can use this command to assign the UMC user designated with the "name" parameter to the
"UP Service" service. This UMC user must have a UM role with the associated UM function
right "UM_ADSYNC". This UM role is not created automatically and must be created before this
UMC user is assigned. This UMC user is saved as an account policy. After execution of the
command, the "UP Service" service must be restarted.

Note
This configuration is not mandatory. The UMC user assigned to the provisioning service by
default is the administrator. We strongly recommend making this configuration to harden your
system according to the least privilege principle.

UMC - Central User Management

240 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Syntax
umx [-x commandUserName commandUserPassword] -AP
-provisioningDefaultUser user [-s]

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.
• user: Represents the user name if the "–s" parameter is present, or the internal user ID if the
"–s" parameter is not present. The ID is a positive number that uniquely identifies the data
record.

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s" parameter is not
present, objects are identified with their internal ID.

6.2.11.3 Change account policies - Restore

You can use this command to reset the account policies to their default settings. The default
settings are:
• Minimum number of characters: 8
• Maximum number of characters: 120
• Minimum number of lowercase letters: 1
• Minimum number of uppercase letters: 1
• Minimum number of alphabetic characters: 2.
• Minimum number of numeric characters: 1
• Minimum number of special characters (not alphabetic or numeric characters): 0
• Password history:
– Enable password history by number of days: true
– Number of days before the same password can be used again: 120
– Enable password history by number of passwords: false
– Number of passwords before the same password can be used again: 5
• Block user after n login errors: true
• Number of login errors after which the user is locked: 5

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 241
References
6.2 UMX reference

Syntax
umx [-x commandUserName commandUserPassword] -AP -restore

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.11.4 Change account policies - Set default PKI rule

You can use this command to set a default PKI rule for the authentication of smartcards. A PKI
rule specifies for a particular issuer the authorization mode that can be used and the
corresponding filter.
For more information and an example of how to configure smartcard authentication, see the
section <Link to topic in the installation guide>

Syntax
umx-AP -setdefaultpki -issuer issuerName -authmode authModeValue [-
filter filterValue]

Parameters
• issuerName: Name of the certificate issuer. This value is not currently used.
• authModeValue: Represents the different types of allowed authentication modes:
– 2: Authentication with filtering by "Subject"
– 3: Alias authentication with filtering by "Subject"
– 4: Authentication with CN
– 5: Alias authentication with CN
– 10: Authentication with filtering by "Alternate subject"
– 11: Alias authentication with filtering by "Alternate subject"
• filterValue: Regular expression for the filter.

See also
Change account policies - Reset default PKI rule (Page 243)

UMC - Central User Management

242 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

6.2.11.5 Change account policies - Reset default PKI rule

You can use this command to reset the default PKI rule for the authentication of SmartCards. A
PKI rule specifies for a particular issuer the authorization mode that can be used and the
corresponding filter.
See also: Change account policies - Set default PKI rule (Page 242)

Syntax
umx -AP -resetdefaultpki

6.2.11.6 Change account policies - Secure Application Data Support

You can use this command to change the account policies for Secure Application Data Support
(SADS).

Syntax
umx -AP {-setakp | -resetakp}

Optional parameters

Parameter Description
-setakp Enables the Secure Application Data Support for users and groups.
-resetakp Disables the Secure Application Data Support for users and groups.

6.2.11.7 Change account policies - Enable password check

You can use this command to enable a check for the passwords set by the administrator when
creating and updating a user. This check ensures that no passwords can be set that do not
comply with the global account policies. Policies for the reuse of passwords are not applied.

Syntax
umx -AP -setpswcheck

6.2.11.8 Change account policies - Disable password check

You can use this command to disable the check for passwords set by the administrator for
ensuring that no passwords can be set that do not comply with the global account policies.

Syntax
umx -AP -resetpswcheck

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 243
References
6.2 UMX reference

6.2.12 Execute commands in interactive mode

6.2.12.1 Interactive mode

You can use this command to start the interactive mode of umx. The umx process is always
active and the individual commands can be triggered directly without a preceding umx string.
The following commands can only be started in interactive mode:
• -q: Ends the interactive mode.
• -lockdb: Initiates a write lock in the UMC database.
• -unlockdb: Removes the write lock in the UMC database. If the DB is not locked, the only
possible command is lockdb.

Syntax
umx -interactive

Note
Database lock
If umx is started in interactive mode, a write lock is set up for the database. In this way, database
objects cannot be changed by other processes or applications. Read access is allowed.

6.2.12.2 Enable notifications

You can only use this command for test purposes. It enables notifications about the connection
status of the server and about the creation, update, and deletion of the following database
objects:
• UM users
• UM groups
• UM roles
• Account policies

Syntax
umx [-x commandUserName commandUserPassword] -N

Parameters
• commandUserName: String that represents the name of the UM user executing the
command.
• commandUserPassword: String that represents the password of the UM user executing the
command.

UMC - Central User Management

244 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the UM user specified as the input parameter.

6.2.13 Execute authentication commands

6.2.13.1 Test authentication

You can use this command to perform an authentication to UMC with the entered login
credentials. If the "-win" parameter is present, the authentication of the user who is currently
logged in to Windows is performed. If the "-dsso" parameter is present, the authentication of the
user who is currently logged in to DSSO (Desktop Single Sign-on) is performed. The output for
the command indicates whether the authentication was successful and whether the
authenticated user has the UM function right "UM_ADMIN UM".

Syntax
umx -t userName userPassword [-totp]
umx -t -win [-totp]
umx -t -dsso [-totp]

Parameters
• userName: Represents the user name of the UM user to be authenticated.
• userPassword: Represents the user password.

Optional parameters

Parameter Description
-win Authenticates the currently logged in Windows user.
-dsso Authenticates the currently logged in DSSO user.
-totp Displays the secret key.

6.2.13.2 Generate ticket

After entering a user name and the associated password, you can use this command to generate
a ticket that will be used instead of the password for the authentication. The period of validity
of the ticket must be indicated. After the validity expires, the ticket expires and can no longer be
used for login.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 245
References
6.2 UMX reference

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

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• userName: Represents the user name.
• password: Represents the user password.
• duration: Represents the period of validity of the ticket in seconds.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.13.3 Change user password

You can use this command to change the user password if you know the old password. The new
password must comply with the global account policies. Empty passwords are not allowed. This
command can also be used on a UM server in "Degraded" mode. When degraded mode of the
UM server ends, the passwords are compared at the database level and the most recent
password is retained.
For more information on "Degraded" mode, see section <Link to topic in the installation
guide>

Syntax
umx [-x commandUserName commandUserPassword] –changepwd userName
oldPassword newPassword

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• userName: String that represents the user name.
• oldPassword: String that contains the old password.
• newPassword: String that contains the new password.

UMC - Central User Management

246 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.

6.2.14 Working with Secure Application Data Support (SADS)

6.2.14.1 Overview of data encryption and decryption commands

Overview
You can use the following commands to encrypt and decrypt the data of users and groups in
order to apply Secure Application Data Support (SADS):
• Enable encryption (Page 247)
• Encrypt keys (Page 248)
• Decrypt keys (Page 248)
At the application level, SADS can be enabled via umx or the Web UI by modifying an
account policy. At the level of users and groups, this is only possible with umx.
See also: Change account policies - Secure Application Data Support (Page 243)

6.2.14.2 Enable encryption

You can use this command to enable encryption for users and groups (subjects).

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

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• user: Represents the user name if the "–s" parameter is present, or the internal user
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record. You can query the user identifier with the "Create list of object
details" command.
See also: Create list with object details (Page 202)
• group: Represents the group name if the "–s" parameter is present, or the group-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 247
References
6.2 UMX reference

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s" parameter is not
present, the objects are identified with their internal identifier.

6.2.14.3 Encrypt keys

You can use this command to encrypt an application key (AK) with the subject key (SK) of the
user or group.

Syntax
umx [-x commandUserName commandUserPassword] -AK -e -k Key {-u user |-
g group} [-s] [-f]

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• Key: Application key to be used to encrypt the application data.
• user: Represents the user name if the "–s" parameter is present, or the internal user
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record. You can query the user identifier with the "Create list of object
details" command.
See also: Create list with object details (Page 202)
• group: Represents the group name if the "–s" parameter is present, or the group-internal
identifier if the "–s" parameter is not present. The identifier is a positive number that uniquely
identifies the data record.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-s If the "-s" parameter is present, the objects are identified with their name. If the "-s" parameter is not
present, the objects are identified with their internal identifier.
-f The encrypted key is stored in the clipboard of umx.

6.2.14.4 Decrypt keys

You can use this command to decrypt an application key (AK) with the subject key (SK) of the
user or group. The encrypted application key can only be decrypted if it has been previously
encrypted with a subject key of the currently authenticated user or the group to which it belongs.

UMC - Central User Management

248 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

SADS provides offline authentication, which means that users can authenticate themselves
even if a connection to a UM server is not possible. This only applies if the user has
performed at least one decryption, the decryption of the EAKs must be possible according to
the subject keys available for this user. To use this functionality, the subject keys used for the
decryption are copied to the local cache.

Syntax
umx [-x commandUserName commandUserPassword] -AK -d {-k
EncryptedKey|-f}

Parameters
• commandUserName: String that represents the name of the user executing the command.
• commandUserPassword: String that represents the password of the user executing the
command.
• EncryptedKey: Key to be decrypted for the user or group, depending on their data access
configuration.

Optional parameters

Parameter Description
-x The command is executed by the user specified as the input parameter.
-f The UMX clipboard is used as input for the encrypted key.

6.2.15 Error codes

6.2.15.1 Error codes

Value Description
0 Success
-1 Syntax error of the command

In all other cases, the command returns the last error code in decimal format returned by the
UMC APIs called during the command execution.
For more information, see the section Error codes for UMC APIs (Page 250).

Example #1
As an example, the following script is used to display information on a user designated as 66
when the identifier "66" is not assigned to any user in the UMC database:
umx -i -u 66

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 249
References
6.2 UMX reference

echo %errorlevel%
Nothing is deleted and umx returns the decimal number "273". This corresponds to the
following error code in the error codes for UMC APIs:

Name Hexadecimal val‐ Decimal value Description

ue
SL_OBJ_DOES_NO 0x111 273 The UMC object does not exist or has not
T_EXIST yet been saved in the UMC database.

See also
Create list with object details (Page 202)

6.2.15.2 UMC APIs error codes

All 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. In the event of an API error, an
error code can be retrieved by calling the SL_GetLastError method. SL_RESULT specifies the
error type. The possible error codes are listed below.

General errors

Name Hexadecimal value Decimal value Description

SL_SUCCESS 0X00 0 No errors have occurred.
SL_GENERROR 0X01 1 General error.
SL_BAD_HANDLE 0x114 276 Internal error due to bad handle.
SL_NOSESSION 0X30 48 The web session has expired.

Authentication errors

Name Hexadecimal value Decimal value Description

SL_USERLOCKED 0X02 2 The UM user for whom the authentication is to be
performed is locked.
SL_USERDISABLED 0X03 3 The UM user for whom the authentication is to be
performed is disabled.
SL_WRONGUSERNA‐ 0X04 4 Wrong username or password during authentica‐
MEPASSWORD tion
SL_PASSWORDPOLICY‐ 0X05 5 Violation of the password policy (specified by
VIOLATION UMC account policies)
SL_USERMUSTCHAN‐ 0X06 6 The user password must be changed.
GEPASSWORD
SL_PASSWORDEXPIRED 0X07 7 The user password has expired.
SL_FAILED 0X0A 10 General operation failed.
SL_ALREADYLOCKED 0X0B 11 The UMC object is already locked.
SL_COMMERR 0X0C 12 Transmission/communication error

UMC - Central User Management

250 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Name Hexadecimal value Decimal value Description

SL_NOTIMPL 0X10 16 Is returned if the called method is not implemen‐
ted.
SL_CHANGEPSWDISA‐ 0X19 25 The UM user cannot change the password.
BLE
SL_USERUNKNOWN 0X20 32 The UM user does not exist in the system.
SL_USERNEVEREXPIRE 0X21 33 The UM user never expires.
SL_TICKETEXPIRED 0X22 34 The authentication ticket has expired.
SL_USER_EXPIRED 0x27 39 The UM user has expired.
SL_PSWMINLEN_ERR 0x120 288 The account policy regarding the minimum pass‐
word length has been violated.
SL_PSW_CHANGE_FAIL 0X154 340 Error while changing the password.
SL_INVALID_NONCE 0x166 358 Login failed: invalid token. This can occur if an
attempt is made to access the login page directly
via the URL, or if the login page is left open.
SL_WEAK_AUTH 0x167 359 Login failed: Access not allowed due to weak au‐
thentication method.

Processing errors

Name Hexadecimal value Decimal value Description

SL_ALREADYEXIST 0x0D 13 The UMC object already exists.
SL_LOCK_NEEDED 0x23 35 A lock is required to complete the operation.
SL_NOT_LOCKED 0x24 36 The UMC object is not locked, so you cannot en‐
able it.
SL_OBJVERMISMATCH 0x31 49 A UMC object has been modified by two Web UI
instances at the same time and mismatched ob‐
ject versions have been detected.
SL_INVALID_OPERA‐ 0x103 259 The operation cannot be performed for the selec‐
TION ted object.
SL_OBJ_DOES_NOT_EX 0x111 273 The UMC object does not exist or has not yet been
IST saved in the UMC database.
SL_OB‐ 0X153 339 The UMC object is already locked.
JECT_LOCKED_IN_DA‐
TABASE
SL_FAIL_NOTAMASTER 0x160 352 An attempt was made to change the UMC data‐
base on a device that is not the master.
SL_FAIL_BINDING_AD‐ 0x161 353 An attempt was made to assign the UM role "Ad‐
MIN_ROLE ministrator" to a group, or the UMX or Web UI user
who performed the assignment does not have
the UM role "Administrator".
SL_OBJ_OFFLINE 0x0F 15 The UM user/group for which you want to per‐
form an operation is offline and the operation is
not allowed for objects in offline status.

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 251
References
6.2 UMX reference

Name Hexadecimal value Decimal value Description

SL_INVA‐ 0x165 357 The offline user/group that is currently being cre‐
LID_NAME_FOR_OFF‐ ated does not follow the pattern <domain‐
LINE_OBJ Name>\<objName>.
SL_INVALID_SID 0x5C 92 Invalid User Security Identifier (SID). For more in‐
formation, see the Microsoft documentation on
Security Identifiers (https://
learn.microsoft.com/en-us/windows/win32/
secauthz/security-identifiers?
redirectedfrom=MSDN).

Provider operation errors

Name Hexadecimal value Decimal value Description

SL_INVALID_PROVIDER 0x100 256 Operation is not offered by this provider.
SL_INVALID_HANDLE 0x101 257 An invalid handle has been passed as a parameter.
SL_ERROR_LOAD‐ 0x102 258 An error occurred while loading the provider.
ING_PROVIDER

Internal or parameter errors

Name Hexadecimal value Decimal value Description

SL_INVALID_PARAME‐ 0x104 260 The method has an invalid parameter.
TERS
SL_MEMORY_ERROR 0x105 262 Memory allocation error.
SL_INITIALIZATION_ER‐ 0x106 263 Initialization error.
ROR
SL_INVALID_LOCK_OP‐ 0x108 264 The lock option has not been defined.
TION
SL_INVALID_PROPERTY 0x109 265 The property has not been defined for the object.
SL_INVALID_CULTURE 0x17B 379 Invalid language.

File errors

Name Hexadecimal value Decimal value Description

SL_ACCESS_FILE_ER‐ 0x112 274 File access error.
ROR
SL_UN‐ 0x113 275 Unknown file format.
KNOWN_FILE_FORMAT
SL_FILE_NOT_FOUND 0x50 80 File not found.
SL_PATH_NOT_FOUND 0x51 81 Path not found.
SL_FILE_CREA‐ 0x52 82 Error when creating the file.
TION_FAIL
SL_PATH_CREA‐ 0x53 83 Error when creating the path.
TION_FAIL
SL_INVALID_PATH 0x54 84 Invalid path.

UMC - Central User Management

252 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

UM function right errors

Name Hexadecimal value Decimal value Description

SL_RE‐ 0x150 336 The UM user does not have the correct UM func‐
SOURCE_NOT_FOUND tion right to perform the requested operation.
This error has the same meaning as error
SL_MISSING_FUNCTION_RIGHT.
SL_INVALID_RESOURCE 0x151 337 The UM function right does not exist.
SL_MISSING_FUNC‐ 0x152 338 The UM user does not have the correct UM func‐
TION_RIGHT tion right to perform the requested operation.
This error has the same meaning as error SL_RE‐
SOURCE_NOT_FOUND.

Service layer errors

Name Hexadecimal value Decimal value Description

SL_CLAIM_EXPIRED 0X155 341 The claim has expired.
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 Operation "make ticket" has failed.
SL_ABORTED 0x159 345 Operation aborted.

Package errors

Name Hexadecimal value Decimal value Description

SL_PACKAGE_CREA‐ 0x55 85 Failed to create the package.
TION_FAIL
SL_PACKAGE_COM‐ 0x56 86 Failed to compress the package.
PRESSION_FAIL
SL_PACKAGE_UNCOM‐ 0x57 87 Failed to uncompress the package.
PRESSION_FAIL
SL_PACKAGE_ENCRYP‐ 0x58 88 Failed to encrypt the package.
TION_FAIL
SL_PACKAGE_DECRYP‐ 0x59 89 Failed to decrypt the package.
TION_FAIL
SL_PACKAGE_RE‐ 0x5A 90 Failed to restore the package.
STORE_FAIL
SL_PACK‐ 0x5B 91 Wrong password for the package.
AGE_WRONG_PASS‐
WORD

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 253
References
6.2 UMX reference

Database errors

Name Hexadecimal value Decimal value Description

SL_DBFILE_AC‐ 0X32 50 The UM user does not have access to a database
CESS_DENIED file.
SL_DBFILE_ERROR 0X33 51 General UMC database file error.
SL_DBFILE_OUT_OF_SP 0X34 52 A UMC database file is full.
ACE
SL_TOO_MANY_GROU 0X36 102 Too many groups have been assigned to a UM
PS user.
SL_TOO_MANY_ROLES 0X37 103 Too many UM roles have been assigned to a UM
user or UM group.
SL_TOO_MANY_USERS 0X38 104 Too many UM users have been assigned to a UM
group.
SL_RO‐ 0X35 53 No additional role IDs are available in the role da‐
LEIDS_OUT_OF_SPACE tabase file. The UM_Roles must be purged.

Alias error

Name Hexadecimal value Decimal value Description

SL_INVA‐ 0x5E 94 Invalid alias name of the UM user.
LID_USER_ALIAS
SL_USER_ALIAS_AL‐ 0x5F 95 Alias name of the UM user already exists.
READY_EXIST
SL_BAD_PKI_FIL‐ 0x115 277 Invalid filter name or filter name does not exist
TER_NAME when authmode = SL_PKI_FILTER_MASK.

Secure Application Data Support (SADS) errors

Name Hexadecimal value Decimal value Description

SL_INVALID_DO‐ 0x60 96 Invalid domain name.
MAIN_NAME
SL_NOT_CURRENT_DO‐ 0x61 97 The entered name does not match the current
MAIN domain.
SL_INVALID_KEY 0x70 112 Invalid key.
SL_KEY_GENERA‐ 0x71 113 Error when generating the key.
TION_FAIL
SL_KEY_ENCRYP‐ 0x72 114 Error when encrypting the key.
TION_FAIL
SL_KEY_DECRYP‐ 0x73 115 Error when decrypting the key.
TION_FAIL
SL_KEY_NOT_FOUND 0x74 116 Key not found.
SL_KEY_ENCRYP‐ 0x75 117 Protection of the application key (global policies)
TION_NOT_ENABLED not enabled.
SL_MAX_NUM_KEY 0x76 118 Maximum number of allowed keys has been
reached.

UMC - Central User Management

254 Programming and Operating Manual, 11/2023, A5E52954435-AA
 References
6.2 UMX reference

Name Hexadecimal value Decimal value Description

SL_KEY_DECRYP‐ 0x77 119 No SUID of the identity found in the EAK array.
TION_NO_ID_FOUND
SL_SADS_VERSION_ER‐ 0x78 120 Incorrect SADS version.
ROR
SL_WRONG_IDENTITY 0x79 121 Ticket authentication error when decrypting a
key.
SL_EAK_BAD_FORMAT 0x80 128 Incorrect format of the encryption application
object.
SL_SUBJECT_NOT_EN‐ 0x81 129 Encryption not enabled for the specified subject.
ABLED
SL_SUBJECT_KEY_OB‐ 0x82 130 The decryption has been carried out with an ob‐
SOLETE solete key.

6.2.16 Parameter sizes

Parameter sizes
The following table contains the sizes for the most important UMC database fields:

Name of the API API object Display name in UMX parameter Size in characters
property the UMC Web UI
SL_USER_NAME SLOBJ_USER User name name 100
SL_USER_PASS‐ SLOBJ_USER Password password 120
WORD
SL_USER_FULL‐ SLOBJ_USER Full name fullName 250
NAME
SL_GROUP_NAME SLOBJ_GROUP Group name name 100
SL_GROUP_DE‐ SLOBJ_GROUP Description description 260
SCRIPTION
SL_ROLE_NAME SLOBJ_ROLE Role name name 255
SL_ROLE_DESCRIP‐ SLOBJ_ROLE Description description 40
TION
SL_ATTRIB‐ SLOBJ_ATTRIBUTE Attribute name attribute name 80
UTE_NAME

UMC - Central User Management

Programming and Operating Manual, 11/2023, A5E52954435-AA 255
References
6.2 UMX reference

UMC - Central User Management

256 Programming and Operating Manual, 11/2023, A5E52954435-AA