What is RiskUtilities Directory Sync?


RiskUtilities Directory Sync (RUDS) is a utility that adds, updates, and deletes users and organizations in your RiskUtilities (RU) system to match your LDAP directory. RUDS runs on your LDAP server and does not make any modifications to your LDAP system or data. 

 

Technical Overview

Tools


Configuration Manager - A GUI that walks you through mapping your LDAP information to be used in the sync. The application generates a XML configuration file that is used by the ruds-sync command line utility.

ruds-sync - A command line utility that syncs your LDAP data using the configuration XML made in the Configuration Manager. This utility can be setup to run as a scheduled task for automation.


 

 Workflow

  

  • RUDS connects to your LDAP directory and queries users and organizations.
  • RUDS connects to your RiskUtilties system and queries users and organizations.
  • These lists are compared and changes are made to the RiskUtilties system to match the LDAP directory.


 

Security

 

  • Runs on a machine in your network that you control.
  • Connection to your LDAP server can be configured to use LDAP + SSL.
  • Connection to RiskUtilities over the internet is via HTTPS.
  • No modifications are made to your LDAP server configuration or data.


 

 

Getting Started

 

Setting up your RiskUtilities System

 

  • Login to your RiskUtilities System
  • Browse to Administration > Settings
  • Click Edit Settings 


  • Enter a System URL Identifier and click Update. You should now see that your System URL has the identifier you entered.
    Warning: Your System URL Identifier customizes the URL for you system. This is a prerequisite for integration, allowing your users to have unique usernames. Once an identifier has been chosen, it can be modified but not removed.
  • Click Edit Settings
  • Set LDAP Integration to Yes and click Update
  • Make note of the following information
    1. Your Username
    2. API URL
    3. Token

 Installing RUDS

  

  1. Application requires Java 6, 7 or 8. Newer Java versions are not currently supported There are several options:
    1. An Oracle–licensed installer from http://java.com/en/download
    2. A free OpenJDK installer for from https://www.openlogic.com/openjdk-downloads
  2. Download and run RUDS installer - download link located at the end of this document.


Configuration


 

  1. From the Start Menu open RiskUtilities Directory Sync and run Configuration Manager.
      



  2. Click the API Tab  


    1. This panel details information about your RiskUtilities system, this information can be found by logging into your RiskUtilities system and browsing to Administration > Settings.
    2. Enter the required fields.
    3. Enter the Username of the user who obtained the token in the textField Username*.
    4. (The Username you choose cannot be a user that exists in Active Directory. It also cannot be a Username that is allowed to log in via SSO.)
    5. Click Test Connection to verify settings.

  3. Click the LDAP Tab 



    Note: Server Type can be defined as Active Directory or General, General allows for access to standard LDAP servers.

    1. This panel details information about your LDAP system. Fill in the required fields.
    2. The Base DN defined here will be used as the top level filter on all queries.
    3. Click Test Connection to verify settings.

  4. Click the Users Tab 

    Default Users Tab


    Note: Attribute mapping is pre-filled when using the Active Directory server type, General configuration requires attributes to be mapped manually.

    Users Tab with User Groups selected



    1. Optionally enter in an Additional User Base DN that will only apply to user queries. If your base DN on the LDAP tab is “dc=company,dc=com”, then entering “OU=CompanyOU” will result in queries being performed against “OU=CompanyOU,dc=company,dc=com”. You can leave this field blank to query the root DN from the LDAP tab.
    2. Click add Rule and enter in a search rule for users to sync. This is a standard LDAP query. Define as many rules as necessary to search for your users in LDAP.
    3. User Groups can optionally be synced by selecting the User Groups checkbox. 
      1. Click the Refresh Group List to pull a list of Groups from LDAP
      2. Select the desired buttons to populate the Filtered User Groups list. 
    4. Attribute Mappings associate LDAP attributes to the correct User fields in RiskUtilities. The required fields come pre-populated with the standard Active Directory attribute name, update as needed.
    5. The Username attribute is required to be a unique value for each user, this is what users will use to login to RiskUtilities.
    6. Click Test Rules and Mappings, this will run all defined rules and report any errors. Attribute mappings will also be verified. For help debugging LDAP rules please use a LDAP browser application such as http://www.ldapbrowser.com/ or http://www.jxplorer.org/.


  5. Click the Notification Tab



    1. Since the sync tool is designed to be executed unsupervised on a scheduled basis, mail notification is required to report any errors.
    2. Enter in the required fields, you may need to contact your mail server administrator for assistance with this panel.
    3. Click Test Notification to verify your settings. Verify that a test email was delivered to the To Address.

  6. Click on the Sync Tab  


    1. Save your configuration by clicking on the File menu and Save Configuration. Make a note of where you saved this file. If you make any modifications to your configuration, remember to save again.

    2. Click Simulate Sync. This process queries your LDAP server and RiskUtilities, verifying all configuration, and will report back how much data will be added, updated, and deleted.

    3. You can now run a manual sync by clicking the Sync button, this will persist changes to the RiskUtilties system.

  7. Scheduling 
    1. Run a sync using the ruds-sync command line utility 

      1. Click Start and type cmd to open a command window

      2. execute cd\[install_path], replace [install_path] with the location you installed RUDS.

      3. execute ruds-sync -a -c [filename], Replace [filename] with the full path of the configuration file you saved using the Configuration Manager.

      4. Review output to validate that sync has completed properly.

    2. Create a Schedule Task 

      1. In Control Panels, open Schedule Tasks

      2. Click Action > Create a Basic Task

      3. Enter name ‘RUDS Sync’ click Next

      4. Set the desired frequency, click Next

      5. Select Start a Program as the Action, click Next

      6. Click Browse to find the ruds-sync.exe

      7. In the arguments section add -a -c [filename] Replace [filename] with the full path of the configuration file you saved using the Configuration Manager. Click Next, Click Finish.

      8. You can right click on the scheduled task and select Run to test.

 

Monitoring

 

It is important to monitor the health of the sync tool. Be sure to review the notification emails sent by the tool. You can also verify the last sync date and time via the RiskUtilities’ Settings page.

 

 


User Access Overview


There are multiple ways to have your users notified of their credentials

    • Automatic notification on demand (default). Users are sent their credentials once they are assigned a task from RiskUtilities.

    • Automatic notification on creation

    1. Log into RiskUtilities

    2. Click Administration > Settings

    3. Click Edit Settings

    4. Enable Send User Welcome Email on User Creation option.

    • Manual notification

    1. Log into RiskUtilities

    2. Click Administration > Users

    3. Click Send Welcome Emails link in the sidebar (this will only be available if there are users that have not received a welcome email).

    4. Optionally you can force a welcome email to be sent to a user regardless if they have before by clicking on their user name from the user list. Then click the Send Welcome Email link in the sidebar.


Warning: Assignment tasks are processed on user creation, if you have an assignment that pertains to new users, they will receive an email immediately.


Troubleshooting



LDAP Connection failure - unable to find valid certification path to requested target

This message indicates that LDAP server is using a self-signed SSL certificate. You will need to configure Java to trust this cert.

    1. Run Command Prompt (as Administrator)

    2. Navigate to your Java directory ie) c:\Program Files\Java\jre7\bin

    3. Execute the following command, replace [certificate] is the file from step 1. keytool -import -keystore ..\lib\security\cacerts -file [certificate]

      1. This will prompt you for a password, enter changeit

      2. Enter yes when prompted for Trust this certificate? [no]:

    4. Restart RUDS and try your LDAP connection.

 

Sync error – You might see a message similar to the following:

[LDAP: error code 49 - 80090308: LdapErr: DSID-0C09042F, comment: AcceptSecurityContext error, data 525, v2580]

The code following the word "data" may be one of the following:
525 user not found
52e invalid credentials
530 not permitted to logon at this time
531 not permitted to logon at this workstation
532 password expired
533 account disabled
701 account expired
773 user must reset password
775 user account locked