UMCONF User Manual

s Contents
UMCONF Overview 1
Concepts You Need to Know About 2
How to Display a Summary of
3
UMCONF Commands
How to Create UM Entities 4
How to Manage UM Services 5
How to Perform Binding / Unbinding
6
Commands
User Management Component 1.9.1 How to Upgrade UM Entities 7

UMCONF User Manual
How to Delete UM Configuration 8
How to Execute Import Commands 9
How to Manage Whitelist Entries 10
How to Manage Plugins 11
How to Manage Logs 12
How to Execute Commands in
13
Interactive Mode
How to Execute Purge Commands 14
How to Display Lists 15
Error Codes 16
04/2018
A5E39179378-AD
Guidelines
This manual contains notes of varying importance that should be read with care; i.e.:
Important:
Highlights key information on handling the product, the product itself or to a particular part of the documentation.
Note: Provides supplementary information regarding handling the product, the product itself or a specific part of
the documentation.
Trademarks
All names identified by ® are registered trademarks of Siemens AG.
The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes
could violate the rights of the owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software
described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the
information in this publication is reviewed regularly and any necessary corrections are included in subsequent
editions.
Security information
Siemens provides products and solutions with industrial security functions that support the secure operation of
plants, systems, machines and networks. In order to protect plants, systems, machines and networks against
cyber threats, it is necessary to implement – and continuously maintain – a holistic, state-of-the-art industrial
security concept. Siemens’ products and solutions only form one element of such a concept.
Customer is responsible to prevent unauthorized access to its plants, systems, machines and networks. Systems,
machines and components should only be connected to the enterprise network or the internet if and to the extent
necessary and with appropriate security measures (e.g. use of firewalls and network segmentation) in place.
Additionally, Siemens’ guidance on appropriate security measures should be taken into account. For more
information about industrial security, please visit http://www.siemens.com/industrialsecurity.
Siemens’ products and solutions undergo continuous development to make them more secure. Siemens strongly
recommends to apply product updates as soon as available and to always use the latest product versions. Use of
product versions that are no longer supported, and failure to apply latest updates may increase customer’s
exposure to cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed under http://www.
siemens.com/industrialsecurity.
Siemens AG A5E39179378-AD Copyright © Siemens AG 2018

Digital Factory 20180412_54566 Technical data subject to change
Postfach 48 48
90026 NÜRNBERG
GERMANY
Contents
1 UMCONF Overview ................................................................................................................. 5
2 Concepts You Need to Know About...................................................................................... 6
2.1 User Manager Domain...................................................................................................... 6
2.2 User Manager User........................................................................................................... 7
2.3 Built-in User Roles ............................................................................................................ 8
2.4 Claim Key.......................................................................................................................... 8
2.5 User Manager Function Rights ......................................................................................... 8
3 How to Display a Summary of UMCONF Commands ........................................................ 10

3.1 Help................................................................................................................................. 10
4 How to Create UM Entities ................................................................................................... 11

4.1 Create Domain................................................................................................................. 11
4.2 Create UM Administrator User........................................................................................ 12
4.3 Create Claim Key............................................................................................................ 13
5 How to Manage UM Services ............................................................................................... 14

5.1 Associate Active Directory Windows User with Provisioning Service ............................. 14
5.2 Associate User with UM Service..................................................................................... 15
6 How to Perform Binding / Unbinding Commands ............................................................. 16

6.1 Attach Agent ................................................................................................................... 16
6.2 Join Server...................................................................................................................... 17
6.3 Unjoin Server .................................................................................................................. 18
6.4 Retrieve Fingerprint ........................................................................................................ 19
7 How to Upgrade UM Entities................................................................................................ 20

7.1 Upgrade Domain............................................................................................................. 20
8 How to Delete UM Configuration ......................................................................................... 21

8.1 Delete Configuration ....................................................................................................... 21
9 How to Execute Import Commands .................................................................................... 22

9.1 Import Package - UMC Partially Configured ................................................................... 22
10 How to Manage Whitelist Entries ...................................................................................... 23

10.1 Create Whitelist Entry ................................................................................................... 23
10.2 List Whitelist Entries...................................................................................................... 24
10.3 Remove Whitelist Entry................................................................................................. 24
11 How to Manage Plugins...................................................................................................... 26

11.1 Register Custom Plugin ................................................................................................ 26
11.2 Register Cookie Adapter ............................................................................................... 27
11.3 List Registered Plugins ................................................................................................. 28
11.4 Deregister Plugin........................................................................................................... 29
User Management Component 1.9.1 - UMCONF User Manual

iii
A5E39179378-AD
12 How to Manage Logs .......................................................................................................... 31
12.1 Archive logs .................................................................................................................. 31
12.2 Extract logs ................................................................................................................... 31
13 How to Execute Commands in Interactive Mode ............................................................. 33

13.1 Launch Interactive Mode............................................................................................... 33
14 How to Execute Purge Commands ................................................................................... 34

14.1 Purge Roles .................................................................................................................. 34
15 How to Display Lists........................................................................................................... 35

15.1 Display Server List ........................................................................................................ 35
16 Error Codes ......................................................................................................................... 36

iv
A5E39179378-AD
1 UMCONF Overview
CAUTION:
• The umconf utility must be used with care. Incorrect usage can cause system
unavailability.
• Stop all of the applications that use UMC before launching umconf and making
changes to the machine configuration.
The umconf utility can be used to perform the basic configuration operations of the User Management
Component (UMC). According to the selected options (switches) and the related parameters, the utility
allows you to execute a different configuration command. The execution of the umconf utility with no
switches is identical to the execution of the utility in interactive mode ( umconf -i ).
This utility, which is distributed with UMC, is installed in the subdirectory \BIN (for example in a 64 bit
machine C:\Program Files\Siemens\UserManagement\Wow\Bin and in a 32 bit machine C:\Program
Files\Siemens\UserManagement\BIN) and must be executed from a command prompt within this
directory. The execution of umconf is only allowed by a Windows user with Administrative rights,
elevated user if User Account Control (UAC) is enabled.
UMC Basic Configuration
The basic configuration consists of:
• the User Manager Domain;

• the User Manager user with administrator role;
• the Windows user that is associated with the User Manager core service; this user must have
Administrative rights;
• the Windows user with Active Directory access rights that is associated with the provisioning
service - mandatory if you need Active Directory Provisioning.
After the first installation it is necessary to perform the configuration parameters above to run UMC on
a machine that, once configured, will be promoted to UM ring server.
Important:
We strongly suggest using the command umconf -i to perform all the configuration steps.
Configuration Options
The following options are supported:
• fresh configuration: it is the first time that you are configuring UMC;
• overwrite an existing configuration: you have already configured UMC and you want to modify
the configuration;
• upgrade an existing configuration from a previous version: you have already configured UMC,
you have installed a newer version of UMC and you have to upgrade the configuration.
The different options are offered when running umconf interactively.

5
A5E39179378-AD
2 Concepts You Need to Know About
The following concepts are the basics you need to know before you start configuring UMC:
• User Manager Domain

• User Manager User
• Built-in User Roles
• Claim Key
• User Manager Function Rights
2.1 User Manager Domain

A User Manager domain (UM domain) is a collection of computers defined by the administrator of a
network that shares a common directory database. A UM domain provides access to the centralized
user accounts and group accounts maintained by the UM domain administrator.
Important:
UM domains are different entities with respect to Windows domains that are defined at
operating system level.
UMC Computer Roles
In a typical UMC scenario there are three computer roles:
• UM ring server: the owner of the UM configuration, which is responsible for managing the
domain, and provides full implementation of authentication and user management features. The
priority ring server is the one which is configured first, running the umconf utility. If more than
one ring server is available, if you unjoin the priority ring server, the system dynamically elects a
new priority ring server.
• UM server: provides full implementation of authentication features, the UM server is in
degraded mode if it is not connected to any UM ring server.
• UM agent: works as a client of the UM server/UM ring server to which it is attached, which can
be used to run an application developed using the UMC API. See the User Management
Component API SDK Developer Manual for more details. In order to import Windows Local
Users, see Importing a Windows Local User on an Agent in the UMC Installation Manual.
Important:
Engineering operations are not allowed on the UM Agent except for encryption
enablement.

6
A5E39179378-AD
2.2 User Manager User
CAUTION:
If you want to manage Active Directory users, the UM ring server and the UM server
machines have to be joined to the AD Windows domain.
2.2 User Manager User

A User Manager user (UM user in what follows) is a user in the User Manager Component database,
identified by a user name. Note that UM users are different entities with respect to Windows users,
which are defined at operating system level.
Custom attributes can be associated with UM users. Example of custom attributes are common user
properties such as phone number, department, and so on.
To apply Secure Application Data Support (SADS), access to encrypted application data can be
granted to authorized users to allow them to decrypt it using specific Subject Keys.
UM User Types
You can distinguish three types of UM users:
• users created from scratch in UMC or created via csv file;

• Windows local users that are imported into UMC (via umx): in this case the user name follows
the pattern <machineName>\<localUserName>;
• Active Directory users that are imported into UMC (via umx or via Web UI): in this case the
user name follows the pattern <ADdomainName>\<ADuserName>.
UM User Passwords
Users created within UMC have also an associated password. Empty passwords are not allowed.
Users imported from Windows authenticate against Windows and do not have a UMC password.
Imported Windows local users authenticate only locally against Windows on the machine where they
are present. They can be used only for configuration purposes, for instance to be associated with a
Windows service running on the machine.
Offline Users
When you create a UMC user you can flag the user as offline. UMC provisioning service checks if the
offline user exists in Active Directory:
• if the user is present, user data are synchronized and the user becomes online,
• otherwise the user remains offline.
Important:
Users created as offline are enabled by design: they can therefore perform the actions
allowed by their function rights.

7
A5E39179378-AD
2.3 Built-in User Roles
The user name of offline users must follow the AD pattern <domainName>\<ADuserName>. They do
not have a UMC password, as they cannot authenticate until they become online. The User Security
Identifier (SID, see Microsoft Documentation on Security Identifiers for more details) property is set to a
default value (S-1-0-0) that is synchronized with the actual AD value by the UMC provisioning service.
Users are also flagged offline if they are deleted from AD. In this case users are permanently deleted
from UMC database after an amount of time that can be configured (default is12 hours). See the
additional provisioning configuration in the User Management Component Installation Manual for more
details.
2.3 Built-in User Roles

A User Manager role groups a set of function rights. Function rights are the capabilities to perform
operations. They are associated with roles so that the set of UM users with a specific UM role is
allowed to perform the set of operations associated with it. UM roles can be associated with UM users
or with UM groups so that all the users belonging to such groups inherit the UM role function rights.
UM roles are used to define the function rights within UMC, for instance, to define whether a user can
configure UMC or not.
The following roles are automatically created by the system while configuring UMC:
• Administrator: built-in "root" role, can perform any operation. The user that has this role is a
root user that can perform any operation. This role cannot be associated with any group. It can
be associated with a user if the user performing the association has in turn the Administrator
role. The Administrator role cannot be deleted. Only users having the Administrator role can
modify other users having this role.
• UMC Admin: can manage users, groups and all the other UMC entities.
• UMC Viewer: can access the user management configuration without making modifications.
2.4 Claim Key

A claim is a statement that one subject, such as a person or organization, makes about itself or
another subject. The subject making the claim or claims is the provider. We use this mechanism to
provide web authentication. When the user authenticates himself against the identity provider, it
receives a claim. This claim is signed using the private claim key. Once a relying party needs to verify
the claim, it uses the corresponding public claim key (previously installed on the relying party). It is up
to the relying party how this public claim key is installed.
2.5 User Manager Function Rights

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

8
A5E39179378-AD
2.5 User Manager Function Rights
Name Description
UM_ADMIN Allows you to display the UMC database data and to configure the UMC
database, that is to create users, groups and so on, to import and export data
via file, to register UMC station clients. This function right allows you to execute
all umx commands.
UM_VIEW Allows you to display the UMC database data related to users, groups, roles
and account policies.
UM_RESETPWD The user can reset the password of another user. The user must also have
associated the UM_VIEW function right.
UM_UNLOCKUSR The user can unlock any other user. The user must also have associated the
UM_VIEW function right.
UM_ATTACH The user can attach a machine to a UM domain, the machine is promoted to the
UM agent role.
UM_JOIN The user can promote a machine to a UM server role. If the machine is not yet
attached to the UM domain, it is attached. This function right incorporates the
UM_ATTACH function right.
UM_RESETJOIN The user can downgrade a machine from the UM ring server or UM server role
to the UM agent role.
UM_IMPORT The user can import the UM Configuration via package. The user must also
have associated the UM_VIEW function right.
UM_EXPORT The user can export the UM Configuration into a package. The user must also
have associated the UM_VIEW function right.
UM_BACKUP The user can back up the UM Configuration (Full backup). This function right is
not used, as the functionality controlled by it has not yet been implemented.
UM_EXPORTCK The user can export Claim Key. This function right is not used, as the
functionality controlled by it has not yet been implemented.
UM_EXPORTDK The user can export Domain Key. This function right is not used, as the
UM_RA Login from Remote Authentication. This function right is not used, as the
UM_RINGMNG The user can promote a machine to a UM ring server role. If the machine is not
yet attached to the UM domain, it is attached.
UM_ADSYNC The user can perform the background AD provisioning synchronization.
UM_VIEWELG The user can display event logging data. The user must also have associated
the UM_VIEW function right.
UM_CLAIMAUTH The user can create an identity from a valid claim.
UM_REGCLIENT The user can register UMC station clients.

9
A5E39179378-AD
3 How to Display a Summary of UMCONF Commands
The following command can be used to display a summary of UMCONF commands:
• Help
3.1 Help
This command displays a brief summary of the different commands with their parameters and
switches.
Syntax
umconf -h

10
A5E39179378-AD
4 How to Create UM Entities
The following commands can be used to create UMC entities:
• Create Domain
• Create UM Administrator User
• Create Claim Key
4.1 Create Domain

This command creates a UM Domain named as the input parameter if no domain exists. If a domain
has already been defined, use the -f switch to overwrite the existing domain. If you are working with a
distributed scenario with an active firewall, the inbound and outbound connections through the 4002
port must be allowed. The command creates also the private claim key, which is necessary for correct
system functioning.
CAUTION:
Overwriting an existing domain can cause possible data loss.
Syntax
umconf -c -d name [-f]
Parameters
• name is the string representing the UM Domain name, only alphanumeric characters are
allowed.
Switches
Switch Description
-f Forces the creation of a new UM Domain. If a domain with the same name is present it is
overwritten.
Example #1
umconf -c -d mydomain

11
A5E39179378-AD
4.2 Create UM Administrator User
4.2 Create UM Administrator User

This command creates the UM Administrator user. This user can be created only once.
CAUTION:
Using umconf you can create only one UM user with Administrator role and neither the
user nor the password can be changed. The password can be changed via umx
command or via Web UI.
General Recommendations
It is strongly recommend that you comply with the password policies of your organization in order to
grant password strength for the UM Administrator user. For example, a password policy may impose
that your password meets the following requirements:
• be at least 8 characters long;

• contain characters from three of the following four categories:
– uppercase characters of European languages (A through Z, with diacritic marks, Greek and
Cyrillic characters);
– lowercase characters of European languages (a through z, sharp-s, with diacritic marks,
Greek and Cyrillic characters);
– base 10 digits (0 through 9);
– nonalphanumeric characters: ~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/
When creating the UM Administrator User, if you are using the command via script, add a warning that
suggests to insert a password that complies with the password policies of your organization.
Syntax
umconf -c -u name -p password
Parameters
• name is the string representing the user name, only alphanumeric characters are allowed.
• password is the password associated to the user. An empty password is not accepted.
Example #1
umconf -c –u administrator -p 123

12
A5E39179378-AD
4.3 Create Claim Key
4.3 Create Claim Key

This command creates a new private claim key and generates the corresponding public key. The new
private claim key becomes the current one used by the Identity Provider to sign the claims provided to
the relying parties.It can be run only on a ring server that is master. This command cannot be run on a
master ring server machine that is running in safe mode (writing is not enabled).
The public key of the claim can be found in %programdata%\Siemens\UserManagement\CERT\CLAIM

and the filename is key.pub. The key can be exported. During the create domain operation a claim key
is created, this new claim key overwrites the existing one. If needed the relying party applications
should be updated with the new claim key.
CAUTION:
In case of a distributed scenario, once you have created a new claim key on a UM master
ring server/UM server, to align the keys, the UMCService of the other UM ring server/UM
server machine has to be manually restarted.
Syntax
umconf -c -k

13
A5E39179378-AD
5 How to Manage UM Services
The following commands can be used to associate users to UM Services:
• Associate Active Directory Windows User with Provisioning Service

• Associate User with UM Service
5.1 Associate Active Directory Windows User with Provisioning Service

This command associates the Windows user identified by the parameter name with the UM service
UPService.exe. In order to associate the Windows user with the service, the password must be
inserted as input parameter.
This Windows user must have the following rights:
• Active Directory access rights;

• write access on the UMC folder C:\ProgramData\Siemens\UserManagement\CONF or
alternatively he must belong to 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", which enables the Web UI import
user and group functionalities.
Important:
In order to disable the Active Directory provisioning, you have to set to "no" the value of
the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Siemens\User Management\
WebUI\Settings\domains_support and stop the UM service UPService.exe.
Syntax
umconf -P -u name -p password [-f]
Parameters
• name is the string representing the user name preceded by the domain.
• password is the password associated with the user.
Switches
Switch Description

14
A5E39179378-AD
5 How to Manage UM Services
5.2 Associate User with UM Service
-f If the Provisioning Service is running and has been already configured, this switch allows
you to overwrite the existing configuration.
5.2 Associate User with UM Service

This command associates the Windows user identified by the parameter name with the UM service
UMCService.exe. In order to associate the Windows user with the service, the password must be
given as input parameter. This user must either be either in the UM Service Accounts group or have
Administrative rights. In case you want to associate a built-in Windows local user, you have to use the
Windows Services configuration tool.
Syntax
umconf -s -u name -p password [-f]
Parameters
• name is the string representing the user name preceded by the domain. If the user is local, the
name must be preceded by the string ".\" or machinename\. For Example: .\administrator,
mydomain\myuser.
• password is the password associated with the user.
Switches
Switch Description
-f If the services are running and have been already configured, this switch allows you to
overwrite the existing configuration.

15
A5E39179378-AD
6 How to Perform Binding / Unbinding Commands
The following commands can be used to perform binding or unbinding actions:
• Attach Agent
• Join Server
• Unjoin Server
• Retrieve Fingerprint
6.1 Attach Agent

This command attaches a machine to a UM domain and promotes it to the UM agent role. All the
parameters of the command are optional. If a parameter is not inserted when launching the command,
you will be prompted to insert it. The serviceUserName and servicePassword parameters are an
exception to this behavior: if not inserted the default is the built-in Windows user Local System.
The command installs the network and machine certificates on your machine. In presence of an active
firewall, the inbound and outbound connections through the 4002 port must be allowed. In an agent
machine you can run an application developed using the UMC API, see the User Management
Component API SDK Developer Manual for more details.
Syntax
umconf -a [-f] [-c computerName] [-u userName] [-p password] [-s

serviceUserName servicePassword] [-v] [-fp fingerprint]
Parameters
• computerName is the name of one of the UM ring servers or UM servers of the domain you
want to be attached to.
• userName is the name of a UM user having the UM_ATTACH function right or the
Administrator role.
• password is the password of the UM user associated with the parameter userName.
• serviceUserName is the name of a Windows Local/domain user (who is either a member of the
UM Service Accounts group or has Administrative rights) that you want to associate with the
User Manager services.
• servicePassword is the password of the Windows user associated with the parameter
serviceUserName.
• fingerprint is the fingerprint of the UMC domain.

16
A5E39179378-AD
6.2 Join Server
Switches
Switch Description
-f If the machine has already been configured, the existing configuration is overwritten.
-v If this switch is present, the installation of the certificates is not interactive. The -v switch is
mandatory if the fingerprint is specified.
6.2 Join Server

This command promotes the machine to a UM server or UM ring server machine. If the machine is not
yet attached to the UM domain, the command attaches it. All the parameters of the command are
optional. If a parameter is not inserted when launching the command, you will be prompted to insert it.
The serviceUserName and servicePassword parameters are an exception to this behavior: if not
inserted the default is the built-in Windows user Local System.
The command installs:
• the network and machine certificates on your machine;

• the ticket and claim keys.
In presence of an active firewall, the inbound and outbound connections through the 4002 port must be
allowed.
CAUTION:
Consider that if you have configured the AD provisioning on the priority ring server you
must configure it also in the machine you are joining. See the -b switch below to exclude
the AD provisioning configuration. If you want to use this command via script, the use of -
b is mandatory and to configure the provisioning you have to use the umconf command to
associate the Active Directory Windows user with the Provisioning Service.
Syntax
umconf -j [-f] [-m serverType] [-c computerName] [-u userName] [-p password]
[-s serviceUserName servicePassword] [-v][-b] [-fp fingerprint]
Parameters
• serverType determines the type of the server that will be joined to the ring:
– 0 the machine will be a UM server, in this case the provisioning is not configured;
– 1 the machine will be a UM ring server.
• computerName is the name of one of the UM ring servers of the domain you want to be joined
to.

17
A5E39179378-AD
6.3 Unjoin Server
• userName is the name of a UM user having the UM_RINGMNG function right (to create a UM
ring server) or UM_JOIN function right (to create a UM server) or having the Administrator
role. For more details see User Manager Function Rights.
• serviceUserName is the name of a Windows Local/domain user (who is either a member of the
UM Service Accounts group or has Administrative rights) that you want to associate with the
User Manager services.
• servicePassword is the password of the Windows user associated with the parameter
serviceUserName.
• fingerprint is the fingerprint of the UMC domain.
Switches
Switch Description
-f Forces the services stop.
-m This switch determines the type of server that will be joined to the ring:
• 0 the machine will be a UM server;
• 1 the machine will be a UM ring server.
-v If this switch is present, the installation of the certificates is not interactive. The -v switch is
mandatory if the fingerprint is specified.
-fp If the switch -v and -fp are present the fingerprint specified is used for validation.
-b The Active Directory provisioning configuration is not performed. This switch is relevant only
for UM ring server configuration. In case of UM server the provisioning is never configured.
6.3 Unjoin Server

This command downgrades a machine having the UM ring server/UM server role to a UM agent role.
The parameters userName and password of the command are optional. If the parameter is not inserted
when launching the command, you will be prompted to insert it, whereas, if you do not insert the
parameter computerName, by default the command is executed for the machine on which you are
launching it. If you unjoin a priority ring server, the system dynamically elects a new priority ring server.
In presence of an active firewall, the inbound and outbound connections through the 4002 port must be
allowed.
CAUTION:
If you perform the unjoin remotely (parameter computerName is present) of a machine

that is disconnected from the network and the unjoined machine returns connected after a
while, you have to delete the UMC configuration before joining it again.

18
A5E39179378-AD
6.4 Retrieve Fingerprint
Syntax
umconf -u [-u userName] [-p password] [-c computerName] [-f]
Parameters
• userName is the name of a UM user having the UM_RESETJOIN function right or having the
Administrator role.
• computerName is the name of the machine having the UM ring server/UM server role that you
are unjoining. This parameter must be used only if the UMC services of the machine you are
running the command cannot communicate with the UMC services of the machine you are
unjoining. This happens for instance when the unjoining machine is no more available.
Switches
Switch Description
6.4 Retrieve Fingerprint

This command retrieves the fingerprint (net id) of the UMC domain from the specified computer. To
obtain the fingerprint from a configured machine for a machine which has not been configured, the [-c
computerName] parameter can be used. If you do not specify the computer name, the fingerprint is
retrieved locally.
Syntax
umconf -fingerprint [-c computerName]
Parameters
• computerName is the name of the machine from which you want to obtain the fingerprint.

19
A5E39179378-AD
7 How to Upgrade UM Entities
The following command can be used to upgrade a UM domain:
• Upgrade Domain
7.1 Upgrade Domain

This command upgrades an existing UM Domain. It can be used after installing UMC on a machine
where a previous version was installed and configured.
CAUTION:
We strongly suggest to use the command umconf -i to perform all the upgrade steps that
include this domain upgrade operation.
Syntax
umconf -U [-f]
Switches
Switch Description

20
A5E39179378-AD
8 How to Delete UM Configuration
The following commands can be used to delete a UM configuration:
• Delete Configuration
8.1 Delete Configuration

This command deletes UMC configuration, restoring the system as if it was just installed. The
command has to be run after the UMC services has been stopped or using the -f switch to stop them
automatically. After executing the command, it is necessary to perform the Recycle of the following
application pools in IIS Manager:
• Web UI pool (umc_pool, for configuration via script);

• Identity Provider pool (SimaticLogonPool, for configuration via script).
In case you want to remove a UM ring server/UM server from the UMC system you have also to
perform the unjoin operation of the machine before executing this command.
CAUTION:
Performing the restart of a UMC service and/or the Recycle of the application pool can
cause service interruption.
Syntax
umconf -D [-f]
Switches
Switch Description
-f Forces the UMC services to stop before deleting all data.

21
A5E39179378-AD
9 How to Execute Import Commands
The following commands can be used to import a UM package:
• Import Package - UMC not Configured
9.1 Import Package - UMC Partially Configured

This command imports a UMC configuration via an input UMC package on a machine where the UMC
domain has been already created. To run this command the only configuration step that you must
have performed on the system is the domain creation. If UMC is configured, to import a package you
must use the corresponding umx command. For more details see the UMX User Manual.
UMC package is a UMC proprietary format, zipped and encrypted. If not inserted, you will be prompted
to insert a password for the decryption that has to be the same as the one used in the export package
umx command. For more details see the UMX User Manual.
The effects of this operation are:
• the creation of the UMC user with administrator role;

• the import of all the users, groups and roles that are part of the package.
For more information on the import/export/update package usage see the Standalone Engineering
Station Scenario in the User Management Component Installation Manual.
Syntax
umconf -I [-f] -F file -p password
Parameters
• file is the path and name of the file to be imported, for instance C:\temp\myPackage;
• password is the archive password.
Switches
Switch Description
-f Forces the services to stop.

22
A5E39179378-AD
10 How to Manage Whitelist Entries
The following commands can be used to manage Whitelist Entries:
• Create Whitelist Entry

• List Whitelist Entries
• Remove Whitelist Entry
10.1 Create Whitelist Entry

This command adds a host to the Identity Provider whitelist. If enabled, whitelisting allows you to
maintain a list of hosts that are granted some privileges. If present in the list:
• the host can call the IdP (service validation);

• the host can create an iFrame embedding the IdP (iFrame validation).
If the host is not present in the list, the call is rejected. In case of service validation, we log a warning
message on UMC event log and, if enabled, we log also a message on the Identity Provider log file.
After executing the command, for each machine where the Identity Provider is installed, it is necessary:
• to restart the UMCService;

• to perform the Recycle of the application pool of the Identity Provider (SimaticLogonPool, for
configuration via script) in IIS Manager.
CAUTION:
If you want to enable whitelisting see "How to Configure UMC" in the User Management Component
Installation Manual.
Syntax
umconf -c -w -d name
Parameters
• name is the string representing the host according to URL standard format. It can be:
– localhost;
– machine name (e.g. myMachine);

23
A5E39179378-AD
10.2 List Whitelist Entries
– internet domain name (e.g. www.myDomain.net);

– IP address (e.g. 172.23.1.48).
Example
umconf -c -w -d 175.22.3.55
Output:
domain 175.22.3.55 successfully added in whitelist.
Remember to recycle the application pool of the Identity Provider to apply all pending modifications.
10.2 List Whitelist Entries

This command lists the hosts of the Identity Provider whitelist. The only default value present in the
whitelist is the hostname of the machine; this value is added to the whitelist when the UMC domain is
created.
Syntax
umconf -l -w
Example
umconf -l -w
Example output:
whitelist contains the following domains:
localhost
myMachine
170.23.1.48
10.3 Remove Whitelist Entry

This command removes a host from the Identity Provider whitelist.
After executing the command, for each machine where the Identity Provider is installed, it is necessary:
• to restart the UMCService;

24
A5E39179378-AD
10.3 Remove Whitelist Entry
• to perform the Recycle of the application pool of the Identity Provider (SimaticLogonPool, for
CAUTION:
Syntax
umconf -d -w -d name
Parameters
• name is the string representing the host according to URL standard format. It can be:
– localhost;
– machine name (e.g. myMachine);
– domain name (e.g. www.myDomain.net);
– IP address (e.g. 172.23.1.48).
Example
umconf -d -w -d 175.22.3.55
Output:
domain 175.22.3.55 successfully removed from whitelist.
Remember to restart UMC service to apply all pending modifications.

25
A5E39179378-AD
11 How to Manage Plugins
The following commands can be used to manage UM plugins:
• Register Plugin
• Register Cookie Adapter
• List Registered Plugins
• Deregister Plugin
11.1 Register Custom Plugin

This command registers a custom plugin. It can only be executed on a master ring server.
After executing the command, for each machine where the Identity Provider is installed, it is necessary
to perform the Recycle of the application pool of the Identity Provider (SimaticLogonPool, for
CAUTION:
Performing the Recycle of the application pool can cause service interruption.
Syntax
umconf -r -u username -p password P plugin_path -d plugin_description -name

pluginname [-w web_plugin|-w2 hybrid_plugin [-cors response format]]
[-usealias][-pk public key file] [-sl security level] [-l language file]
Parameters
• userName is the name of a UM user who has the UM_ADMIN function right or the
Administrator role.
• plugin_path is the path and name of the dll plugin to be registered, for instance C:\temp\
myPlugin.dll;
• plugin_description is the string that will appear in the drop-down menu on the right of the Idp
login page on the client machine;
• plugin_name specifies the unique name of the plugin. Note that the following names are
reserved: iwa, pki, desktop, web, web_cors, hybrid, hybrid_cors and ":".
• response format for future use.
• securitylevel defines the type of authentication. This information is passed in the IdP claim so
that the third party application can determine the authentication security level; in UMC Web UI

26
A5E39179378-AD
11.2 Register Cookie Adapter
can only be used if the authentication is standard or strong.The security level can only be
specified for web and hybrid plugins. The possible values are:
– weak
– standard
– strong
• languagefile not used.
Switch Description
-w For future use. Specifies that the plug in is a web plugin, if this switch is used you must
use -pk, see below.
-pk For future use. Specifies a public key associated to the plugin.
-w2 For future use. Specifies that the plug in is a hybrid plugin.
- Specifies that the alias of the user is to be used instead of the username.
usealias
11.2 Register Cookie Adapter

This command registers a cookie adapter. It can be executed only on a master ring server.
CAUTION:
Syntax
umconf -r -u userName -p password -P url -d plugin_description -w -pk

public_key_path -sl securityLevel [-l languagefile]
Parameters
• userName is the name of a UM user having the UM_ADMIN function right or having the
Administrator role.
• url is the url of the cookie adapter to be registered;
• plugin_description is the string that will appear in the drop-down menu on the right of the Idp
login page on the client machine;

27
A5E39179378-AD
11.3 List Registered Plugins
• public_key_path is the public key generated at the setup of cookie-adapter

• securityLevel defines the type of authentication. This information is passed in the IdP claim so
that the third party application can determine the authentication security level; in UMC Web UI
authentication is performed in case of standard and strong. The possible values are:
– weak
– standard
– strong
• languagefile - not used.
Switches
Switch Description
-w Specifies that you are registering a cookie adapter.
-pk Specifies a public key associated to the plugin.
11.3 List Registered Plugins

This command can be be executed on any server and lists the plugins which are registered on the
master ring server, along with their:
• Plugin Uid: the unique id of the plugin which is necessary to activate plugins on clients.
• Path: the path of the plugin.
• Description: the description of the plugin.
• Class: Specifies the type of plugin: desktop, web or hybrid.
• Pub keyid: the public key id.
• Security Level: Weak, Standard and Strong, see register custom plugin for more information.
• Plugin Name: the unique the name of the plugin, this field is empty in plugins which were
created prior to UMC 1.9.1.
Syntax
umconf -l -P
Example
An example of the command output follows:

28
A5E39179378-AD
11.4 Deregister Plugin
#1 Plugin Uid: 889f1341-0260-4f77-81fd-ceadf8f56c4fPath: C:\Users\Administrator\Desktop\

Test_plugins\Bin\PluginTAF.dllDescription: Plugin Desktop Stateful Class: desktopPub keyid:Security
level: weak Plugin name: my desktop plugin #2 Plugin Uid:
3c179694-e5ed-4225-b064-eb01b981251bPath: C:\Users\Administrator\Desktop\Test_plugins\Bin\
PluginTAF2.dllDescription: Plugin Desktop Stateless Class: desktopPub keyid:Security level: weak
Plugin name:my plugin

This command deregisters a plugin on a master ring server.
CAUTION:
Syntax
umconf -dP -u userName -p password -name pluginname [-P pluginId]
Parameters
• userName is the name of a UM user having the UM_ADMIN function right or having the
Administrator role.
• pluginname is the name of the plugin alternatively you can use pluginId.
• pluginId is the position of the plugin in the list of registered plugins. See example below.
Example
If the command:
umconf -l -P
returns:#2 Plugin Uid: 5a25fc03-3bd1-479b-9b02-2dcb9f6f60f3Path: https://mymachine/

tcss_webDescription: Teamcenter Web Class: webPub keyid:
88FACEFCD6ED416BC6D516D10E09ABBBDA85FDC6Security level: strongUse alias: enabledPlugin
name: Teamcenter Web#3 Plugin Uid: 113dc9ec-ada6-4f61-b938-9bf2a50b1401Path: https://vm-
chessa/tcss_hybridDescription: Teamcenter Hybrid Class: hybrid_corsPub keyid:
88FACEFCD6ED416BC6D516D10E09ABBBDA85FDC6Security level: strongUse alias: enabledPlugin
name: Teamcenter Hybrid

29
A5E39179378-AD
pluginlist contains 2 plugins correctly registered.
the command:
umconf -dP -u myUser -p 098P@ssword! -name Teamcenter Hybrid
deregisters the Windows plugin.

30
A5E39179378-AD
12 How to Manage Logs
The following commands can be used to manage logs:
• Archive logs
• Extract logs
12.1 Archive logs

This command archives the system log folder into a UMC package. UMC package is a UMC
proprietary format, zipped and encrypted. The exported package is the input of the extract logs
command.
Syntax
umconf -log -a -f file [-p password]
Parameters
• file is the path and name of the package file, for instance C:\temp\myLogs;
• password is the package password. If not provided, the user will be prompted to insert the
password.
12.2 Extract logs

This command extracts the system logs previously archived into a UMC package. UMC package is a
UMC proprietary format, zipped and encrypted. If the password is not inserted when launching the
command, you will be prompted to insert it. The input password has to to be the same of the one used
in the archive logs command.
Syntax
umconf -log -e -f file [-p password]

31
A5E39179378-AD
12 How to Manage Logs
12.2 Extract logs
Parameters
• file is the path and name of the package file, for instance C:\temp\myLogs;
• password is the package password.

32
A5E39179378-AD
13 How to Execute Commands in Interactive Mode
The following command can be used to execute the umconf utility in interactive mode:
• Launch Interactive Mode
13.1 Launch Interactive Mode

This command executes the umconf utility in interactive mode. The following configuration steps are
performed launching the interactive mode:
• the User Manager Domain;

• the User Manager user with administrator role, the password for this user should be at least 8
characters long and contain characters from three of the following four categories:
– uppercase characters of European languages (A through Z, with diacritic marks, Greek and
Cyrillic characters);
– lowercase characters of European languages (a through z, sharp-s, with diacritic marks,
Greek and Cyrillic characters);
– base 10 digits (0 through 9);
– nonalphanumeric characters: ~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/
• the Windows user that is associated with the UMCService.exe service;

• the Windows user that is associated with the UPService.exe service - mandatory only if you
need to import Active Directory users via the umx tool or via the Web UI;
• the private claim key.
The following options are supported:
• fresh configuration: it is the first time that you are configuring UMC;
• overwrite an existing configuration: you have already configured UMC and you want to modify
the configuration;
• upgrade an existing configuration from a previous version: you have already configured UMC,
you have installed a newer version of UMC and you have to upgrade the configuration.
Syntax
umconf -i
Or alternatively:
umconf

33
A5E39179378-AD
14 How to Execute Purge Commands
The following command can be used to purge UM roles:
• Purge Roles
14.1 Purge Roles

This command purges the roles identifiers. Role identifiers are generated incrementally, until the
maximum value of 32600 is reached. Beyond this value it is no longer possible to insert any other new
role (regardless of the maximum roles number) until you make the purge of the roles previously
deleted.
CAUTION:
This command stops the UMCService and restarts it after the execution. The stop can
Syntax
umconf -purge -roles

34
A5E39179378-AD
15 How to Display Lists
The following commands can be used to display the list of servers:
• Display Server List
15.1 Display Server List

This command displays the list of the servers with their machine role. The command can be executed
only on a server or ring server machine.
Syntax
umconf -t
Example
umconf -t
Output
The server list contains:
servername: myname1 ring server

servername: myname2 ring server
servername: myname3 server

35
A5E39179378-AD
16 Error Codes
Value Description
0 Success.
1 The user launching the command does not have the proper administrative rights.
10 Initialization error, for instance a registry key is missing.
50 Command syntax error.
100 Command execution error.

36
A5E39179378-AD

UMCONF User Manual

Uploaded by

Copyright:

Available Formats

UMCONF User Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

UMCONF User Manual

Uploaded by

Copyright:

Available Formats

s Contents

User Management Component 1.9.1 How to Upgrade UM Entities 7

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

Siemens AG A5E39179378-AD Copyright © Siemens AG 2018

3 How to Display a Summary of UMCONF Commands ........................................................ 10

4 How to Create UM Entities ................................................................................................... 11

5 How to Manage UM Services ............................................................................................... 14

6 How to Perform Binding / Unbinding Commands ............................................................. 16

7 How to Upgrade UM Entities................................................................................................ 20

8 How to Delete UM Configuration ......................................................................................... 21

9 How to Execute Import Commands .................................................................................... 22

10 How to Manage Whitelist Entries ...................................................................................... 23

11 How to Manage Plugins...................................................................................................... 26

User Management Component 1.9.1 - UMCONF User Manual

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

14 How to Execute Purge Commands ................................................................................... 34

15 How to Display Lists........................................................................................................... 35

16 Error Codes ......................................................................................................................... 36

User Management Component 1.9.1 - UMCONF User Manual

UMC Basic Configuration

The basic configuration consists of:

• the User Manager Domain;

The following options are supported:

The different options are offered when running umconf interactively.

User Management Component 1.9.1 - UMCONF User Manual

• User Manager Domain

2.1 User Manager Domain

UMC Computer Roles

In a typical UMC scenario there are three computer roles:

User Management Component 1.9.1 - UMCONF User Manual

2.2 User Manager User

You can distinguish three types of UM users:

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

User Management Component 1.9.1 - UMCONF User Manual

2.3 Built-in User Roles

2.4 Claim Key

2.5 User Manager Function Rights

User Management Component 1.9.1 - UMCONF User Manual

UM_ADSYNC The user can perform the background AD provisioning synchronization.

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

UM_REGCLIENT The user can register UMC station clients.

User Management Component 1.9.1 - UMCONF User Manual

User Management Component 1.9.1 - UMCONF User Manual

4.1 Create Domain

Overwriting an existing domain can cause possible data loss.

umconf -c -d name [-f]

User Management Component 1.9.1 - UMCONF User Manual

4.2 Create UM Administrator User

• be at least 8 characters long;

umconf -c -u name -p password

umconf -c –u administrator -p 123

User Management Component 1.9.1 - UMCONF User Manual

4.3 Create Claim Key

The public key of the claim can be found in %programdata%\Siemens\UserManagement\CERT\CLAIM

User Management Component 1.9.1 - UMCONF User Manual

• Associate Active Directory Windows User with Provisioning Service

5.1 Associate Active Directory Windows User with Provisioning Service

This Windows user must have the following rights:

• Active Directory access rights;