Installing and Configuring the EmpowerID Virtual Directory Server

EmpowerID's Virtual Directory Service (VDS) provides a robust identity virtualization service with unified, enterprise-wide security by acting as an abstraction layer between disparate data stores, including: payroll systems, HR systems, Active Directory, custom applications and other sources. EmpowerID's VDS allows applications to interact with these data sources, without being directly connected to them.

ℹ️Terminology

In this topic, we used the terms "Virtual Directory Service", "VDS", and "LDAP Server" interchangeably.

The VDS is a server-side JavaScript application managed by Node.js. As such, Node must be installed on your server before the VDS can be configured for use. Additionally, the LDAP Server uses the Forever node module to keep the server up and running. The installer you received from EmpowerID checks to see if these prerequisites are installed. If they are not, installer will install them for you.

Installing and configuring the EmpowerID Virtual Directory Server involves the following:

1. Creating a SQL Login on the EmpowerID database for the VDS (see prerequisite information)
2. Extracting the LDAPServer.X.X.X.zip file you received from EmpowerID on your EmpowerID server and executing the LDAPServer.msi.
3. Installing Node by executing the Node.X.X.X.msi included with the Virtual Directory Server.
4. Installing the Forever node module. The LDAP Server uses this module to keep the server up and running.
5. Editing the Config.txt file for your environment.
6. Adding to the LDAP Server the SQL password for the user you set in the prerequisites above, as well as a PFX certificate and the passphrase for the certificate—if you are using TLS.
7. Editing the index.js and Config.txt files for your environment.
8. Saving the SQL Login password in an encrypted file.
9. Starting the LDAP Server service.

ℹ️SQL Login Prerequisite

As the LDAP Server authenticates users against the EmpowerID database, you need to provide it with a SQL login that has rights to the EmpowerID database. Expand the below drop-down for step-by-step directions on creating the login in SQL Server.

To create a SQL Login

1. Open SQL Server Management Studio.
2. From Object Explorer, create a Login and set the Default database to the instance of the EmpowerID database in your environment. Note that SQL Serve authentication is used.

3. From the Login Properties dialog, set the User Mapping to EmpowerID Service and public.

4. To verify the login, open a new instance of the Connect to Server dialog, select SQL Server Authentication and enter the credentials you just created.

Procedure

Step 1: Install the LDAP Server

1. Download the LDAPServer.X.X.X.zip file from the EmpowerID FTP site and extract the folder to a location of your choosing on your EmpowerID Web server.
2. Navigate to the EmpowerID LDAP Server/LDAP Server/MSI/WiX folder in the EmpowerID installation path and locate the Virtual Directory Server.msi.
3. Double-click the Virtual Directory Server.msi to open the EmpowerID LDAP Server Setup Wizard.
4. From the EmpowerID LDAP Server Setup Wizard, click Next.

5. Accept the terms of the license agreement and click Next.

6. Select the installation destination folder and click Next.

7. Click Install.
8. Once the wizard finishes the installation, click Finish to exit the wizard.

Step 2: Install Node and the Forever module

1. From Windows Explorer, navigate to the EmpowerID LDAP Server/LDAP Server/MSIs folder in the EmpowerID installation path.
2. Double-click the node installer to open the Node.js Setup Wizard.
3. From the Node.js Setup Wizard, click Next.

4. Accept the terms of the license agreement and click Next.
5. Select the installation destination folder and click Next.
6. Review the features to be installed and click Next.
7. Click Install.
8. Once the wizard finishes the installation, click Finish to exit the wizard.
9. Verify the installation by opening a command prompt and typing node. You should see no errors and be entered in the command line mode of node.js.

10. Exit the node repl by pressing the CTRL key and typing d in the command line.
11. From the command line install the Forever node module globally by typing NPM install -g forever and pressing ENTER.

Step 3: Configure Config.txt for your environment

1. From the LDAP Server folder, locate and open the config.txt file in any text editor.
2. From config.txt specify the following values for your environment:
   • Port - If you are using TLS, the standard port for LDAP is 636; if you are not using TLS, the standard port for LDAP is 389. However, you can use any port for either situation.
   • IP - You can specify a specific port or set the value to 0.0.0.0.
   • USE_TLS - Set to true or false based on whether you are using TLS to secure the communication between the LDAP server and the LDAP client.
   • DB_USERNAME - This is the database user you set above.
   • DB_DATABASE - This is the name of the EmpowerID database.
   • OAUTH_HOSTNAME - This the FQDN or fully resolvable DNS to the EmpowerID Web server.
   • OAUTH_PORT - Set to 443
   • OAUTH_IS_TLS - Set to true
   • WORKFLOW_HOSTNAME - This is the FQDN or fully resolvable DNS to the EmpowerID Web server hosting the EmpowerID Worker Role service.
   • WORKFLOW_SITEPATH - Set to EmpowerID
   • WORKFLOW_PORT - Set to true
   • WORKFLOW_IS_TLS Set to true
   • Specify the rotating log file settings. By default, the LDAP server rotates log daily, keeping a maximum of 10 logs in the LDAP Server > Logging folder. You can change these setting as needed.
   • Leave the rest of the settings in this file at the default.

ℹ️Configuration Changes

If you need to make changes to the config.txt file beyond those listed above, it is recommended that you contact EmpowerID support.

Step 4: Add the SQL password, PFX certificate and passphrase to the LDAP Server

1. Optional - If you are using TLS, do the following in the LDAP Server folder:
   1. Create a new folder named cert and then paste the appropriate PFX certificate into the folder.
   2. From the cert folder, rename the PFX certificate file to ldaps.pfx.
2. From the LDAP Server folder, open a command prompt and type node configure in the command prompt.
3. Type the SQL password for the SQL user in the command line and press ENTER.
4. If you are using TLS, type the pfx passphrase for the certificate and press ENTER.

Step 5: Edit the start and forever log paths

1. From the LDAP Server > process folder, open start.bat in any text editor.
2. From the text editor, change the path for the forever log to reflect the installation location in your environment. This log shows the state of the LDAP server.

In a default installation, the path should look like the following:

forever --uid "eidVd" -s -a -l "C:\Program Files\EmpowerID LDAP Server\process\forever.log

3. From the text editor, change the start path for the LDAP server to reflect the location of the index.js file. Node calls this file when starting the LDAP server.

In a default installation, the path should look like the following:

start --sourceDir="C:\Program Files\EmpowerID LDAP Server" index.js

To start and stop the LDAP server

1. From the LDAP Server folder, open a command prompt and type node index.

You should see that the LDAP server is listening at the specified port and IP you set in the config.txt file earlier.

2. To stop the LDAP server, press CTRL and type c in the command window.

You should see that the LDAP server stops.

Step 6: Create a profile for EmpowerID in the LDAP browser

1. From your LDAP Browser (or LDAP Administrator), click New > New Profile.

2. In the Profile Creation Wizard that appears, enter a name for the profile in the Profile Name textbox and then press the ENTER key.

3. In step 2 of the Profile Creation Wizard, verify the host information:
   • Host - localhost, 127.0.0.1, 0.0.0.0 or your host's DNS name (this value is specified in your config.txt file)
   • Port - 639 (this value is specified in your config.txt file)
   • check Use secure connection (SSL) checkbox

4. In step 3, choose Anonymous user. If you want to authenticate using credentials (authenticated bind), see LDAP VDS: authenticated bind paragraph of this doc to configure your environment for authentication

5. In step 4, click Finish and click OK if asked about trusting a certificate.

You should now see a virtual directory for the default view of the EmpowerID database as determined by the LDAP Server configuration file. If desired, you can customize this file to return more or less data.

Configuring Authenticated LDAP VDS Bind

To configure the environment for authenticated LDAP VDS bind, the following set of parameters shown in the screenshot need to be set in the config.txt file.

Step 1: Set the OAUTH_CLIENTID, OAUTH_CLIENTSECRET, and X_EmpowerID_API_KEY

Do the following to get the values for the OAUTH_CLIENTID, OAUTH_CLIENTSECRET, and X_EmpowerID_API_Key:

1. Log in to EmpowerID UI (located at OAUTH_HOSTNAME URL) as an admin user.
2. On the left pane, expand Apps and Authentication and click Applications.
3. Search for LDAP Virtual Directory and click the Display Name link on the returned record.

This directs you to the View One page for the application.

4. Expand the Advanced pane and click the OAuth Provider App ID link.

This directs you to the View One page for the OAuth Provider application.

5. Copy the values for the Client ID and API Key located in the Connection Details pane.

6. Next, generate the Client Secret by doing the following:
   • Expand the Client Secrets accordion and click the New button.

This opens a popup for adding a new secret. You should the Client Secret field is populated with a randomly generated value.

• Copy the Client Secret. Note that once the secret is saved you will not be able to retrieve it from the UI so be sure the copy it first.
• Enter a Name for the secret and select an expiration from the Expires dropdown.
• Click Save to save the secret.

Step 2: Set the EID_URL, EID_OAUTH_CALLBACK_URL and OAUTH_URL

1. Your EID_URL is https://<OAUTH_HOSTNAME>/api/services/v1/LdapVds/Authenticate
2. EID_OAUTH_CALLBACK_URL is equal to https://<OAUTH_HOSTNAME>
3. OAUTH_URL - https://<OAUTH_HOSTNAME>/oauth/v2/token

Step 3: Set the EID_OAUTH_GRANT_TYPE

1. Enter urn:ietf:params:oauth:grant-type:jwt-bearer

Step 4: Set the EID_OAUTH_JWT_KEY_PATH, EID_OAUTH_JWT_KEY_PASSPHRASE, EID_SRV_ACCT_CERT_THMB

1. Using EmpowerID Certificate Generator (or any other tool), generate a self-signed certificate. Give it a subject name (like the one shown below) and a password and then check the Import to EmpowerID Certificate Store.

To verify that your certificate was indeed generated and imported correctly, you can run a SELECT query in CertificateStore table of EmpowerID database on the server your EID instance is connected to.

You also need to copy the Thumbprint of this certificate - that is your EID_SRV_ACCT_CERT_THMB. Your EID_OAUTH_JWT_KEY_PASSPHRASE is the password you created this certificate with.

2. In order to get a PEM file, you need to have OpenSSL installed. Once you have it installed, you can run the following command to extract the PEM key from your .pfx certificate file:

   openssl pkcs12 -in <filename>.pfx -nocerts -nodes -out key.pem
   Put the extracted key to a cert folder of your LDAP VDS installation location, same location where your ldaps.pfx is. Location to .pem file is your EID_OAUTH_JWT_KEY_PATH.

Once you have these parameters specified in your config.txt file, you should be able to bind with user credentials.

info

In the event you receive a 400 error, you can do the following:

1. Check if SELECT query on CertificateStore described above returns a PersonID for your certificate entry. If you see NULL, run the following query, updating CertificateStoreID with a value that the query returns for your certificate:

   UPDATE CertificateStore SET PersonID = 1 WHERE CertificateStoreID = <your_certificate_store_id>
2. If this doesn't help, run the following query:

   delete OAuthProviderAccessToken
   delete OAuthProviderRefreshToken
3. Retry binding.