|This week's theme: Cool Tech Tips|
This week's topic was recommended by a member of the AR System Developer Community.
Using Active Directories with ARDBC LDAP
Last week's Tips and Tricks article describes how to use Active Directories for authentication using AR System® External Authentication for Lightweight Directory Access Protocol (AREA LDAP). As a next step, you may want to consider dynamically accessing that user data from a Vendor form. This week's article describes how to use Active Directories with AR System Database Connectivity (ARDBC) LDAP Vendor forms.
There are many things that you can do with Vendor forms, such as:
- Access Active Directories data from Search Menus within AR System forms
- Populate user data into your AR System Application by using a Set Fields action with a Filter, Active Link, or Escalation
- Use an Escalation to push Active Directories data into an AR System form
- Modify Active Directories data
- Create new Active Directories users and other objects
To use the ARDBC LDAP plug-in with Active Directories, you will need to configure the ARDBC LDAP Configuration form, create and configure a Vendor form, and potentially configure Active Directories.
The ARDBC LDAP Configuration form is where you provide basic connection information so the ARDBC plug-in can communicate with Active Directories.
Note: Click images for full screen view.
Figure 1 – ARDBC LDAP Configuration Form
Here are brief descriptions of the important fields on this form and how to obtain the appropriate values:
- Host Name: This is the host name of the LDAP server. If you are using SSL, this should match the name for which the server's certificate was issued.
- Port Number: This field is optional. If Use Secure Socket Layer? is not selected, the default, port 389 is used. If Use Secure Socket Layer? is selected, port 636 is used.
- Distinguished Name: For Active Directories, the value can be the actual login name or the distinguished name of a user with appropriate permissions to query the data specified in the Vendor form. For example if you are using the domain administrator account, you can simply use a value of <Domain>\<accountname>, such as JETSONS\Administrator. Knowledge Base #10604 from Remedy's support website provides more details on obtaining this value.
- Password: Type in the password for the account used in the Distinguished Name (dn) field
- Use Secure Socket Layer?: If you plan to use SSL for this ARDBC Plug-in, select Yes. Since SSL requires additional setup in this form and outside of AR System, you may want to experiment without SSL first and then add this option later. If you choose Yes, you will need to provide the path to the Certificate Database later.
- Certificate Database: Enter a value in this field only if you are using SSL. You will need to obtain a cert7.db file since AR System uses the Netscape LDAP SDK, which requires this cert7.db file. One way to obtain the cert7.db file is to install Netscape Navigator 4.7x on the AR System box. Locate the cert7.db file and provide its location in this field.
Before creating a Vendor form, you need to know the location of your users and what attributes you would like to access. Since it is relatively easy to create a Vendor form, you may decide to create different forms on the same data. For example, you may want to create a Vendor form that accesses all corporate users and another form that only accesses users in a particular office.
It is very important that you identify an attribute in your data that will always have these three properties:
- 15 characters or less
Later this attribute will be mapped to the RequestID field. If you do not have an attribute that is guaranteed to meet these three requirements, you must create an attribute that will have these properties and populate it with data.
From the Remedy Administrator, create a new Vendor form Server Object:
Figure 2 – Creating a Vendor Form
Available Vendor Names: Choose ARSYS.ARDBC.LDAP. You will see a list of tables on the right. If not, the ARDBC LDAP Configuration form was not configured properly or the plug-in is not working. Verify the data in the ARDBC LDAP Configuration form and check the arerror.log for related errors.
Available Vendor Tables: This list contains all containers off of the root dn. Since by default, user information exists in the CN=Users container, and not the root dn, you will need to make some minor adjustments later. For now, select the container that shows the appropriate filter. For example, to access user information, choose the line that ends with (objectclass=user).
Available columns: Select one or more attributes that you would like to access in your Vendor form. You can add or remove attributes later as well.
Click on Create to create your new Vendor form.
The two keys to a good Vendor form are the LDAP Search string (since it contains the query used to find your data) and the Request ID mapping. Please refer to Chapter 15 in the Developing AR System Applications: Advanced book for more information.
With your Vendor form open, click on Form/Form Properties/Vendor Information/Table Name. You will see the LDAP Search string such as ldap://astro/dc=jetsons,dc=remedy.dc=com??sub?(objectclass=user)
For Active Directories, your users may exist in the default container CN=Users. So modify this LDAP search URL to read: ldap://astro/cn=Users,dc=jetsons,dc=remedy.dc=com??sub?(objectclass=user)
You can also use this search string to change the filter to something more specific. For example, if you want to limit your search to users in the user objectclass but only to those users whose samaccountname starts with 'A', you could modify the string to read:
If you want to return only users who have a non-blank employeeId, use this example:
Modifying the LDAP search URL string may require some LDAP knowledge but it is important to know where to make this modification.
The RequestID is used to retrieve data for each record returned in a query from the Remedy User tool. It is important to assign an appropriate value to the RequestID.
Figure 3 – Configuring the RequestID
Using the Remedy Administrator, open the Vendor form. In the Vendor Information section on the Database tab, replace RequestID in the Name: field with an attribute name such as samAccountname.
To add a new attribute to the Vendor form, right-click in an open area of the Vendor form. Click on Field from ldap://... to see a list of the available attributes. If you see the attribute you want to add, simply click on that attribute and a field will be created for you on the form. If you do not see the attribute you want to add, then after right-clicking on the form, choose Character field. Double-click on the new field and give it a name. Then choose the Database tab and set the desired attribute name in the Vendor Information/Name field.
If any of your attributes are multi-valued attributes, you need to suffix the Vendor Information/Name field value with [*,]. For example, Objectclass should read 'objectClass[*,]'. This identifies that commas will delimit the multiple values stored in this attribute.
Note: If you are using your Vendor form to create user entries in your Active Directories, then make sure to include the following attributes. Depending on your environment, you may also need other attributes such as userPrincipalName (the user's login name).
You may want to auto-populate the dn (distinguished name) field since it is lengthy and the value may not be obvious. Typically the dn would be the value of the cn attribute plus the container name.
Create a filter to set the value of dn. For example: ( "CN=" + $cn$) + ", CN=Users,DC=ntense,DC=remedy,DC=com"
As mentioned in the section above, you must have a Request ID field that maps to an attribute that meets some specific criteria. It is possible that you will need to add an attribute to achieve this.
Active Directories treats searches off the root dn in a peculiar way. Since it is possible that you have a Forrest of Domains, a root search may need to 'refer' you to another location to perform your query. The ARDBC LDAP plug-in does not know how to handle 'referrals' so Microsoft recommends that you use LDAP port 3269 rather than 389 to avoid the referral. You could also avoid referrals by not performing searches on the root dn.
Active Directories has a setting, MaxPageSize, that defines how many records will be returned in a single results page. Multiple pages are supported in LDAP version 3. Since Remedy's current ARDBC LDAP plug-in is based on LDAP version 2, only the first page is available to the Vendor form. If your MaxPageSize is smaller than the number or records you need to access, you must increase the value of MaxPageSize. This is performed using the NTDSUTIL.EXE utility. See Knowledge Base entry # 11574 on Support's website for more details on using this utility.
Once you have the Vendor form created, test it to make sure all of the desired functionality works. Open the Vendor form in the Remedy User or Web Browser and perform a Search. And if needed, test modifying and creating data in the Vendor form.
Now you should decide how you will use this Vendor Form. A couple scenarios are included below to help identify possible solution.
Scenario 1: You are going to use AREA to allow users who do not exist in the user form to authenticate. Many of these users will be using Remedy Help Desk and need to exist in the SHR:People form. To eliminate duplication of effort, your goal is to leave these users out of the user form.
Solution: Setup AREA LDAP and ARDBC LDAP Vendor form with the appropriate attributes to push into the SHR:People form. Create an Escalation to run against the Vendor form. Set the Run If qualification to select only those users who belong in the SHR:People form. Alternatively, you can modify the Form/Vendor Information/Table Name property to modify the LDAP search string filter so that the Vendor form only accesses those users who belong in the SHR:People form. The If Action should perform a Push fields into SHR:People if the samAccountname is equal to the Login Name. If you run this escalation periodically, you can keep SHR:People in sync with Active Directories.
Scenario 2: You have a customer form that contains employee information. Since much of the employee information already exists in Active Directories, you don't want to duplicate efforts by storing the information in an AR System form. But you do want to be able to view information such as location, employeeId, email address, phone number, etc. from your AR System employee form.
Solution: Create a Vendor form that will access your user information. Make sure all the data you want to view in your employee form is available on the Vendor form. Create Active Links on the employee form that perform Set Fields actions to populate Display-Only fields from data in the Vendor form. You can use Set Fields if qualifications that will locate the data in Active Directories via the Vendor form.
In summary, last week we described how you could use Active Directories for authentication using AREA LDAP. This week we described how to dynamically access data using Active Directories and ARDBC LDAP with Vendor forms.
Remedy Support Technical Group Lead/Windows Server Team
Joined Remedy in May 1997