Communicating with LDAP is a common function in Aegis automation workflows across a wide variety of use cases.
Most use-cases are simply to find or modify information as part of a larger workflow in an integrated fashion. For example if a VMWare Provisioning request is received from a user, we can determine that persons group memberships, his managers details for approval etc. in order to progress the workflow without user-interaction. We can also run more LDAP centric workflows where we search for inactive or disabled accounts for routine maintenance for example.
Already I have some LDAP Activities for Active Directory here but the LDAP Adapter brings a much tighter integration with many more features as well as working with NetIQ eDirectory, Active Directory and OpenLDAP and compatible Directories.
Adapter Instances are configured via Adapter Configuration Utility in the normal way as other adapters. Adding connection info is mandatory obviously to connect to your system, but advanced options can be left as default values. The account chosen to connect to the directory will effect what operations can be run - so you need to use an account with adequate permissions to perform the tasks you want.
The ‘Test Connection’ button verifies if the target directory can be connected to, bound with the account specified and that the Base Context Path provided (not required for eDirectory) is valid. The Base context serves as the default Context for searches in activities but can also be overridden by other values specified in activities.
The 3 Types of Directory work very similarly in almost all cases, and it is entirely possible to configure a different type of directory and it may work at runtime. However the adapter automatically formats values such as datetime into the format expected by the directory so some things will not work.
The ‘Events’ button brings up the event configuration UI to configure what type of events to generate in Aegis.
The Help Icon on the bottom left brings up the Configuration Help.
The ‘Events’ button in the Adapter Configuration Utility brings up the event configuration UI to configure what type of events to generate in Aegis.
You choose what generates an event in Aegis based on an LDAP filter you specify. Specify the filter, and choose to generate events by changes to creation time, modification time or all objects.
The example in the screenshot shows a new event based on objectclass=user.
The searchbase is empty so the search base defined in the adapter will be used, and Scope is ‘Sub’ which means it will search in all locations with the search base as root.
Time Filter Type is ‘Creation time’.
What happens during an event poll is that the supplied filter will be modified to include a time range component based on the objects creation time. The adapter remembers the last poll time.
The first time the adapter polls for the event, it goes back the ‘Rewind Seconds’ value in time to start polling.
Replication Latency makes allowances for replication delay in your directory infrastructure.
Events generated by the Adapter can be viewed and filtered in the Aegis Web Operator Console:
Event Definitions for Triggering can also be created as normal with the IQLdap Event type attributes:
If a configured server cannot be bound during event polling, an event is generated in Aegis.
The adapter allows for browsing of the Directory Tree with the Namespace Browser in the Configuration Console. It does not implement all directory object types, just many of the more popular types.
As usual the Namespace is a great tool for troubleshooting connections, checking object attributes etc. However the out of the box ‘find objects’ activity won’t be able to search beyond the instances of the adapter as it would be an inefficient way to search the directory. Apart from objects at the Top Level, all object data is pulled live from the Directory.
Access Directory Objects in Aegis Namespace:
Additionally, the Aegis Namespace allows you to browse object classes in the LDAP schema, and see what attributes are mandatory for object creation. It also allows you to check how attributes are defined:
Also in the next screenshot you can see an object class for IQLdap_NCPServer. This is specific to eDirectory, where you can see eDirectory Servers, replica and partition information. You can monitor the status of your eDirectory Server and generate an event in Aegis if the object status is not equal to 2 .
The adapter provides 9 activities which interact with the Directory. Please note that behavior of some activities will vary depending on the type of directory you connect to.
For example, if you move an object in Active Directory, it can be renamed immediately. If you move an object in eDirectory, you need to wait for the change to replicate to all replicas before the object can be renamed. Basically your workflow will have to abide by the rules of the target directory.
Object Query Activity
This activity allows to you search for any objects in your directory matching an LDAP Filter. You also get to choose the scope of the search, the maximum number of results (0 gives the Max allowable results) and the Search Base. If left blank, the search base defaults to the default base for the LDAP instance in adapter configuration.
The result of the activity is an array of matched objects and an integer value specifying the number of results.
Activities which have Directory Tree input, can have either the directory alias or the locator (as in screenshot) value specified. Note however, if you have an activity which also specifies an object, and if the object is entered as a namespace locator, then the Directory Tree input is ignored
Get Object Attributes Activity
This activity allows you to get a list of attribute values from any object. The Attribute input is an array of attributes. Note that the adapter will convert all attribute values into string human readable format. For example the GUID is stored in the directory as an octet string and is converted into a string by the adapter. NetworkAddress is also a complex data type. Complex Data Type handling is discussed further on in this article, but here you can see for this activity you don’t need to worry about what data type the attribute is.
Also you can see in this case that the networkaddress attribute has more than one value, an IP address and a TCP address. Multiple values are delimited by the delimiter chosen when configuring the adapter instance. Care must be taken to ensure that a delimiter is chosen which is not going to be used in an attribute value.
Add Object Activity
This Activity allows you to add object to your directory, for example Users, Groups, Computers, and OUs. You need to provide a table with attribute name /value pairs. There is an activity in the IQLdap Activities library with this table prepared. You can use the Namespace browser to browse the schema for each object to determine what attributes are mandatory for object creation.
The DN of newly created object is available as output.
Rename Object Activity
This activity allows you to rename an object in your directory. You need to specify the existing object and the new RDN of the object. The output makes the new DN available for the object.
Move Object Activity
This activity allows you to move objects from one location to another. You cannot however move container objects. The new DN of the object is available as output.
Delete Object Activity
This activity allows you to delete an object in the directory. The result is simply True or False. If False however the activity will throw an error which will need to be handled in order to determine why the deletion failed.
Modify Object Activity
The modify object activity lets you change attributes of an existing object. There are three different modification types – Add, Replace and Delete. When to use these will depend on whether an attribute is a multi-valued attribute or not. Please note that a multi-valued attribute in one directory type may be single valued in another .
For Single Valued Attributes:
Using the ‘Replace’ modification type is safest. You replace the existing value with something else. You can still use Add and Delete but activity will fail if you try to add a value when a value already exists.
For Multi-valued Attributes:
You may want to add to an existing attribute another value - Then use Add modification Type. If the attribute is has no value, it will add a first value.
Delete will delete the specified value from the Attribute.
So how do you know if an attribute is multi-valued or not (via Aegis)? You can check the schema via the namespace or run the ‘Get Attribute Definition’ activity…
Get Attribute Definition
This activity allows you to find out information about an attribute for a specified directory object. For example in this directory (Active Directory), the description attribute is a Multi-Valued Attribute. Some attributes will also have a defined maximum length which is also presented at output.
However, even the above example isn't actually accurate as caveats can exist depending on the directory you connect to. If you try and set more than one value for the description attribute in AD, it will fail. Via Active Directory Users and Computers UI the Description value is presented as a single value, so you can’t try to add multiple values. If you edit an object via ADSI editor, description attribute will be displayed as a multistring value, but if you try to assign a value it will fail. So the Ldap Adapter operations must conform with the rules of the target directory, even if sometimes those rules aren't that obvious!
LDAP data Format Operations Activity
This activity doesn't interact with the directory at all. It allows data to be converted for special scenarios like preparing values for a filter. For example if you want to find an object by its GUID/ObjectGUID, you can’t do a filter like this:
That is the same GUID by the way, there is a little re-arranging going on!
At the moment there is a limited number of conversions but its a growing list and I can expand this over time as required.
Find IQLdap Instances Activity
This is just a Find Objects activity pre-configured to find IQLdap Instances so isn't a new activity. You will see however that you cannot choose objects below the Top Level Container. Any searches in the directory should be made via the Object Query Activity.
Complex Data Handling
Data stored in Ldap Directories are stored in various formats depending on the type of data. There are simple data types like numbers and strings but there are also complex datatypes like binary streams and octet strings and arrays of various data types.
For the example of the GUID/ObjectGUID attributes, when you request this attribute value, the data is converted from data in a byte array, into a Display Format compatible with Aegis Data types so it is displayed in the format you would expect.
Any time you want to find out what format you should give an attribute value, you can first query an attribute of that type to see what its value is. When you add or modify an attribute value that value will be automatically converted into the correct datatype and stored in the directory.
The Object Query activity is the only activity where data conversions do not take place. The query is executed as is. As previously mentioned, to query based on GUID/ObjectGUID, you can’t do a filter like this:
The IQLdap Adapter is an Adapter developed by the Community for the Community almost 2 years in the making, so it does have some limitations! Future versions will hopefully whittle these limitations down a bit.
The Aegis Namespace Browser shows a limited number of object types.
Activities are generic to all object type – i.e. no specific ‘Add User’ or ‘Add AD User’ activity.
Manual Installation steps required.
Search Object results are limited to 250 objects
25 Objects in each container are viewable in the Aegis Namespace.
1 Directory with 1 monitored event filter can be used.
License: There is no license for this version. The system generates a trial license and will expire, but the adapter will keep running even after expiration so you can ignore any pop-ups.
Data Types - Most of the more common data types work with the adapter. If the adapter finds an attribute which is doesn't know, it will attempt to convert it. If you find a datatype which isn't handled correctly please let me know, as well as an example which I can use to test.
IQLdap Installation Instructions - (A Readme.PDF is also attached which includes pictures)
Aegis Versions IQLdap is built for Aegis 3.0 (and above) and is on 64 bit systems only although it should work on 32 bit systems. All instructions below are for 64 bit systems but you can work out 32 bit equivalent
This version of the adapter is the Community Version as is not supported and should not be given to customers without agreeing to the disclaimers on the Community Site.
Installation Aegis Needs to be up and running until told otherwise!
Copy the IQLdapAdapterXXXXXX.zip file to your installation folder:
<installdrive>:\Program Files (x86)\NetIQ Aegis should be a sub-folder at this location. This location will be referred to as <installpath> in the next steps.
Unzip IQLdapAdapterXXXXXX.zip to the <installpath> directly. Do not unzip it to any subfolder extract to the existing Aegis folder structure. This can be verified by checking that following file exists – if it doesn't you have done unzipped the file to the wrong location! <install path>\Program Files (x86)\NetIQ\Aegis\IQConnect73\bin\IQLdap.dll
Open an elevated command prompt (Run As Administrator) and navigate to: <installpath>\Aegis\IQConnect73\bin
Execute the register_IQLdap.cmd command, with the following parameters: server hostname or FQDN (IP address will work but will need to be updated if it changes in the future) running the "NetIQ Aegis Namespace Provider" service port the port the "NetIQ Aegis Namespace Provider" service runs on (probably 2219) domain of service Aegis Service account service account the Aegis Service Account Service Account Password the Aegis Service Account password
There is a multi-value string value here called providers which contains a number of adapter names including PG and IQSCH. Do not confuse with the subkey of the same name! Add IQDotNetProvider:IQLdap to this list.
Open the NetIQ Aegis Adapter Configuration Utility - You should have an IQLdap entry in the List. Add a new instance under IQLdap and Configure. Click 'Test Connection' to verify.
Save and exit the NetIQ Aegis Adapter Configuration Utility
Restart NetIQ Aegis Namespace Provider Service and dependant services (NetIQ Aegis Engine, NetIQ Aegis Activity Broker) and the NetIQ Aegis Business Services service.
In Configuration console, open workflow designer - choose to open the IQLdap Activities Library if it is not listed in Activity Libraries.
Use namespace browser to verify the connection to your directory.