Active Directory Integration Update for Existing Customers


Technical Overview


** Updating the 64 Bit RiskTool Directory Sync


1.) Copy and save the "RUDS_config.xml" .......as a backup file.  Uninstall RUDS and download the new version "RUDS_windows-64bit_x64_5_0".  (Bottom of this article.)

2.) When you run this for the first time click on "file"> "open configuration"...... browse and select the saved copy of the "RUDS_config.xml" file in step 1 and click "open".

3.) In RiskTool under "Settings" The only thing you need to modify now is under the API tab.  Update your url, User Name and Token.





Initial Installation Instructions for reference......


What is RiskTool Directory Sync?


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

 


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 RiskTool system and queries users and organizations.
  • These lists are compared and changes are made to the RiskTool 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 RiskTool over the internet is via HTTPS.
  • No modifications are made to your LDAP server configuration or data.


 

 

Getting Started

 

Setting up your RiskTool System

 

  • Login to your RiskTool 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, download and run installer from http://java.com/en/download if not already installed.
  2. Download and run RUDS installer - download link located at the end of this document.


Configuration


 

  1. From the Start Menu open RiskTool 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 RiskTool. 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 RiskTool.
    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/.


  6. Click the Notification Tab
    Since the sync tool is designed to be executed unsupervised on a scheduled basis, mail notification is required to report any errors.

    1. Enter in the required fields, you may need to contact your mail server administrator for assistance with this panel.
    2. Click Test Notification to verify your settings. Verify that a test email was delivered to the To Address.

  7. 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 RiskTool, 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 RiskTool system.

  8. 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 RiskTool’ 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 RiskTool.

    • Automatic notification on creation


    1. Log into RiskTool

    2. Click Administration > Settings

    3. Click Edit Settings

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


    • Manual notification


    1. Log into RiskTool

    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


API WebService Fail - Sync Failure


Use the attached certificate (rtprod.crt) (which you can obtain if you wanted to use an openssl client).  To use the attached certificate, browse to your local cert store on your machine where RUDS is installed (this could vary based on the machine) and run the following command as administrator:

 

keytool -import -alias "www.risktool.com" -keystore <keystorefilename> -file rtprod.crt

 

Only variable being the <keystorefilename>, so it would look like this if they use the typical cacerts standard:

 

keytool -import -alias "www.risktool.com" -keystore cacerts -file rtprod.crt

 

You will then need to close RUDS and re-open it for Java to read the new certificate locally.




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