3 Installing and Configuring the LDAP Gateway

You can install the LDAP gateway on Windows and Linux platforms.

The following topics describe the system requirements, LDAP gateway concepts, and procedures to install and configure the LDAP gateway:

• System Requirements

• LDAP Gateway Concepts

• Files and Directories that Comprise the LDAP Gateway

• Installing the LDAP Gateway

• Configuring the LDAP Gateway

• Configuring Windows Service

• Starting the LDAP Gateway

System Requirements

These are the recommended system requirements that are designed to give you optimal system performance from the LDAP gateway.

However, individual performance may vary depending on actual system components in use and the number of objects being managed on the target system.

The following are the minimum system requirments:

• Windows Server (2012) and Linux (RHEL)
• 2 GHz Single-Core Processor
• 4 GB RAM
• 10 GB Hard disc drive
• 1 Network Interface

The following are the recommended system requirements:

• Windows Server (2012) or Linux (RHEL)
• 2 GHz Multi-Core Processor
• 16 GB RAM
• 50 GB Hard disc drive
• 1 Network Interface

The following are the prerequisites required to install the LDAP Gateway:

• 64-bit Linux or Windows Server 2016 or later.
• The LDAP Gateway requires Oracle Java JRE 1.7, 1.8, or 1.10.
• A software license file (license.lic) available in the connector installation media.

If you do not have Java, the installer will redirect you to the Oracle website to install Java. Re-run the LDAP Gateway installer once Java is installed.

LDAP Gateway Concepts

This section discusses the following optional features of the LDAP Gateway:

• About Encrypting Data

• About Caching Layer

• About Scheduled Recon Utility

• About Parsing Grammar Protocol 1.0

About Encrypting Data

An encryption.properties file exists in the conf/ directory. This file allows the ability to configure what properties associated with connectors should be managed as encrypted values.

For example,

file.customer-configuration=adminUserPassword,altAdminUserPassword

This example defines that there exists a properties file called customer-configuration.properties that contains the sensitive properties adminUserPassword and altAdminPassword. This definition is consumed when the gateway first starts up. If the property file exists on the disk, the gateway searches for that property file and replaces any cleartext values in those properties with an encrypted version.

It is similar to connector definitions. For example, for the CA ACF2 connector, class.ACF2Module=_SecretKeyValue_ defines that there exists a connector called ACF2Module whose associated property files contain the sensitive property of _SecretKeyValue_ that needs to be secured by the gateway.

When the gateway starts, it uses the encryption.properties file to examine the properties that need to be represented in their encrypted format. Encrypted values within property fields are always represented using the format - ENC(<ENCRYPTED STRING>). To add or replace an existing encrypted value with a new value, replace the entire encryption string if present (including the ENC()) with a new clear text value, and then restart the gateway. Once the gateway restarts, the newly added clear text value goes through an encryption process with the result being written back out to the property file replacing the original clear text value.

During the encryption process, the encryption framework used by the gateway automatically detects the highest level of encryption possible by examining the version of the Java Virtual Machine running along with any additional encryption libraries that may have been installed alongside the JVM. By default, Java 1,8 support 128-bit AES encryption and Java 1.7 support 40-bit AES encryption. Additional encryption libraries by BouncyCastle can be installed into the JVM allowing for up to 256-bit AES encryption.

The encryption process in the gateway also allows for automatic migration of encryption values from a lower bit strength to a higher strength as it becomes available. For example, if the gateway is initially deployed on a system running Java 1.7 with 40-bit AES and that system is upgraded to Java 1.8 running 128-bit AES, then upon the next restart of the gateway, all encrypted values remaining at the 40-bit AES level are automatically re-encrypted at the higher 128-bit and stored back out in the property files. This process eliminates the need to manually replace the values in every property file in order to take advantage of the higher bit strength.

The private key located in the idf.properties file is used for all the encryption and decryption performed by the gateway. It is recommended that access should be restricted to this file.

Note:

Once the gateway is deployed and started up for the first time, the value of the autogenerated encryption key in the idf.properties file should not be changed. However, the file name and its location can be easily changed. For example, to store the idf.properties file to a more secure location, the default location (where the gateway resides) can be overridden and defined as system.idfprops.filepath=<absolute path of the new file> in the customer-configuration.properties file.

About Caching Layer

A Caching layer is a temporary storage area where frequently accessed data is stored for rapid access.

The IDF LDAP Gateway features an optional and configurable caching layer.

An expiration policy defines the time dependency for the cached resource. For example, the cachingMaxAge parameter specifies the maximum time in minutes when the data is not in sync with the target systems. You can pair the caching layer with a real-time reconciliation or with a scheduled reconciliation to maintain the most recently updated data in the caching layer. This improves the performance of the LDAP Gateway. The caching layer also opens the LDAP Gateway up to more advanced features defined by the LDAPv3 RFC.

The caching layer, when enabled, offers the following benefits:

• Faster search operations (when the cache is primed)
• A unified Base DN for both provisioning and reconciliation data

When paired with the Embedded DS (default behavior), the caching layer offers these additional benefits:

• The ability to perform advanced LDAP search filters against the Gateway
• The ability to query an RFC compliant ChangeLog for delta reconciliation

  Note:

  In an environment where the items noted above may not be required, the caching layer can be turned off entirely by setting the cnctr.coreBean.nexus.cachingEnabled=false in the customer-configuration.properties.

The LDAP Gateway can suffer a performance penalty when all of the following conditions are met:

• There is no data in the cache, or the cache is stale based on configuration
• An LDAP search operation is performed to retrieve the children of an Organizational Unit - e.g. the contents of ou=People
• The target Adapter only returns key information when returning a list of objects.

Performing an LDAP search operation against such adapters to retrieve the children of an Organization Unit returns only DNs (along with RDN components).

• The cachingIterateBehavior property remains set to the default of AUTO and not overwritten within the customer-configuration.properties file.

In this case, an LDAP search operation initially retrieves the list of results, containing only DN and RDN values. The LDAP Gateway caching layer then iterates through each result, fetching and caching the details from the target Adapter. Finally, the full set of results will be returned to the LDAP client.

To avoid this scenario, it is recommended that you use the caching layer in combination with Scheduled Recon or Real-time recon. With reconciliation setup and the staleness settings configured properly the above conditions will not be met.

Note:

See About Scheduled Recon Utility.

About Scheduled Recon Utility

Scheduled Reconciliation allows for establishing a periodic synchronization between the Identity Store associated with the LDAP Gateway and that is represented by a target system reachable by way of a connector.

The Scheduled Recon Utility (provided by dist/scheduled-recon.jar) is a tool that ships with the IdentityForge LDAP Gateway. It provides the ability to perform a full recon against a configurable target system, placing the results in the Gateway's internal identity store.

• For connectors that already support reconciliation against the Internal identity store such as ACF2.

• For connectors that do not support reconciliation, the connectors rely solely on the Scheduled Recon Utility for both scheduling and providing the capabilities necessary to simulate a traditional batch recon process.

An example properties file that defines the reconciliation setup and behavior - scheduledrecon.properties.example - is provided in the conf/ folder.

Configuration

An example properties file, scheduled-recon.properties.example file that defines the reconciliation setup and behavior is available at (…/IDFLDAPGateway-6/conf/… folder). Use this file to configure the scheduled recon. Create a scheduled-recon.properties file in the conf folder and copy all the settings from the scheduled-recon.properties.example file. A scheduled-recon.properties file containing the configuration details for the recon operation can be provided via the -h argument.

Description of the illustration h_argument.gif

A batch file called run-recon.bat located in the “bin” folder can be used to start the scheduled recon utility. The basic command structure for executing this batch file is as follows:

…\ldapgateway6\bin>run-recon.bat -l "warning" <location of the log file> -p "D:\ldapgateway6\conf\scheduled-recon.properties”.

Description of the illustration run-recon_batch_file.gif

Execute the run-recon.bat with a minimum set of arguments passed in. For example,

Description of the illustration run_recon_bat.gif

About Parsing Grammar Protocol 1.0

Grammar is necessary for properly parsing user and group listings that come into the gateway from the mainframe agent during search requests and reconciliation events.

The grammar represents line-by-line parsing instructions that convert the semi-structured textual data into LDAP attributes and their respective values. Each line (ending in CRLF) of the listing received from the agent can be represented by an individual grammar definition and specified in the grammar file. The grammar file is present in the <conf/parser-grammar/ > folder.

For example, following is the ACF2 user listing:

PIONEER                        PIONEER        VPIONEER-STC
CLIENT() COMPANY() DEPT() GRP() LEVEL() LOCATION()
PROFILE() REGION() SBCLIENT()
PRIVILEGES           ACCOUNT SECURITY STC
ACCESS               ACC-CNT(0) ACC-DATE(00/00/00) ACC-TIME(00:00)
PASSWORD             KERB-VIO(0) KERBCURV() PSWA1TOD(00/00/00-00:00)
PSWD-DAT(00/00/00) PSWD-INV(0) PSWD-TOD(00/00/00-00:00)
PSWD-VIO(0) PSWDCVIO(0) PWP-DATE(00/00/00) PWP-VIO(0)
TPXPROF()
TSO                  DFT-PFX(PIONEER)
STATISTICS           CRE-TOD(05/17/18-00:13) SEC-VIO(0)
UPD-TOD(05/17/18-00:13)
RESTRICTIONS         PREFIX(PIONEER) UXHOLD5()

Using the above listing, if you want to parse out the KERB-VIO value from the listing and assign it to an LDAP attribute called “kerbvio”, the following <Line> element can be constructed in the grammar file.

<Line id=”kerbvioVal” enabled=”yes” sig=”[ ]*KERB-VIO = (?&lt;kerbvio&gt;.*)"/>

The signature attribute (sig) in the Line element above is a regex that represents the rules for pulling out the value and assigning it to an LDAP attribute. Regex named groups are used as the convention for assigning the discovered values to LDAP attributes exposed through the connector.

The following table lists the attributes of a line element. The allowed values for these attributes are yes or no.

String	Definition
id	Unique ID that is given to the Line definition. Used primarily for internal referencing purposes, such as with the 'dependson' attribute Values Allowed: [any] Behavior: Required
enabled	Specifies whether the Line is eligible for participating in the Parsing process. This flag is used mainly to allow the customers to override files (turn off lines). Behavior: Optional Defaults to: yes
signature	Defines the rules for what values are to be extracted for each line of the listing and which LDAP attribute(s) should be assigned the values. Behavior: Required
required	Defines if an attribute is required or not. Default to: yes
multiline_sig	An optional regex expression to define the signature of a follow-on line that could represent whether the value was wrapped around two additional lines in the document Values Allowed: [any valid regex containing attribute matching key and attribute name]. Behavior: Optional Defaults to: empty value
repeats	Represents whether the line can show up multiple times in the document. If set to "no", once the line is found, this Line definition is not evaluated again for the rest of the document. Behavior: Optional Defaults to: No
overflow	Represents whether data for an associated attribute can overflow to next line. In case of an overflow, the final value of an attribute will be derived by concatenating all values. Behavior: Optional Defaults to: No
multivalue_parser	An optional regex expression that defines how the found values are to be parsed out and turned into a multivalued list, such as using '(\S+)' to parse values that are space delimited. Values Allowed: [any valid regex ] Behavior: Optional Defaults to: empty value
applyCompositeRef	An optional comma separated list of composite attributes to be built immediately after processing the line. Each value in the comma separated list should correspond to the "id" attribute of a CompositeAttribute definition.
defaultvalue	Defines the default value for an attribute. If this line does not match with any line of input, then this default value will be assigned to attribute. Behavior: Optional

Customizing Grammar Rules

The grammar file with the default grammar is present in the conf folder. It parses user and group listings that come into the gateway from the mainframe agent during search requests and reconciliation events. You can apply new grammar rules to append to or override rules that come out of the box. To define new grammar rules or override the existing rules, create a grammar file parser-grammars.cust file in the <conf/parser-grammar/ > folder.

Note:

• If the Id of the existing attribute matches with the attribute in the grammar line, it overrides the existing grammar definition.

• If the Id of the existing attribute does not match with the attribute in the grammar line, it creates a new grammar definition.

Key Considerations

• The parser-grammars.cust grammar file must be at the same location where the parser-grammars file.

• The name of the grammar file must be the same except the cust extension.

• For the grammar definitions to override, the ID attribute from both the files should match.

Nomenclature of the parsing grammar files

Each grammar file is named for the type of operation and listing it is responsible for parsing.

For example, for ACF2:

For user extraction use the following:

• acf2_FindAllUsers.xml – fetches the IDs of all users.

• acf2_FindUserById.xml – fetches all the details of a single user (for the given ID).

Overriding default existing grammar definitions

The grammar definitions specified in the grammar file parser-grammars.cust override the default grammar definitions specified in the property files. To enable overriding of the particular line, the ID attribute in the custom provided attribute should match with the default grammar definition.

For example, if the default grammar definition in the property file and the definition specified in the custom grammar file is as shown in the following lines, then the definition is disabled and the line is not parsed.

<Protocol><Lines>
<Line id="elId" enabled="yes" sig="[ ]*ELID[ ]*=[ ]*(?<ELID>.*)"/>
</Lines>/Lines>

<Protocol><Lines>
<Line id="elId" enabled="no" sig="[ ]*ELID[ ]*=[ ]*(?<ELID>.*)"/>
</Lines></Protocol>

New grammar definitions

New grammar definitions can be specified in the grammar file parser-grammars.cust. For example, the following grammar definition is used to get values of DEPT_ACID=001 DEPT_NAME=hr.

<Protocol><Lines>
="deptAcid" enabled="yes" sig="[ ]*DEPT_ACID[ ]*=[ ]*(?&lt;deptacid&gt;.*?)
[ ]*DEPT_NAME[ ]*=[ ]*(?&lt;department&gt;.*)" />
</Lines></Protocol>

Files and Directories that Comprise the LDAP Gateway

These are the files and directories that comprise the LDAP Gateway.

Table 3-1 Files and Directories that Comprise the Gateway

Files and Directories	Description
bin	The bin/ folder contains run scripts for the components of the LDAP Gateway: run.bat (.sh) - Used to start the Gateway server stop.sh - Used to stop the Gateway when run with nohup run-migration.bat (.sh) - Used to migrate between versions of the product run-recon.bat (.sh) - Used to run the scheduled recon utility. See About Scheduled Recon Utility. stop-recon.sh - Used to stop the Scheduled Recon Utility when run with nohup install-license.bat (.sh) - Used to install a license.lic file found in the conf/ folder
conf	The conf/ folder contains the files required to configure a connector. For example, <connector>.properties - Contains connector-specific configuration customer-configuration.properties - Contains the LDAP Gatewaty configuration
dist	The dist/ folder contains the distributable JAR files. For example: idfserver.jar - LDAP Gateway server migration-utility.jar - Utility for migrating between product versions scheduled-recon.jar - Represents the scheduled recon utility. See About Scheduled Recon Utility. property-validator.jar - Used to validate (lint) .properties files
dsroot	The dsroot/ folder contains configuration files and data related to our Embedded DS persistence layer.
logs	The logs/ folder contains all the audit logs of the transactions.
schema	The schema/ folder contains files that determine the attributes types supported by the LDAP Gateway.

Installing the LDAP Gateway

Install the LDAP Gateway on Windows and Linux platforms.

Note:

During installation of the LDAP Gateway, if a previous installation is detected, you can either upgrade or continue with the fresh installation. If you plan to upgrade, ensure to perform the following preupgrade steps:

• Stop the running instance of the Gateway. If you are using Windows Service to run the Gateway, then uninstall the Windows Service.
• Shut down any Agent (for example, Pioneer or Voyager) running on the target environment.
• Disable any cron jobs.

See System Requirements to ensure that the target machine has the suitable specifications.

To install the LDAP Gateway, do the following:

1. To display the LDAP Gateway Setup Wizard, do the following:

   Note:

   The IDFLDAPGateway-6-linux-64-installer.run and IDFLDAPGateway-6-windows-64-installer.exe files are available in the IDF_LDAP_GATEWAY_VERSION.zip located in the connector installation media.
   • If you are using a Linux operating system, then run the IDFLDAPGateway-6-linux-64-installer.run file.
   • If you are using a Microsoft Windows operating system, then run the IDFLDAPGateway-6-windows-64-installer.exe file.
   The LDAP Gateway Setup Wizard is displayed.
2. Click Forward to proceed.
   The EULA is displayed.
3. Accept the EULA, and then click Next to proceed.
4. If an instance of LDAP Gateway is already installed, then that installation is detected as shown in the following image.
   
   Description of the illustration ldap_gateway_prev_inst.gif
5. If you want to upgrade, click Yes and then click Next to proceed. If you click No, then fresh installation will continue.

   Note:

   To upgrade from version 5.x to 6.x, you need to provide the location of the existing installation folder location and the path of the valid license file. If the install folder location is same, then the installer detects and creates a backup of the entire folder of the previous version with a suffix pre- and a timestamp. This can be verified at the install location. The backup of the entire folder happens only once when you are upgrading from v5 to v6. For example, if you already have a Gateway version 5.3 installed on your system, and you want to install Gateway version 6, a backup folder for the files of 5.3 is created at the install location.
   The Ready to Install window is displayed. Continue from Step 7.
6. If no instance of LDAP Gateway is detected or if you select No on the Previous Installation Detected screen, then specify the location where the LDAP Gateway must be installed.
   1. For Linux

      When you install the gateway as a normal user, the default location is inside the Home folder (home/ubuntu/IDFLDAPGateway-6).

      When you install the gateway as a sudo or root user, the default location is /opt/IDFLDAPGateway-6.

   2. For Windows, the default location is Program files (…\ProgramFiles (x86)\IDFLDAPGateway-6)

      Note:

      If the installation directory points to a location containing an existing gateway, that gateway is automatically upgraded during the installation process.
7. Click Forward to proceed.
   You are prompted for the license file.
8. Browse to the location containing the license.lic file, select it and click OK.
   The Ready to Install window is displayed.
9. Click Forward to proceed.
   The Installing window is displayed.
10. Once the installation or upgrade is complete, click View Readme File to view the changes in the release version.
11. Click Finish to complete the installation or upgrade process.

Configuring the LDAP Gateway

Configure the LDAP gateway to connector to the target system and access the data.

The following topics describe the procedure to configure the LDAP Gateway:

Note:

The following procedures are for a fresh installation only. If you already have a running setup or if you want to upgrade, then you do not have to perform these procedures.

• Creating a Connector Configuration

• Editing the System Administrator Credentials for Target

• Configuring the LDAP Gateway with Multiple Connectors

• Overriding the System Configuration

• Configuring the Adapter

Creating a Connector Configuration

To allow IDF Gateway to work with a target system, it must be configured for the type of connector and its related parameters for the operations.

Perform the following steps to create a connector configuration:

1. Open the customer-configuration.properties file from the conf/ folder in a text editor to configure the connectors. Copy the connector specific configurations to this file.

   Refer to the customer-configuration.properties.example file from the conf/ folder to get the connector specific configuration properties. Each connector comes with an example configuration that can be found in the customer-configuration.properties.example file. Find the connector definition that you want to turn on and copy that definition in the customer-configuration.properties file.

   For more information and example settings, see the customer-configuration.properties file.

   For CA ACF2, copy the following and paste it in the customer-configuration.properties file:

   cnctr.acf2.class=com.identityforge.idfserver.backend.acf2.Acf2Module
   cnctr.acf2.acf21.schema=schemas
   cnctr.acf2.acf21.suffix=dc=acf2,dc=com
   cnctr.acf2.acf21.adminUserDN=cn=idfAcf2Admin,dc=acf2,dc=com
   cnctr.acf2.acf21.adminUserPassword=idfAcf2Pwd
   cnctr.acf2.acf21.altAdminUserDN=cn=oimAcf2Admin,dc=acf2,dc=com
   cnctr.acf2.acf21.altAdminUserPassword=oimAcf2Pwd
   cnctr.acf2.acf21.configLocation=../conf/acf2.properties
   cnctr.acf2.acf21.allowAnonymous=false
   cnctr.acf2.acf21.metaBackend=ldapds
   cnctr.acf2.acf21.agent=true
   cnctr.acf2.acf21.people.multiCallAttributes=userpassword,revoke,revoked,revoke|revokeDate,userpassword|userpassword,userpassword|passwordexpire

2. Add following line to the customer-configuration.properties file if it is not already there: cnctr.coreBean.nexus.cachingEnabled = false

   Note:

   This step is mandatory. Otherwise, the cache can become stale and any ACF2 Reconcile All Users Task in Oracle Identity Manager will not be able to reconcile data from the ACF2 target system.
3. Save the file.

Editing the System Administrator Credentials for Target

Modify the system admnistrator credentials to authenticate access with the Gateway.

Perform the following steps to view and modify the system administrator credentials used to authenticate access with the Gateway:

Note:

Sensitive data is automatically encrypted when the LDAP Gateway starts. For more information, see About Encrypting Data.

Edit the conf/customer-configuration.properties in an editor and set values for the following:

• cnctr.<foo>.<foo>1.adminUserDN=cn=idf<Foo>Admin,dc=<foo>,dc=com

• cnctr.<foo>.<foo>1.adminUserPassword=idf<Foo>Pwd

  Note:

  • Replace the terms <foo> and <Foo> with connector specific values. For example, replace <foo> with acf2 and <Foo> with Acf2 for the ACF2 connector.
  • While setting the adminUserDn, it is mandatory to use cn as the RDN identifier.
  • If you put spaces after the commas in the DN, you must match that when using that ID to connect to the LDAP Gateway.
  • After you modify the customer-configuration.properties file, make sure you restart the LDAP Gateway Server to have the changes take effect.

  For example, the required format for ACF2 is: cn=adminId,dc=acf2,dc=com (the dc=acf2,dc=com must match the suffix property).

Configuring the LDAP Gateway with Multiple Connectors

The same type of connector can be instantiated multiple times to represent multiple different endpoints of the same target system. This is, in addition, to the gateway supporting the ability to run various kinds of connectors within a single gateway instance.

It is assumed that you have already configured a single instance of your connector and wish to configure an additional instance. For more information on configuring the LDAP Gateway with a single connector, see Configuring the LDAP Gateway.

To configure the LDAP Gateway with multiple connectors, do the following:

1. In a text editor, open the customer-configuration.properties file located in the conf/ folder for editing.
2. Copy the connector-specific configurations from the customer-configuration.properties.example file to the conf/customer-configuration.properties file.

   For example, copy the following snippet to the /conf/customer-configuration.properties file:

   cnctr.<foo>.class=com.identityforge.idfserver.backend.<foo>.<Foo>Module
   cnctr.<foo>.<foo>1.schema=schemas
   cnctr.<foo>.<foo>1.suffix=dc=<foo>,dc=com
   cnctr.<foo>.<foo>1.adminUserDN=cn=idf<Foo>Admin,dc=<foo>,dc=com
   cnctr.<foo>.<foo>1.adminUserPassword=idf<Foo>Pwd
   cnctr.<foo>.<foo>1.altAdminUserDN=cn=oim<Foo>Admin,dc=<foo>,dc=com
   cnctr.<foo>.<foo>1.altAdminUserPassword=testpass
   cnctr.<foo>.<foo>1.configLocation=../conf/<foo>.properties
   cnctr.<foo>.<foo>1.allowAnonymous=false
   cnctr.<foo>.<foo>1.defaultUacc=read
   cnctr.<foo>.<foo>1.metaBackend=ldapds
   cnctr.<foo>.<foo>1.agent=true

   Note:

   Replace the term <foo> and <Foo> with connector specific values. For example, for ACF2 replace <foo> with acf2 and <Foo> with Acf2. For more information, see the customer-configuration.properties.example file located in the <LDAP_INSTALL_DIR>/ldapgateway/conf/ directory..
3. In the /conf/customer-configuration.properties file, rename the instance ID for the pasted entries if the connector is already defined. For example, rename acf21 to acf22.
4. Modify the following properties as required:
   • adminUserPassword - change this for security reasons.
   • suffix - represents a unique baseDN. For example, dc=<foo>dev,dc=com.
   • adminUserDN - full DN of the administrative user account that can use the connector for performing reconciliation and provisioning operations. DN suffix must match the value supplied for suffix.
   • altAdminUserDN - DN suffix must match the value supplied for suffix.
   • configLocation - location of the connector property file - e.g. conf/<foo>.properties. If the intent is to point these two connector instances to different target systems, the configLocation param should point to a different connector properties file for each connector instance. The new properties file can be a copy of the original properties file with changes in the necessary properties to point to the new system.
5. Save the customer-configuration.properties file after the configurations are defined.
6. Restart the LDAP Gateway to have the changes take effect.

Overriding the System Configuration

You can override the default system configurations for serveral reasons. For example, you may want to change the default passwords for the system backend persistence store or change the listening port when the default collides with another service or when the policies of the company require using a different port.

To change the default system properties, locate that property in the configuration.properties file (located in the conf/ folder) and copy it to customer-configuration.properties file and provide a new value.

Note:

Not all properties can be modified and must be done in consultation with Support.

To change the default system backend passwords, open the customer-configuration.properties file (located in the conf/ folder) and specify values for the following entries:

cnctr.proxy.ldapds.adminUserPassword=<admin-password>
cnctr.proxy.ldapds.altAdminUserPassword=<alt-admin-password>

In the preceding snippet, replace <admin-password> with the desired password and <alt-admin-password> with the desired alternative password for accessing the system backend (dc=system,dc=backend).

To change the default port, open the customer-configuration.properties file (located in the conf/ folder) and specify values for the following entries:

system.port=6389
system.ssl_port=7389

Replace 6389 with the desired listening port for LDAP and 7389 with the desired port for LDAPS.

Note:

• Any of the values defined in conf/configuration.properties can be re-defined in conf/customer-configuration.properties. Copy the value from conf/configuration.properties to conf/customer-configuration.properties and modify the value accordingly.
• You must not edit conf/configuration.properties directly as it will be overwritten when upgrading.

Configuring the Adapter

To configure the adapter, do the following:

1. Create a acf2.properties file in the conf folder by renaming the acf2.properties.example file located inside the <LDAP_INSTALL_DIR>/ldapgateway/conf> folder.
2. In a text editor, open the acf2.properties file. Edit, specify, and verify that the host, port, user credentials, and other properties are correctly updated to match your environment: The following properties can be configured:

   • Host – Host name or IP address to connect to the Pioneer Agent. For example, _host_=localhost.

   • Port – Enter the number of the port on the mainframe that you are going to reserve for the Provisioning Agent. The LDAP Gateway will send provisioning messages to this port. This value should match the PORT parameter specified in the Pioneer provisioning agent STC. For example, _port_=5790.

   • defaultDelete – Specifies if the user is to be disabled or deleted as an outcome of the Delete User provisioning operation. Accepted values are revoke or delete.

     Note:

     • To disable the user on the target system as the outcome of the Delete User provisioning operation, set the value of this property to revoke. For example, _defaultDelete_=revoke.
     • To delete the user from the target system as the outcome of the Delete User provisioning operation, set the value of this property to delete. For example, _defaultDelete_=delete.
   • secretKeyValue - Specifies the secret key to connect to the MF ACF2. For example, _secretKeyValue_=.
   • credentials.username and credentials.password - Credentials to pass to Pioneer as part of authentication enforcement of the connection. Required if the EnforceAuthentication flag is set on the pioneer side.
   • agentPort - Enter the port number on the LDAP Gateway host computer that you are going to reserve for messages sent from the mainframe by the Reconciliation Agent Voyager. The LDAP Gateway will receive messages using this port. This value should match the value of the PORT parameter in the Voyager agent control file. For example, _agentport_=5791.

   • stcID - This property allows the real-time agent to ignore events that have been submitted to the target system by the Pioneer STC (such as by request from Oracle Identity Manager). For example, _stcID_=PIONEERN.

   • internalEnt - This property is used to allow the real-time agent to store users in the LDAP internal store. Values are true or false.

   • domainOU - This property is used to store user in a certain location under the ou=People tree of the internal LDAP. This needs to be unique and specific for each system if multiple systems are used within one LDAP Gateway. Default setting is _domainOu=acf2.

     Note:

     ACF2 now supports a new OU called ResourceXRef. It represents the secondary Auth Ids that users can be included and excluded from. The new LDAP attributes represent assignment: "includeids", "includedns", "excludeids", and "excludedns". All these attributes can be used to add and remove users to and from. There must exist at least one include user. However, exclusions can be an empty list.
   • username= and password= - MF is set to authenticate using auth_ldap = Y and the EnforceAuthentication flag is set on the pioneer side. The credentials are required to pass the Pioneer as part of authenication enforcement of the connection.

     Note:

     • If you set the value of this property to No, then there would be no authentification.
     • If you set the value of this property to Yes, then it is mandatory to define credentials.

       For example, username=<Acf2 User> and credentials.password=<Password>

   • Error message signature XML - This file contains error message signatures. The file path is specified in errormsg-sig-file=.

     Define an error message signature XML file that contains new error message signatures
     # (or overrides existing error message signatures by specifying the same id).  
     #
     #The format of the file should follow
     #  <Signatures>
     #     <Signature id="[unique id]" regex="[regex]" enabled="yes|no">
     #         <!-- Optional Exceptions to reduce false positives -->
     #         <Exception regex="[regex]"/>
     #         :
     #     </Signature>
     #     :
     #  </Signatures>
     #
     #  Value: File path (relative to the folder where the gateway was executed in)
     errormsg-sig-file=

   • nameFormat - Name format for reconciliation. For example, _nameFormat_=fn|sp|ln.

   To specify the components of the format:

   • Use fn to represent the first name.
   • Use sp to represent the space character.
   • Use ln to represent the last name.
   • Use a comma (,) to represent the comma.
   • Use a period (.) to represent the period.
   • Use the vertical bar (|) as the separator for the other components.

Configuring Windows Service

The Windows Service for the LDAP Gateway is installed with a supplied IdentityForge batch file.

The Windows Service installer uses the Apache Procrun utility prunsrv.exe to create a fully managed Windows Service for the LDAP Gateway. For more information about Procrun, see http://commons.apache.org/proper/commons-daemon/procrun.html.

• Installing and Configuring the Windows Service for the LDAP Gateway

• Uninstalling the Windows Service for the LDAP Gateway

• Configuring Memory Pool Settings

Installing and Configuring the Windows Service for the LDAP Gateway

To install and configure the Windows service for the LDAP Gateway:

1. Open a command prompt (cmd).
2. From the command line, execute the command IDF_Win_Service install in the win_service/ directory.
3. Once the service is installed, you can start, stop, and restart it from the standard Windows Services manager or from the command prompt. For example,

   > net start IdentityForgeService
   > net stop IdentityForgeService

Note:

If there are any problems with the installation of the service from the batch file, uncomment the CG_PATH_TO_JVM variable and ensure that the path is accurate.

> rem -- 7. Set this if you want to use a different JVM than the one configured in your registry, or if it is not configured in the windows registry
> rem set CG_PATH_TO_JVM=C:\Program Files\Java\jre7\bin\server\jvm.dll

If any modifications are required, it is recommended to uninstall the service, make the modifications, and then re-install the service until it installs and runs correctly.

Uninstalling the Windows Service for the LDAP Gateway

To uninstall the Windows service for the LDAP Gateway:

1. Open a command prompt (cmd)
2. From the command line, execute the command IDF_Win_Service remove in the win_service/ directory.

Configuring Memory Pool Settings

You can configure the memory pool size for the Windows service by setting values for the CG_JVMMS and CG_JVMMX variables in the LDAP_INSTALL_DIR/win_service/IDF-Win-Service.bat file.

By default, the CG_JVMMS and CG_JVMMX variables are set to 1024 MB and 2048 MB, respectively. If the LDAP gateway processes a large number of records, then you might encounter the "Out of memory" exception. In such a scenario, you can allocate higher memory for your Windows service by increasing the values of the CG_JVMMS and CG_JVMMX variables.

To do so:

1. Stop the LDAP gateway Windows service and then uninstall it.
2. In a text editor, open the LDAP_INSTALL_DIR/win_service/IDF-Win-Service.bat file for editing.
3. Set the JVM minimum and maximum values by modifying values for the following lines:

   rem Initial memory pool size in MB.
   set CG_JVMMS=1024
   
   rem Maximum memory pool size in MB.
   set CG_JVMMX=2048

   Note:

   When you receive the "Out of memory" exception, start with increasing the minimum and maximum values to 2048 and 4096, respectively. If the number of records is greater than 40k, then use higher minimum and maximum values.
4. In the LDAP_INSTALL_DIR/conf/log4j.properties file, set the gateway debug level to ERROR as follows:

   rootLogger.level = ERROR

5. Install the LDAP gateway Windows service.
6. Start the LDAP gateway through the Windows service.

Starting the LDAP Gateway

1. To start the LDAP Gateway, do one of the following:
   • Execute the run.bat script on Windows or run.sh on Linux.
   • Start the configured Windows Service.
   • Use the shortcut from the Start Menu.
   • Double-click the Desktop shortcut.

   The LDAP Gateway begins its startup sequence and eventually displays a banner representing the version of the gateway. This banner symbolizes that the gateway is now ready to receive LDAP requests.

2. Check the connection using an LDAP browser with the following connection information:
   • Port: 6389
   • Base DN: dc=system,dc=backend

   • User DN: cn=Directory Manager,dc=system,dc=backend

   • Password: testpass