LDAP Router Setup with CA Directory DXlink (configs for LDAP and AD)

Document ID : KB000050047
Last Modified Date : 14/02/2018
Show Technical Document Details

DESCRIPTION

This document is designed to create a "Router" in CA Directory to route your single LDAP connection to several LDAP (or AD) repositories and read in the data from the multiple sources. The connection to each LDAP (or AD) is achieved using a CA Directory "DXlink" to link to each LDAP (or AD).

If you are combining several LDAP repositories (or AD domains) you will need to ensure that the attribute you are going to look up or authenticate users against is unique across each external store. If they are not unique you will need to find a unique identifier that can be used (like UserPrincipalName) or correct the conflicts across the repositories you are combining.

SOLUTION

Preparation:

We should first start with the definitions we need to understand, the environment defaults which will be used, and the pre-requisites which should be completed before we can setup the LDAP Router with CA Directory DXlink. I will also provide a form you can provide to your LDAP or AD Admin to obtain the required information. Next I will briefly note the important AD information you should discuss with your AD Admin before you begin. This information will then be verified by testing the connection before we change any settings in CA Directory.

  • Definitions:
    LDAP     Lightweight Directory Access Protocol AD       Abbreviation for Microsoft Active DirectoryDSA      Directory Service Agent (also referred to as Directory System agent) DIT      Directory information Tree Router   Refers to a router dsa created in CA DirectoryDXlink   Refers to the CA Directory technology which connect to a remote LDAP Dxi      CA Directory (DSA) main Initialization file for the running service Dxc      CA Directory configuration files for defining the links (DXlink) to LDAP/ADDxg      CA Directory Group file used to source in required dxc configuration files
    Default Path Environment variables:
    Windows: %DXHOME% = C:\Program Files\CA\Directory\dxserver\Unix: $DXHOME =/opt/CA/Directory/dxserver/
    Pre-Requisites:

    • First you must work with your internal LDAP or AD Admin to request a service account which will need to have permissions to bind to the LDAP or AD and read attributes of other users (like MemberOf).

    • You will need the Service account users DN and password. Examples: cn=LDAPSvcAcct01,ou=people,dc=domain,dc=com cn=ADBind01,cn=users,dc=ca,dc=com

    • You will also need the base DN in your LDAP or AD which has the users in a sub-folder/ou. The more specific you are for the users

    • location the better performance you should receive. Examples: ou=people,dc=domain,dc=com cn=users,dc=ca,dc=com

    • Next you will need the hostname and port of your LDAP or AD server to connect. Examples: LDAPServer1.domain.com ADServer1.ca.com

    • LDAP and AD server generally run on port 389 for standard LDAP services but confirm with your Admin.

Required Information:

  • Use the form below to gather the information needed to complete this configuration. You may need to ask your LDAP or AD Admin for this information.

  • This may require a request for a service account to be created in the external LDAP (or AD).

  • You will require one of these completed for each external LDAP or external AD you are configuring a link to.

    LDAP HostName:
    LDAP Port:
    LDAP Base DN:
    LDAP Users DN:
    LDAP Service Account DN:
    LDAP Service Account Password:

    Optional:
    Backup LDAP Server Hostname:

IMPORTANT AD INFO:

  • IF you are using AD as your remote user repository, ask your AD Admin if you have the global catalogue port 3268 open and if it can reference all the AD Domains you need available through the router for authenticating or searching against.

  • IF this is available you can stop using this document and consider having your software (example: EEM, ServiceDesk, etc) point directly to the default AD global catalogue port 3268.

    • For EEM Please refer to the EEM Getting Started, Guide Chapter 10 titled "Configure an External Directory with CA EEM" section.

    • The EEM documentation is installed on the EEM Server along with the product and can be found in the default location below. It will have a similar location on Unix.

    • C:\Program Files\CA\SharedComponents\Embedded IAM\Doc\Bookshelf\ENU\PDF

Test Connection:

  • Once you have the LDAP Service account and the above information you can now test a connection using a standard LDAP browser like the open source JXplorer or an LDAP browser of your choice.

  • Apply the information you have to the fields below in JXplorer. If using another LDAP browser or bind/search tool please apply the information based on the logical locations for the information.

  • I will be using the sample information in my example screenshot of the JXplorer connection window which follows.

    Example Info:
    LDAP HostName:
    LDAPServer1.domain.com
    LDAP Port: 389
    LDAP Base DN: dc=domain,dc=com
    LDAP Users DN: ou=people,dc=domain,dc=com
    LDAP Service Account DN: cn=LDAPSvcAcct01,cn=users,dc=domain,dc=com
    LDAP Service Account Password: P@ssw0rd123

    Figure 1

    Tip: You can click the Save button to save the connection details (minus the password) for use or testing at a later time if needed .

  • Click OK button to test the connection.

  • You might also use ldapsearch on Linux OR dsquery on Windows to look up this information.

  • Once you have confirmed you can connect to each of the remote LDAP or AD instances you can proceed to the CA Directory Router/DXlink setup.

SETUP:

We will be completing the below phases to achieve a CA Directory router/DXlink configuration.
They were tested on CA Directory 12.0.4355 but should apply to other builds of CA Directory r12

  1. ROUTER: Run the dxnewdsa command to create the dxi file (Directory dsa info file)

  2. GROUP: Create the .dxg (Directory Group File)

  3. DXLINK: Create the .dxc (Directory config files) for each LDAP/AD connection.

    Below is the communication and configuration architecture:

    Embedding Software (EEM) ->   LDAP_Router.dxi  ->  LDAP_Router.dxg ->  LDAP_1.dxc                                                                        LDAP_2.dxc OR for AD setups:                               AD_Router.dxi    ->  AD_Router.dxg   ->  AD_1.dxc                                                                        AD_2.dxc 
======================================================================================================
  1. ROUTER:

    • ? Run the dxnewdsa command on your version of Directory so the router file created reflects the version and features available.

      • For format and options of dxnewdsa run the command with no parameters.

    • NOTE: On Unix/Linux you will need to change to the Directory user (dsa by default) before you can run this command. Please use the command below.

      • su - dsa

    • Next run one of the commands below to setup a CA Directory Router for your LDAP or AD.

      LDAP:

      • dxnewdsa -t router LDAP_Router 30389 o=CA

      AD:

      • dxnewdsa -t router AD_Router 30389 o=CA

      • Active Directory Note : if you are using AD_Router in the command you should continue to change the naming convention to reflect an AD backend throughout the document by changing references to LDAP with AD

      Example screen output:
      C:\Documents and Settings\Administrator>dxnewdsa -t router LDAP_Router 30389Writing the knowledge file...knowledge file writtenWriting the initialization file...Initialization file writtenStarting the DSA 'LDAP_Router'...Installed the CA Directory - LDAP_Router service.LDAP_Router starting..LDAP_Router started
    • Now open the dxi file created for the Router . The file name should be LDAP_Router.dxi or AD_Router.dxi located in the default below path below.

      • Windows: %DXHOME%\config\servers

      • Unix: $DXHOME/config/servers

    • Change the knowledge section in the dxi file to refer to a group file so you can then define a connection to each LDAP instance. We will create the actual Group file in a later step.

      • Change
           source "../knowledge/LDAP_Router. dxc";    to    source "../knowledge/LDAP_Router .dxg";                 Example: (knowledge section from the LDAP_Router.dxi)# knowledgeclear dsas;source "../knowledge/LDAP_Router.dxg";
    • IMPORTANT: Add the following line at the end of the same dxi file.
      set transparent-routing=true; 
  2. GROUP: Create the Router group file (LDAP_Router.dxg or AD_Router.dxg) to source in the dxc files which will connect to the remote LDAP/AD repository.

    • The Router Group file should be created in %DXHOME%\config\knowledge folder for Windows and under $DXHOME/config/knowledge directory for Unix.

    • The first line will refer to the already existing LDAP_Router.dxc file (or AD_Router.dxc).

    • The following lines (2,3,4.etc) you should add based on how many LDAP's you will be connecting to. The file names you add here will be created in phase 3.

    • Below examples are for 2 remote LDAP's or 2 AD's. Please add or remove based on your needs.

      LDAP FORMAT:

      # Computer Associates DXserver/config/knowledge/sample.dxg # # sample.dxg written by samples/router/setup # # Description: #   This file shows how DSA knowledge can be grouped and shared. #   This file is source this file from the Router initialization file. # # Source the knowledge files of the LDAP/AD Router below. # source "LDAP_Router.dxc"; source "LDAP_1.dxc";source "LDAP_2.dxc";
      AD FORMAT:

      # Computer Associates DXserver/config/knowledge/sample.dxg # # sample.dxg written by samples/router/setup # # Description: #   This file shows how DSA knowledge can be grouped and shared. #   This file is source this file from the Router initialization file. # # Source the knowledge files of the LDAP/AD Router below. # source "AD_Router.dxc"; source "AD_1.dxc";source "AD_2.dxc";
  3. DXLINK:

    • Manually create the .dxc custom DXlink configuration files to make the connection to your remote LDAP repositories (AD, Directory, etc) based on the templates provided.

    • Create each .dxc filename which you listed in the dxg group file (LDAP_Router.dxg or AD_Router.dxg) in phase 2 using the Sample DXlink config Templates on the next page of this document.

    • Create the .dxc files in the locations below. Windows: %DXHOME%\config\knowledge Unix: $DXHOME/config/knowledge

    • You will be creating one .dxc file for each LDAP or AD connection you are sourcing.

      Examples:
      LDAP:
      Based on the LDAP_Router.dxg file I have used as a sample, I created the LDAP_1.dxc and LDAP_2.dxc files in the knowledge folder.

      OR

      AD: Based on the AD_Router.dxg file I have used as a sample, I created the AD_1.dxc, AD_2.dxc files in the knowledge folder.

    • The sample template files below/attached can help you to create the LDAP/AD connection files.

    • They should be basic text files with the proper .dxc extensions.

    • IMPORTANT: Make sure they are not created as .txt if you have hidden extensions on Windows

    Important Tips:

    • If you are creating several LDAP/AD router files verify that the dsa name in line 1 and 5 of the file are unique.

    • Change the "<dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE>" in the Prefix and native-prefix lines to base domain name.

      Example: <dc com><dc acme>
      Note: The domain syntax is in reverse order.

    • Replace the 'ldap-dsa-name' parameter's value below with an actual bind DN of your LDAP/AD server.

    • Replace the 'ldap-dsa-password' parameter's value below (mentioned as "USER_PASSWORD_HERE") with an actual clear-text password for this bind DN account.

    • Replace "LDAP_SERVER_NAME_HERE " below with the name of your LDAP/AD server.

    • The port 389 is the LDAP default communication port; if your LDAP/AD communication port is different change this to reflect it.

    • Port 3268 can be used by AD specifically as a global catalogue and indexing port known for increased performance.

    • The "read-only" dsa-flag prevents updates to LDAP/AD from the Policy Server (even if the account used by the user data store has domain admin privileges).

    SAMPLE DXlink config templates (.dxc):

    • Replace the NAME_HERE with the type of information noted.
      # Computer Associates DXserver/config/knowledge/# Manually created file for DXlink to AD#=====LDAP TEMPLATE===============set dsa LDAP_1 ={prefix        = <o CA><o LDAP_1>native-prefix = <dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE>dsa-name      = <dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE>dsa-password  = "secret"ldap-dsa-name = <dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE><ou USER_ORG_UNIT_NAME_HERE><cn USER_HERE>ldap-dsa-password = "USER_PASSWORD_HERE"address       = tcp "LDAP_SERVER_NAME_HERE" port LDAP_PORT_NUMBER_HEREauth-levels   = clear-passwordtrust-flags       = no-server-credentials, allow-upgrading, allow-check-passwordlink-flags          = dsp-ldap};#================================= # Computer Associates DXserver/config/knowledge/# Manually created file for DXlink to AD#======AD TEMPLATE================set dsa AD_1 ={prefix        = <o CA><o AD_1>native-prefix = <dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE>dsa-name      = <dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE>dsa-password  = "secret"ldap-dsa-name = <dc DOMAIN_EXTENSION_HERE><dc DOMAIN_HERE><ou USER_ORG_UNIT_NAME_HERE><cn USER_HERE>ldap-dsa-password = "USER_PASSWORD_HERE"address       = tcp "AD_SERVER_NAME_HERE" port AD_PORT_NUMBER_HEREauth-levels   = clear-passwordtrust-flags       = no-server-credentials, allow-upgrading, allow-check-passwordlink-flags          = dsp-ldap, ms-ad};#==================================
    • Restart the dxserver service for the dsa created LDAP_Router or AD_Router from the command line or from Service panel in Windows (CA Directory - AD_Router).

    • Windows : Set the Service to Automatic startup in the service properties and set the service to restart in the Recovery tab for at least the first and second failure.

    • Move onto the next page to test your connections.

    TEST Connection:

    • I would suggest using an LDAP browser (like JXplorer) to do the connection testing.

    • Test a connection to the LDAP/AD Router on the CA Directory server name as the host and the router port of 30389 with an anonymous bind (no user or password).

    • The anonymous bind should work as the .dxc files with the ldap-dsa-name and ldap-dsa-password are binding with those credentials.

      • These credentials in the .dxc files need to be correct if the bind is to work.

      • Also the permissions of this bind user must be allowed to bind and see other user's group membership (memberOf).

    • The native-prefix is where the dxc file will connect in the LDAP structure and the users and information there will be displayed in your LDAP browser or product (like EEM) when you connect.

    • The "prefix" defines where it will be mounted and displayed from within your LDAP browser or connecting product (like EEM).

    • If you cannot see any information after connecting to the Router make sure to look at the logs in the C:\Program Files\CA\Directory\dxserver\logs folder which relate to the Router you created.

      • The _ALARM and _TRACE should help find any issues you may have.

      • If you make adjustments to the configuration remember to restart the service LDAP_Router or AD_Router and then refresh the _TRACE file for the service.

      • Look at the last few lines in the logs for clues as to what might be causing a problem.

      • If further assistance is needed contact CA Support for review of these log files and the setup.

    • IF your connection is showing your LDAP or AD information properly you have completed the setup successfully. Congratulations!

      • Please note the other details related to EEM or AD setups in the References section below if required.

    References:

    EEM IMPORTANT Information:

    • In EEM you will configure the GlobalUsers/Global Groups screen to point to the hostname of the CA Directory Server and the port seton the Router configuration (example port: 30389)

    • You will NOT need a user DN or Password since the dxlink files you created will have connection credentials for each separate LDAP orAD it is connecting to. Please leave them blank.

    • If you followed the suggested settings in this document your Base DN to use in EEM will be o=CA and should match the prefix setting inyour LDAP_Router.dxc (or AD_Router.dxc) file.

    • If using EEM to connect through the Directory Router it is suggested to change the <LDAPAutoReferral> setting in the iPoz.conf file tofalse (See below)
           <LDAPAutoReferral>false</LDAPAutoReferral>
    • This will prevent EEM delays when responding to referrals passed by certain versions of CA directory when one of the remoteAD/LDAP's are down.

    • If you are using AD you may need to set the paging feature to true to ensure EEM can read in multiple AD's in the Manage Identitiesscreen. Please set the below in the iPoz.conf and restart the iGateway service to take effect.
           <ExternalDirPaged>true</ExternalDirPaged>
    • If you are using LDAP you may need to increase the Search limits in the LDAP OR expect you will only be able to do specific searches toview users in Manage Identities

    Troubleshooting:

    • ERROR: remoteCacheData: Too many attribute

      Problem: If you are setting up a connection to AD and you get this error below, you did not set Transparent-routing to true in the dxi file.
      Solution:
      Add line below to the end of the AD_Router.dxi file.
            set transparent-routing=true; 
    • ERROR: CANNOT RESOLVE ADDRESS

      Problem:
      This is usually related to dns failures.
      Solution: Check the hostnames in dns with the nslookup command. If they are not found you may need to use IP instead of hostname OR add the hostnames to the hosts file of the machine running the CA Directory.

    DXNEWDSA command format:
        C:\Documents and Settings\Administrator>dxnewdsa    Usage: dxnewdsa [-t type] [-l dblocation] [-s dbsize] dsaname port [prefix]    where:       type       is the type of DSA. Valid options are:           data (default)           router       dblocation is the database file location (default $DXHOME/data)       dbsize     is the database file size in MB (default 500MB)       dsaname    is the name of the DSA       port       is the port number of the DSA       prefix     is the DSA prefix       For example       dxnewdsa -s500 mydsa 1000 "ou=Internet Sales,o=ACME CORP,c=US"       dxnewdsa -trouter myrouterdsa 54321 "ou=Internet Sales,o=ACME CORP,c=US"    dxnewdsa r12.0 (build 4355