Configuring DirX Identity

This chapter describes how to configure DirX Identity on all available platforms. The Configurator serves different purposes:

  • It can perform a complete initial configuration. (This part is automatically presented after an installation on Windows).

  • The customer can perform a reconfiguration at any time; for example, to create a new domain.

  • During un-installation or when executed by user request, it can perform an un-configuration.

Starting the Configuration

The configuration is based on the content in the file:

install_path/configuration.ini

This file determines the components and agents to configure and contains the passwords for a silent configuration.For details about the configuration.ini file see "Silent Configuration / Un-configuration".

Windows

  • With the operating systems Windows 2008 and Windows 7 (Vista), Microsoft introduced a new technique called User Access Control (UAC) to "elevate" a user "on the flow" from a standard to an administrative user by letting a standard user "explicitly confirm" when trying to perform an administrative task, for example writing to the registry. Because this explicit confirmation cannot be performed at several situations while the Configurator is running, either put the user who is running the Configurator to the local administrator group, start the InitialConfiguration.bat / Configuration.bat with "run as Administrator" or disable UAC during configuration.
UNIX

  • Normally, superuser permissions are required for starting the configuration. However, if the conditions described in "Determining the Account for Configuration on UNIX platforms" are satisfied, then a login as the DirX Identity installation account is sufficient for starting the configuration. However, if you have once started the configuration as superuser, then subsequent runs of the configuration / un-configuration must be performed as superuser, too.

  • For Linux platforms only: Setting and exporting the environment variable LD_ASSUME_KERNEL (value 2.4.19) is no longer required and is incorrect. Undo this setting if it is still active in your environment.

Initial Configuration

After finishing the installation, you must configure DirX Identity with the DirX Identity Initial Configuration Wizard.

Windows Platforms

You can start the initial configuration wizard on Windows platforms at any time:

Run Start → Programs → DirX Identity → Initial Configuration

This tool is located on Windows platforms in install_path*\bin*. The syntax of the tool is as follows:

InitialConfiguration.bat

At the end of an update installation, the Initial Configuration Wizard starts automatically.

Linux Platforms

You must start the initial configuration wizard on Linux platforms by hand.

Note: This tool is located in install_path/bin:

InitialConfiguration.sh

Configuration

You can re-configure DirX Identity at any time; for example, to create a new domain.

Windows Platforms

You can start the reconfiguration wizard via:

Run Start → Programs → DirX Identity → Initial Configuration

Or if you only want to re-configure the Java-based Server and / or Web Center:

Run Start → Programs → DirX Identity → Configuration

The configuration tool is located in install_path\bin. The syntax of the tool is as follows:

Configuration.bat type mode [Java-based_server_configuration_file]

where

type is one of the following values

  • InitialConfiguration - Performs all initial configuration steps.

  • Configuration - (default value) Performs configuration steps for the Java-based Server and / or the Web Center.

  • UnConfiguration - Performs an un-configuration.

mode is one of the following values:

  • normal - (default value) The configuration runs in interactive mode.

  • silent - The configuration runs in silent mode. (See "Silent Configuration / Un-configuration" for details.)

Java-based_server_configuration_file is the name of the configuration file containing the properties of the Java-based Server to be configured. (See "Java-based Server" for details about this file.) You can specify only one Java-based_server_configuration_file. It must be located in install_path*/bin*. If you want to specify this parameter, you must specify all parameters in the correct order. You must perform the configuration tool for each Java-based Server you want to configure.

If Java-based_server_configuration_file is specified, the Configurator reads the Java-based Server properties from there. If no such file is specified, the values are read from configuration.ini as usual. The configured values - in normal mode, the user can change the pre-configured values - are written back to the configuration.ini file. The optional Java-based Server configuration file is only used for reading but never for writing.

If you want to run the configuration with parameters, run it as administrator in a command prompt window or from a shell script.

Linux Platforms

You can start the re-configuration wizard on Linux platforms by hand.

This tool is located in install_path/bin:

Configuration.sh

Un-Configuration

Un-configuration can be performed before un-installation.

The un-configuration process performs the following tasks:

  • Work Path and Status Path Deletion

Removes all files in the work and status folders.

  • DirX Identity C++-based Server for Un-configuration

Unregisters the DirX Identity agents from the connectivity configuration directory and removes the C++-based Service on Windows platforms.

  • DirX Identity Java-based Server for Un-configuration

Removes the Java-based Service on Windows platforms.

  • Web Center Un-configuration for Tomcat

Uninstalls the Web Center component from the Tomcat installation folder.

  • Web Center for Password Management Un-configuration for Tomcat

Uninstalls the Web Center for Password Management component from the Tomcat installation folder.

Windows Platforms

Un-configuration is requested during un-installation.

Manual un-configuration should not be necessary but can be performed.

This tool is located in install_path\bin:

UnConfiguration.bat

Linux Platforms

You must start the de-configuration wizard on Linux platforms by hand.

Note: This tool is located in install_path/bin:

UnConfiguration.sh

If you have integrated the DirX Identity start/stop scripts into the Linux operating system (see the section "Integrating Start/Stop Scripts into the Linux Operating System"), you must undo these integration actions (see the subsection "Undoing the Integration") before un-installing the product.

Using the Configurator

This section provides information about all possible steps of the Configurator.Some steps contain exceptions for the different modes (initial configuration, configuration, un-configuration).

After startup, the Configurator shows the welcome screen.

Welcome Dialog

The first comment line provides information about the configuration type (initial configuration or configuration mode).

  • Click Next to go to the next step.

The configuration wizard is built similar to the DirX Identity wizards, with all steps shown on the left side and title and help information shown on the right side.

Buttons at the bottom allow you to navigate in the wizard. You can use Next to step forward and Previous to step backwards. Cancel allows you to end the wizard operation at any time and Finish is enabled at the point where parameter settings are complete (all buttons in the navigation pane are green).

Configuration Options

The set of options for the Configuration Options dialog is:

  • Connectivity Schema and Data Configuration

This component extends the LDAP directory server’s schema with the DirX Identity connectivity data model and imports the connectivity configuration as follows:

  • Creates the DirX Identity object classes

  • Creates the DirX Identity attribute types

  • Creates the DirX Identity name forms

  • Creates access control and subschema subentries within the administrative areas

Within the administrative areas, subentries for access control and subschema are created. (See the section "Schema and Content Handling" for details.)

This configuration component has the following prerequisite:

  • The directory server must be present on the local machine and running.

The configuration procedure deletes and adds objects classes. If you have already used these object classes and have extended them, the content could be lost. In this case, you cannot use the delivered script. You must update the schema by hand.

  • Provisioning Schema and Data Configuration

This component configures the provisioning schema and the system domain.

The Directory Schema extension extends the LDAP directory server’s schema with the Provisioning data model, as follows:

  • Creates the Provisioning object classes

  • Creates the Provisioning attribute types

  • Creates the Provisioning name forms

  • Creates an administrative area for the Provisioning system domain

  • Creates access control and subschema subentries within the administrative area

Within the administrative area, subentries for access control and subschema are created.

This configuration component has the following prerequisites:

  • The directory server must be present on the local machine and running.

  • The Connectivity Schema and Data Configuration must already exist or you must select the option.

  • ActiveMQ Message Broker Configuration

This component configures the DirX Identity Message Broker (based on ActiveMQ) and starts it if the flag to start it after configuration is checked. This configuration component has the following prerequisites:

  • The Connectivity Schema and Data Configuration must have been performed or you must select the option.

  • C++-based Server Configuration

This component configures the DirX Identity C++-based Server and starts it if the flag to start it after configuration is checked. It adds configuration information about the installed agents to the database containing the connectivity schema.

This configuration component has the following prerequisites:

  • The Connectivity Schema and Data Configuration must already exist, or you must select the option.

  • Domain Configuration

This component performs the configuration of a customer domain and/or the sample domain. If you select this step, the step Provisioning Schema and Data Configuration is automatically selected.

This configuration component has the following prerequisite:

  • The directory server must be present on the local machine and running.

Here is more detailed information about the sample domain and the customer domain:

Sample Domain:

The sample domain My-Company is created. The set of installed data objects is a useful starting point to play with users, privileges, target systems and policies. The roles are not yet resolved to group memberships and account objects are not provided.

Customer Domain:

The customer domain with the provided name is created. An administrative area is created automatically.

During a single run of the Configurator, only one customer domain can be configured. For each customer domain, the initial folder structure, the configuration objects and some policies are provided.

If the customer domain already exists, this task replaces the configuration and system default data of the domain: default object descriptions and property page descriptions, system rules and operations. It does not modify the customer extensions.

For easy access, DomainAdmin profiles to access the domain via the DirX Identity Manager are created automatically if a Manager is or will be configured on this machine.

This configuration component has the following prerequisites:

  • The directory server must be present on the local machine and running.

  • The Provisioning Schema and Data Configuration option is automatically selected then and is disabled for deselection.

  • Java-based Server Configuration

This component configures a DirX Identity Java-based Server to a specific domain and starts it if the flag to start it after configuration is checked.

This configuration component has the following prerequisites:

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

  • A Domain Configuration must already exist or you must select the option.

  • Server Admin (including Supervisor-J) Configuration

This component deploys the Server Admin files from install_path/ha/serverAdmin.org to the embedded Java server tomcat to install_path/ids-j-domain-Sn/tomcat/webapps/serverAdmin.

This configuration component has the following prerequisite:

  • The Java-based Server Configuration option is automatically selected and is disabled for de-selection.

  • Manager Configuration

This component creates and customizes the manager profile files in the installation directory install_path/GUI/profiles.

This configuration component has the following prerequisites:

  • The Connectivity Schema and Data Configuration must already exist or you must select the option.

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

  • Web Center Configuration

This component configures the DirX Identity Web Center for Tomcat.

This configuration component has the following prerequisites:

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

  • Web Center for SAP NetWeaver Configuration

This component configures the DirX Identity Web Center for SAP NetWeaver and can only be chosen as an alternative to the Web Center Configuration.

You must perform additional configuration steps manually.

  • Web Center for Password Management Configuration

This component configures the DirX Identity Web Center for Password Management for Tomcat.

This configuration component has the following prerequisites:

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

  • Provisioning Web Service Configuration

This component configures the DirX Identity Provisioning Web Service for Tomcat.

This configuration component has the following prerequisites:

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

  • Identity REST Service Configuration

This component configures the DirX Identity REST Service for Tomcat.

This configuration component has the following prerequisites:

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

  • Business User Interface Configuration

This component configures the DirX Identity HTML5 Business User Interface for Tomcat.

This configuration component has the following prerequisites:

  • The Provisioning Schema and Data Configuration must already exist or you must select the option.

Select the components or options you want to configure and click Next.

Note: The number of steps on the left side will be different depending on the options you have selected.

Linux Platforms

If C++-based Server Configuration is selected during an update configuration or un-configuration, the Configurator now checks the C++-based DirX Identity server. When the server is running, the Configurator asks you if it should stop the server. If your answer is "No", you must stop the server before you can continue with the configuration. Otherwise the Configurator will stop the server.

DirX Directory Server for Connectivity

For Connectivity Schema and Data Configuration, the dialog asks you for the necessary properties of the directory server.

  • Enter the host name and the port number of the directory server.

  • Select the path where the directory server is installed.

  • Check Use SSL if you want to connect with SSL to the directory server where the Connectivity database resides. Make sure you entered the appropriate port then.

If you are using SSL for the first time to bind to the directory server with the Configurator, you must import the test CA certificate of the LDAP server into the trust store dxi_java_path/lib/security/cacerts of the JRE for DirX Identity before you run the Configurator. (See the chapter "Setting up the Java-based Configuration Wizard" in the DirX Identity Connectivity Administration Guide for details.) If DirX Identity was not installed before and you cannot use the DirX Identity Manager to import certificates into trust stores, then you must use keytool.exe under dxi_java_home/bin to import the certificate.

For Connectivity Schema and Data Configuration, the dialog asks you for the name and password of the administrator who has the right to make changes to the directory server schema. You can:

  • Click Next to use the default directory administrator. The default password is dirx.

  • Enter the name and password of the directory administrator, and then click Next.

If Connectivity Schema and Data Configuration is selected, the Configurator now checks the directory path. A warning is displayed when the path is incorrect. You can enter the correct path and try again or cancel the configuration. The Configurator then tries to connect to the directory server with the administrator account that you specified. If this action fails, an error dialog is displayed. You can correct the address and/or the credentials and try again or cancel the configuration.

DirX Directory Server for Provisioning

For Provisioning Schema and Data Configuration, the dialog asks you for the necessary properties of the directory server.

  • Enter the host name and port number of the directory server.

  • Select the path where the directory server is installed.

  • Check Use SSL if you want to connect with SSL to the directory server where the Provisioning database resides. Make sure you entered the appropriate port then.

If you use SSL the first time for binding to the directory server with the Configurator, you must import the CA certificate of the LDAP server into the truststore dxi_java_path/lib/security/cacerts of the JRE for DirX Identity before you run the Configurator. (See the chapter "Setting up the Java-based Configuration Wizard" in the DirX Identity Connectivity Administration Guide for details.) If DirX Identity was not installed before and you cannot use the DirX Identity Manager to import certificates into truststores, you must use keytool.exe under dxi_java_home/bin to import the certificate.

For Provisioning Schema and Data Configuration, the dialog asks you for the name and password of the administrator who has the right to make changes to the directory server schema. You can:

  • Click Next to use the default directory administrator. The default password is dirx.

  • Enter the name and password of the directory administrator, and then click Next.

For Provisioning Schema and Data Configuration, the Configurator now checks the directory path. A warning is displayed when the path is incorrect. You can enter the correct path and try again or cancel the configuration. The Configurator then tries to connect to the directory server with the administrator account that you specified. If this fails, an error dialogs is displayed. You can correct the address and/or the credentials and try again or cancel the configuration.

DirX Identity Administrators

This dialog asks you for the passwords of the DirX Identity administrators.

The admin account is used to access the DirX Identity configuration database during configuration runs. If the DirX Identity configuration database does not yet exist in the directory, the Configurator will store the given password in the directory for future logins.

  • Enter the password of the administrator admin (the default password is dirx).

The DirX Identity C++-based Server and the supervisor use the server_admin account to access the directory. If the account does not yet exist in the directory, the Configurator will store the given password in the directory for future logins.

  • Enter the password of the administrator account server_admin (the default password is dirx).

The SystemDomain account is used to access the DirX Identity provisioning database. If the DirX Identity provisioning database does not yet exist in the directory, the Configurator will store the given password in the directory for future logins.

The Configurator now tries to connect to the LDAP directories with the given credentials. If this fails, a warning is displayed. Possible reasons are:

  • The directory address is invalid or the directory server is not running. Correct the given address or start the directory server and try it again.

  • The DirX Identity database does not yet exist in the directory (this is the case during a new installation). You can ignore the warning.

  • The DirX Identity database already exists in the directory. The password for the displayed user is not valid. You must go back, correct the password and try it again.

System-wide Configuration

This dialog is only displayed when either ActiveMQ Message Broker or Java-based Server or C++-based Server is selected.

If you want to activate the High Availability functionality system wide, which is selectable only if the HA license is installed:

  • Check Activate High Availability.

If you want to use secure connections to the ActiveMQ Messaging Server(s) and to the Java Servers running in the system:

  • Check Use SSL.

SSL cannot be set on new installations because some certificate and keystore- and truststore-generating scripts as described in the chapter "Securing Identity Server Connections with SSL" in the DirX Identity Connectivity Administration Guide must be run first. Also the Connectivity schema and data step must be selected to be able to select or deselect SSL.

When preparing the above mentioned scripts for generating certificates and key and trust store, be sure that you specify the local machine name (hostname) the same way - either in the short form or in the fully-qualified name form, which is recommended in a wide area network - as you intend to do in the configuration steps for the ActiveMQ Message Broker, Java-based Server and C++-based Server. They all write the specified hostname into the same Connectivity system object, which must match the name contained in the server certificate for that machine.

If SSL is selected, the Configurator asks you to set:

  • Keystore Password.

The passwords are written to the install_path/ssl/password.properties file. Be sure that you specify the same passwords as you did when generating the store. In silent configuration, the keystore password is read from the property systemwide.keystore_pwd in the configuration.ini file.

If encryption mode is configured at the Connectivity Configuration object or the cn=server_admin,dxmC=DirXmetahub object contains a certificate, the Configurator asks you to set:

  • Pin for reading the private key from the server_admin object.

  • Previous Pin for reading the previous private key from the server_admin object.

The PINs are written to the install_path*/ssl/password.properties* file. Be sure that you specify the same PINs as you did when generating the certificate and private key for the Connectivity server_admin object with the dirxgenpse tool. In silent configuration, the Pin and the Previous Pin are read from the properties systemwide.pin and systemwide.previous_pin in the configuration.ini file.

If client signature is configured at the Provisioning Domain object, the Configurator asks you to set:

  • Signature Pin for reading the private key from the DomainAdmin user object.

The domain-specific signature PIN is written to the install_path/idsj-domain-Sn/private/password.properties file (if a Java-based Server is also configured in this configuration run). Be sure that you specify the same PIN as you did when generating the certificate and private key for the Provisioning cn=DomainAdmin,cn=domain_name object with the dirxgenpse tool. In silent configuration, the Signature Pin is read from the property systemwide.signature_pin in the configuration.ini file.

The password.properties file is always written in this step, no matter whether ssl, encryption or client signature is set. If one of them is not set and so the Configurator does not ask for the related password or PIN, the default value is written to the password.properties file, which is changeme for the key store password, 1234 for the Pin and the Previous Pin and 5678 for the Signature Pin.

ActiveMQ Message Broker Configuration

This dialog is only displayed when ActiveMQ Message Broker Configuration is selected.

In this dialog, you can:

  • Click Next to use the proposed values or

  • Change the proposed values for the editable fields and then click Next.

You can change:

  • The Host Name of the system this server runs on.

If SSL is used or planned to be used for the system, specify the host name in the same form - short or fully-qualified - as for generating the server certificate for this host. In a wide area network a fully-qualified host name could be required for SSL to work properly.

  • The Display Name field cannot be changed. It is either the display name of an existing Message Broker or a new Broker name. A new Broker name consists of the prefix Message Broker and the number of the Broker configured for your (possibly distributed) installation.

  • The Port for message transfer (default 61616).

  • The Secure Port for message transfer (default 61617).

  • The Admin (Web Console) Port (default 8161).

  • The JMX Port (default 10098).
    Note that the port (n+1) is also configured and used.

  • The Message repository path to be specified either as absolute path or as UNC path on a Windows system referring to a shared folder. The Configurator displays the default location install_path/messagebroker/data/kahadb or the location specified in the last configuration run.

  • The checkbox Set service start type to automatic, which is only shown on Windows Systems (default checked).

  • The checkbox Start service after configuration (default checked).

ActiveMQ Message Broker Service Account

This dialog is only displayed on Windows platforms when ActiveMQ Message Broker Configuration is selected.

The Configurator asks under which account the ActiveMQ Message-Broker service should run.

  • Enter your preferred account or use the system account.

  • Set the checkbox Set service start type to automatic (default checked).

  • Set the checkbox Start service after configuration (default checked).

  • Click Next.

Setup now checks whether the specified account is valid and has the right to create files in the directory install_path.

Note: To perform these checks, the account under which this configuration procedure runs (the account you are logged in) must have the advanced user rights "Act as part of the operating system" and "Replace a process level token". If this is not the case, the Configurator displays a message box with the text "A required privilege is not held by the account …". We recommend aborting the configuration at that point and performing this procedure:

  • Cancel the configuration.

  • Grant the required rights to the user.

  • Reboot your computer.

  • Run the DirX Identity Configurator again.

C++-based Server Configuration

This dialog is only displayed when C++-based Server is selected.

In this dialog, you can:

  • Click Next, to use the proposed values or

  • Change the proposed values for the editable fields and then click Next.

You can change:

  • The Host Name of the system the server runs on.

Note: If SSL is used or planned to be used for the system, specify the host name in the same form - short or fully-qualified - as for generating the server certificate for this host.

  • The Port for key transfer (default 1111) for secure connections between the DirX Identity C++-based server and the DirX Identity Java-based agents if encryption mode is to be used.

  • The Work path.

  • The Status path.

The Configurator asks you to select a work path directory and a status path directory. It displays the default locations in the fields provided.

We recommend locating the work and status path on separate disks in production environments. DirX Identity is designed to ignore a full status area disk but cannot ignore a full disk where the work area is located.

  • The Primary DirX Identity C Server checkbox (the default is checked).

This checkbox is only visible if you are configuring a C Server on a machine other than the one on which the Connectivity Database resides. If you want to configure your primary C Server to this host name, check the box. When the box is not checked, a secondary C Server is configured to this host name. When reconfiguring a primary or secondary C Server (where the server already exists in the database), be sure to set the host name to the same name as before (the suggestion is taken from the configuration.ini file) and don’t change from short to long form or vice versa, because then the C Server object is not found in the database and a new object is created, which is wrong.

C++-based Service Account

This dialog is only displayed on Windows platforms when C++-based Server is selected.

The Configurator asks under which account the DirX Identity C++-based service should run.

  • Enter your preferred account or use the system account. We recommend that you do not use the system account:

  • If you intend to set up a distributed DirX Identity environment to run distributed workflows,

  • If you define a work or status path on another machine (the system account cannot access any resources on other machines).

  • Set the checkbox Set service start type to automatic (default checked).

  • Set the checkbox Start service after configuration (default checked).

  • Click Next.

Setup now checks whether the specified account is valid and has the right to create files in the directory install_path.

To perform these checks, the account under which this configuration procedure runs (the account you are logged in) must have the advanced user rights "Act as part of the operating system" and "Replace a process level token". If this is not the case, the Configurator displays a message box with the text "A required privilege is not held by the account …". We recommend aborting the configuration at that point and performing this procedure:

  • Cancel the configuration.

  • Grant the required rights to the user.

  • Reboot your computer.

  • Run the DirX Identity Configurator again.

Domain Configuration

This dialog is only displayed in this form when Domain Configuration is selected. If it is not selected but Java-based Server - or Web Center Configuration is selected, only the part to configure a customer domain is shown.

  • Select the domain you want to use.

The sample domain is a complete and fully working example. For more information, see the DirX Identity Tutorial Guide.

The English and German health care domains are sample hospital domains with a typical medical person and role hierarchy.

For a customer domain configuration:

  • Enter the domain name.

  • The configuration process suggests a technical domain name. This name is used for creating the folder install_path/idsj-technical_domain-Sn on your machine relating to the nth Java-based Server for that domain and for service names relating to the Java-based Servers for that domain. For technical reasons, these names must consist of only alphanumerical characters (A-Z, a-z, 0-9) and/or the minus sign (-) or the underscore (). The name is also appended to the URL of the Web Center. (See chapter "Using the Web Center" in the _DirX Identity User Interfaces Guide for details.

    You may change the suggested name.

  • Enter the password of the customer domain administrator (the default password is dirx).

  • Click Next.

If the domain does not yet exist in the directory, the Configurator will store the given password in the directory for future logins.

The Configurator creates the account cn=DomainAdmin,cn=My-Company with the password dirx for the sample domain.

Java-based Server

This dialog is only displayed when Java-based Server is selected.

In this dialog, you can:

  • Click Next to use the proposed values, or

  • Change the proposed values for the editable fields and then click Next.

You can make the following changes:

  • You can select whether you want to update or create a new Java-based server from the drop-down list provided for the Server to configure field. You are not allowed to update a Java-based Server for the domain specified in Domain Configuration if that Java-based Server is already configured for another domain. For DirX Identity version 8.2A and newer, you are allowed to configure multiple Java servers per domain.

  • You can change the Host Name of the system on which the Java-based Server runs.

If SSL is used or planned to be used for the system, specify the host name in the same form - short or fully-qualified - as for generating the server certificate for this host.

  • You can change the Heap Size of the Java-based Server (default 2 GByte).

  • You can change the IdS-J Http(s) Port (default 40000).

  • You can change the IdS-J JMX Port (default 40005).
    Note that the port (n+1) is also configured and used.

  • You can change the path where the Java-based Server writes its warning and server logging files. By default, the path is ../logs. This path is also used for classloading logging and other items.

  • You can check or uncheck the Set service start type to automatic checkbox (only displayed on Windows platforms (default checked)).

  • You can check or uncheck the Start service after configuration checkbox (default checked).

Note that you cannot change the Display Name field. It is either the display name of an existing Java-based Server or, for a new Java-based Server, a proposed name consisting of the technical domain name, the number of the server configured for this domain and the host name the Java-based Server runs on (domain_name*-S*n*-*host_name).

The Configurator checks whether the configured or interactively changed values are consistent regarding value ranges, for example, for the heap size, or regarding the naming conventions for the Java-based Server name. If the values are not consistent, an error message is displayed and in case of silent configuration the Configurator is aborted.

You can turn off name checking for the host name. You may need to take this action when your host can be accessed via different names (and also if you want to use localhost). In these cases, you can deactivate the checks by setting the following line in the configuration.ini file:

IdS-J.relaxed_name_check=1

If you do so, please be careful.

Java-based Service

This dialog is only displayed on Windows platforms when Java-based Server is selected.

The Configurator asks under which account the Java-based Server service should run.

  • Enter your preferred account or use the system account.

  • The checkbox Set service start type to automatic (default checked).

  • The checkbox Start service after configuration (default checked).

  • Click Next.

Setup now checks whether the specified account is valid and has the right to create files in the directory install_path.

To perform these checks, the account under which this configuration procedure runs (the account you are logged in) must have the advanced user rights "Act as part of the operating system" and "Replace a process level token". If this is not the case, the Configurator displays a message box with the text "A required privilege is not held by the account …". We recommend aborting the configuration at that point and performing this procedure:

  • Cancel the configuration.

  • Grant the required rights to the user.

  • Reboot your computer.

  • Run the DirX Identity Configurator again.

At the end of the Java-based Service configuration step, the Configurator always saves a template file containing the Java-based Server properties. The name of this template file is Java-based_Server_Display_Name-configuration.tpl. It is saved in install_path. Here is an example of a template file:

IdS-J.heap_size=2 GByte
IdS-J.host=MC0XCNXX
IdS-J.port=40000
IdS-J.jmx_port=40005
IdS-J.protocol=http
IdS-J.log_path=../logs
IdS-J.server_name=My-Company-S1-MC0XCNXX
IdS-J.start_after_configuration=1
IdS-J.start_type_automatic=1
domain= My-Company
IdS-J-service.domain=mydomain
IdS-J-service. account=myaccount
tech_customer_domain=My-Company

For silent installation, you can specify the password of the service account with:

IdS-J-service.password=password

The name of the template file is My-Company-S1-MC0XCNXX-configuration.tpl.

You can use the Configurator tool Configuration.bat to configure several Java-based Servers automatically. For this purpose, create one configuration file for each Java-based Server in install_path/bin. You can use a template file as input for a Java-based Server configuration file. Then run the wizard for each Java-based Server and specify the name of the Java-based Server configuration file as the third parameter. (See "Configuration" for details.)

If in silent mode a customer domain is to be created or updated, the password for the domain admin user (*cn=DomainAdmin,cn=*domain) can also be specified in the Java-based Server configuration file. If it is not specified there, the Configurator tries to read it from configuration.ini.

Web Center Configuration

This dialog is only displayed when Web Center Configuration is selected.

The Web Center is configured to the domain specified in Domain Configuration. You can configure a Web Center for each domain. The technical domain name is used to deploy the Web Center into Tomcat. Thus, the URL part for the Web Center is:

webCenter-technical_domain_name, for example webCenter-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the … button.

  • Enter the name of the Service (on Windows platforms).

  • The checkbox Start Tomcat service after configuration (default checked).

  • Click Next to go to the next dialog.

The DirX Identity Web Center can be set up with other Web servers, too. Contact your support group to get more information about configuration with your specific Web server.

Web Center for Password Management

This dialog is only displayed when Web Center for Password Management Configuration is selected.

The Web Center for Password Management is configured to the domain specified in Domain Configuration. You can configure a Web Center for Password Management for each domain. The technical domain name is used to deploy the Web Center for Password Management into Tomcat to:

pwdManagement-technical_domain_name; for example, pwdManagement-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the … button.

  • Enter the name of the Tomcat service (on Windows platforms).

  • Check the checkbox Start Tomcat service after configuration (default is checked).

The fields for specifying the Tomcat parameters described above are only enabled for editing if Tomcat has not already been configured in the previous step. Otherwise, the previously configured parameters are displayed in the disabled fields.

Click Next to go to the next dialog.

Provisioning Web Service

This dialog is only displayed when Provisioning Web Service Configuration is selected.

The Provisioning Web Service is configured to the domain specified in Domain Configuration. You can configure a Provisioning Web Service for each domain. The technical domain name is used to deploy the Provisioning Web Service into Tomcat to:

ProvisioningService-technical_domain_name; for example, ProvisioningService-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the … button.

  • Enter the name of the Tomcat service (on Windows platforms).

  • Check the Start Tomcat service after configuration checkbox (the default is checked).

The fields for specifying the Tomcat parameters described above are only enabled for editing if Tomcat has not already been configured in one of the previous steps. Otherwise, the previously configured parameters are displayed in the disabled fields.

Click Next to go to the next dialog.

Server Admin REST Service

This dialog is only displayed when Server Admin REST Service Configuration is selected.

The Server Admin REST Service is configured to the domain specified in Domain Configuration. You can configure a Server Admin REST Service for each domain. The technical domain name is used to deploy the Server Admin REST Service into Tomcat to:

ServerAdminRestService-technical_domain_name; for example, ServerAdminRestService-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the … button.

  • Enter the name of the Tomcat service (on Windows platforms).

  • Check the Start Tomcat service after configuration checkbox (the default is checked).

Note that the fields for specifying the Tomcat parameters described above are only enabled for editing if Tomcat has not already been configured in one of the previous steps. Otherwise, the previously configured parameters are displayed in the disabled fields.

Click Next to go to the next dialog.

Server Admin User Interface

This dialog is only displayed when Server Admin User Interface Configuration is selected.

The Server Admin User Interface Web Application (HTML5) is configured to the domain specified in Domain Configuration. You can configure a Server Admin User Interface for each domain. The technical domain name is used to deploy the Server Admin User Interface into Tomcat to:

DirXIdentityServerAdmin-technical_domain_name; for example, DirXIdentityServerAdmin-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the …​ button.

  • Enter the name of the Tomcat service (on Windows platforms).

  • Check the Start Tomcat service after configuration checkbox (the default is checked).

Note that the fields for specifying the Tomcat parameters described above are only enabled for editing if Tomcat has not already been configured in one of the previous steps. Otherwise, the previously configured parameters are displayed in the disabled fields.

Click Next to go to the next dialog.

Identity REST Service

This dialog is only displayed when Identity REST Service Configuration is selected.

The Identity REST Service is configured to the domain specified in Domain Configuration. You can configure an Identity REST Service for each domain. The technical domain name is used to deploy the Identity REST Service into Tomcat to:

DirXIdentityRestService-technical_domain_name; for example, DirXIdentityRestService-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the … button.

  • Enter the name of the Tomcat service (on Windows platforms).

  • Check the Start Tomcat service after configuration checkbox (the default is checked).

Note that the fields for specifying the Tomcat parameters described above are only enabled for editing if Tomcat has not already been configured in one of the previous steps. Otherwise, the previously configured parameters are displayed in the disabled fields.

Click Next to go to the next dialog.

Business User Interface

This dialog is only displayed when Business User Interface Configuration is selected.

The Approval Web Application (HTML5) is configured to the domain specified in Domain Configuration. You can configure a Business User Interface for each domain. The technical domain name is used to deploy the Business User Interface into Tomcat to:

BusinessUserInterface-technical_domain_name; for example, BusinessUserInterface-CustomerDomain.

Specify the following parameters:

  • Enter the path to the Tomcat installation directory or choose it via the … button.

  • Enter the name of the Tomcat service (on Windows platforms).

  • Check the Start Tomcat service after configuration checkbox (the default is checked).

Note that the fields for specifying the Tomcat parameters described above are only enabled for editing if Tomcat has not already been configured in one of the previous steps. Otherwise, the previously configured parameters are displayed in the disabled fields.

Click Next to go to the next dialog.

HCL Notes Client

This dialog is only displayed on Windows platforms when C++-based Server Configuration is selected and the Connectivity Package HCL Notes has been installed.

  • Enter the path where your Notes Client is or will be installed.

  • Click Next.

Before you can use connectivity to the IBM Notes system, you must reboot the machine.

ODBC Library Path

This dialog is only displayed on Linux platforms when C++-based Server Configuration is selected and the Connectivity Package ODBC is installed. The Configurator asks you for the path where your ODBC libraries are installed.

In this dialog, you can:

  • Click Next to select the default location.

  • Select a different location and then click Next.

The Configurator tries to load the ODBC Agent. If this action fails, a warning is displayed. You can step back and enter a correct path, cancel the configuration or continue without configuring the agent.

SAP ECC UM Library Path

This dialog is only displayed on Linux platforms when C++-based Server Configuration is selected and the Connectivity Package SAP ECC UM is installed. The Configurator asks you for the path where your SAP JCo files are installed.

In this dialog, you can:

  • Click Next to select the default locations.

  • Select a different location and then click Next.

Pre-Configuration Summary

Before the specified configuration tasks are performed, you can review them here. The text window displays a complete list of tasks that will be performed after you click the Next button.

  • Click Next to start the configuration procedure.

  • Click Previous to correct data that is incorrect.

Configuration in Progress

The configuration is running now. It performs all steps displayed:

  • A running step is displayed in gray.

  • If a step is performed successfully, its color turns to green and the configuration procedure proceeds with the next step.

  • If a step fails, its color turns to red.The configuration procedure is aborted and a message is displayed that asks whether you want to view the log file.

    Correct the problem and then re-start the configuration process.You can select only those configuration options for which the configuration procedure previously failed.

If all steps are performed successfully, you have completely configured DirX Identity.

Click Finish to close the Configurator.

Don’t forget to set the correct passwords for all of the pre-configured accounts in the DirX Identity database.(See the section "Managing Administrative Accounts" in the chapter "Managing the Connectivity System" in the DirX Identity Connectivity Administration Guide for details.)

Integrating Start/Stop Scripts into the Linux Operating System

For Linux platforms, the following DirX Identity service components are not necessarily stopped during system shutdown and not necessarily started during system start:

  • Message Broker

  • C++-based Server

  • Java-based Servers

This section describes how to use the DirX Identity integration utility to integrate start and stop scripts for these DirX Identity components into Linux and how to undo the integration if necessary.

Using the Integration Utility

Use the updrcs-linux.sh utility located in install_path/etc to integrate or unintegrate the start/stop scripts created for the listed DirX Identity components in /etc/init.d. The default names for these scripts are:

  • dmsvr for the C++-based Server

  • dmmbrk-number for a DirX Identity Message Broker

  • dmsvrj-technical_domain_name-Snumber for a Java-based Server

It is unlikely but possible that a script with a default name already exists in this folder which does not belong to DirX Identity. The utility automatically detects this kind of naming conflict. In this case, the utility can be customized by modifying the value of the shell variable UNIQUESUFFIX (default: empty string) in order to append a suffix to the default names. To integrate these scripts, perform the Linux command chkconfig -add with the related script names.

The scripts are similar to the scripts dmmbrk-* and S99* in install_path/etc. For instance, the script dmsvr on SuSE platforms is a concatenation of the suitable INIT-V information in install_path/etc/suse/S99dmsvr.txt install_path/etc/S99dmsvr. Here the related placeholders (like @dirx@) are substituted so that they reflect the dependencies correctly. For RedHat platforms, the related file in install_path*/etc/redhat* is used.

The script updrcs-linux.sh uses the technical domain name rather than the original domain name when handling domain-specific components.

For the Message Broker and the Java-based Servers, the script prompts the user to specify whether the related component needs configuration or un-configuration because this cannot be determined from configuration.ini.

Performing the Integration

If the DirX Identity components whose start/stop scripts are to be integrated use a co-located DirX Directory Server installation as the configuration and/or Provisioning store, the following prerequisites must be satisfied:

  • DirX Directory has been configured so that it is started when entering runlevels 3 or 5 and stopped during shutdown. See the DirX Directory documentation for Linux platforms for further details.

For SuSE, this prerequisite means:

  • A start/stop script dirx_script_name for DirX (for example, dirx) must exist in /etc/init.d.

  • The Linux command chkconfig --list dirx_script_name is successful.

You must be superuser in order to verify these prerequisites.

If these prerequisites are satisfied, perform these steps:

  • Login as superuser.

  • Using a shell, navigate to install_path*/etc*.

  • Execute the command ./updrcs-linux.sh. For SuSE Linux platforms, dirx_script_name must be supplied as an input argument if the DirX Identity installation uses a co-located DirX installation.

  • The script displays the exit code on screen. An exit code indicates successful execution of the script. A log file updrcs-linux.sh.log is also written.

The integration is now complete. The relevant DirX Identity components are started during system startup (in the order listed in "Integrating Start/Stop Scripts into the Linux Operating System") listed and stopped during system shutdown (in reverse order).

Running this script is required whenever the configuration has been changed with respect to these DirX Identity components.

Undoing the Integration

Before uninstalling DirX Identity, the integration must be undone:

  • Log in as superuser.

  • Using a shell, navigate to install_path/etc.

  • Execute the command ./updrcs-linux.sh -cleanup and then check the exit code and the log file.

Silent Configuration and Un-configuration

You can configure DirX Identity on a machine without interaction.Follow these steps to create a silent configuration:

  • Run the Initial Configuration in normal mode and then cancel it when the dialog Pre-Configuration Summary is displayed.This action customizes the response file configuration.ini and creates the Java-based Server configuration template in the installation folder.

  • Set the required passwords in configuration.ini and then save a copy of the file.

  • If necessary, create the Java-based Server configuration files in install_path*/bin*.(See "Java-based Server" for details.)

  • Run Configuration.bat (Configuration.sh) in install_path/bin with the following parameters:

  • InitialConfiguration silent [Java-based_server_config_file]

  • Check for errors and search for the string The configuration finished successfully! in the file install_path/logs/silent.log

You must perform the first two steps only after the first installation or when you want to change configuration settings. Otherwise, copy the saved configuration.ini file into the installation folder when the silent installation has finished and run the silent configuration.

By changing the configuration settings, you can:

  • Determine what components are configured by specifying the option properties. In a silent configuration, the components associated with the selected options are configured. In a non-silent configuration, the options determine whether the associated configuration step is preselected, which the user can change interactively. Here is the list of options that can be set:

  • option.dxm_schema=1 specifies that the Connectivity Schema and Data is configured.

  • option.dxr_schema=1 specifies that the Provisioning Schema and Data is configured.

  • option.MessageBroker=1 specifies that the Message Broker is configured.

  • option.idsc=1 specifies that the C++-based Server is configured.

  • option.idsj_server=1 specifies that the Java-based Server is configured.

  • option.sample_domain=1 specifies that the sample domain is configured.

  • option.cust_domain=1 specifies that the customer domain with the name specified in domain= is configured

  • HighAvailability.Serveradmin=1 specifies that the Server Admin application including the Java-based supervisor are configured.

  • option.configureManager=1 specifies that the Identity Manager is configured.

  • option.WebCenter=1 specifies that the Web Center is configured.

  • option.WebCenterPwdMgmt=1 specifies that the Web Center for Password Management is configured.

  • option.WebCenterSAP=1 specifies that Web Center for SAP is configured.

  • option.ProvisioningWebService=1 specifies that Provisioning Web Service is configured.

  • option.RestService=1 specifies that Identity REST Service is configured.

  • option.BusinessUserInterface=1 specifies that Business User Interface (HTML5) is configured.

  • Determine default values for certain properties. The properties are evaluated if the related component has been selected for configuration by the related option property described above. Here is a list of some properties with sample values:

  • MessageBroker.admin_port=8161

  • MessageBroker.displayname=Message Broker 1

  • MessageBroker.host=dxiptest01-vm

  • MessageBroker.jmx_port=10098

  • MessageBroker.port=61616

  • MessageBroker.secure_port=61617

  • MessageBroker.start_after_configuration=1

  • MessageBroker.start_type_automatic=1

  • MessageBroker-service.domain=domain

  • MessageBroker-service.account=account

  • MessageBroker-service.password=password

  • path.notes=C\:\\Program Files\\lotus\\notes

  • path.status=C\:\\Program Files\\Atos\\DirX Identity\\status

  • path.work=C\:\\Program Files\\Atos\\DirX Identity\\work

  • connectivityStore.directory_inst_path=C\:/Program Files/Atos/DirX

  • connectivityStore.host=dxiptest01-vm

  • connectivityStore.port=389

  • connectivityStore.ssl=0

  • connectivityStore.type=DirX Directory V8.x

  • connectivityStore.user=cn\=admin,o\=My-Company

  • provisioningStore.directory_inst_path=C\:/Program Files/Atos/DirX

  • provisioningStore.host=dxiptest01-vm

  • provisioningStore.port=389

  • provisioningStore.ssl=0

  • provisioningStore.type=DirX Directory V8.x

  • provisioningStore.user=cn\=admin,o\=My-Company

  • roleadmin.user=cn\=SystemAdmin,cn\=DirXmetaRole-SystemDomain

  • svcadmin.user=cn\=server_admin,dxmC\=DirXmetahub

  • systemwide.ha=0

  • systemwide.ssl=0

  • tomcat.path=C\:/Program Files/Apache Software Foundation/Tomcat 8.0

  • tomcat.service_name=Tomcat8

  • tomcat.start_after_configuration=1

  • The names of all properties can be seen in the configuration.ini file after the Configurator has run. Their values can be changed and will be taken for preselection (in silent mode for final selection) in the next run.

If the Configurator runs in silent mode, the selected components are configured with the specified property values. In non-silent mode, the Configurator displays the steps and dialog boxes corresponding to the selected components and the specified properties. These preselections can then be changed by the user.

Password settings in the configuration.ini file for silent configuration include:

# Password of the directory administrator for connectivity (that is, cn=admin,o=My-Company)
connectivityStore.password=password
# Password of the directory administrator for provisioning (that is, cn=admin,o=My-Company)
provisioningStore.password=password
# password of cn=SystemAdmin,cn=DirXmetaRole-SystemDomain
roleadmin.password=password
# password of the customer domain admin (cn=DomainAdmin,cn=Customer Domain)
domainadmin.password=password
# password of cn=admin,dxmC=DirXmetahub
hubadmin.password=password
# password of cn=server_admin,dxmC=DirXmetahub
svcadmin.password=password
# password of the C++-based server account
IdS-C-service.password=password
# password of the Java-based service account
IdS-J-service.password=password
# password of the ActiveMQ MessageBroker service account
MessageBroker-service.password=password
# password of the system-wide keystore
systemwide.keystore_pwd=password
# system-wide pin
systemwide.pin=pin
# system-wide previous pin
systemwide.previous_pin=pin
# system-wide signature pin
systemwide.signature_pin=pin

You can specify that the passwords and PINs in the section shown above should be deleted in the configuration.ini file and the Java-based_server_config_file (.tpl), if used, at the end of the configuration by setting:

deletePasswordsAfterConfiguration=1

For a silent un-configuration:

  • Run Configuration.bat (Configuration.sh) in install_path/bin with the following parameters:

  • UnConfiguration silent