Active Directory Adapter
- Home
- Neuron ESB
- Development
- Developing Neuron Applications
- Connecting to External Systems
- Adapters
- Neuron Adapters
- Active Directory Adapter
Introduction
Neuron ESBs CU4 Active Directory (AD) Adapter simplifies your efforts to make your AD Server(s) part of your Neuron ESB-based integration infrastructure. Using the Neuron ESB Active Directory adapter, organizations can incorporate AD into their Business Process automation and management solutions to automate tasks involved in new hire and user/group provisioning scenarios. The Neuron ESB Active Directory adapter can function as either a publishing or subscribing endpoint to the bus. In Publish mode, the adapter can monitor an organizations AD server for specific changes/events (i.e. password change, deleted user, etc.), publish those changes to bus where they would be routed to all interested subscribing users or Business Processes/Workflows. In Query mode, the AD server can be queried for information, or existing users and groups can be updated, added or deleted. Users and Groups can also be enabled/disabled and passwords can be reset.
Before reading this document
If you are not familiar with Neuron ESB Adapters, take a moment to consult the Adapter Overview. This document assumes you have the following knowledge:
- What adapters are and how they are leveraged in Neuron ESB
- Register a Neuron ESB Adapter within a Neuron ESB Solution
- Create an Adapter Endpoint in a Neuron ESB Solution
- Set a Neuron ESB Adapter Endpoint Properties
- Invoke a Neuron ESB Adapter Endpoint
Supported Modes
The AD Adapter supports 2 modes:
- Publish: Used to monitor a specified AD Server and Path. This mode receives events from the AD Server and publishes the event data to the bus. Note: each published message contains the details of only one record.
- Query: Used to perform record retrievals for a specified AD Path as well as to perform a Create, Update or Delete operation on an AD record like a user or group. A request message is received by the AD Adapter Endpoint which in turn provides a response message that contains the data for the record(s) in the result set. Note: the results returned can be for multiple records. This is determined by the Search Scope Property.
AD Adapter Properties
Every Neuron ESB Adapter has design time properties that can configured within a standard Microsoft property grid (as shown below). These properties are used to determine the behavior of the adapter at runtime. The AD Adapter Properties fall into two classes:
- General: Applies to modes (Publish and Query)
- Publish: Applies only to the Publish Mode
General Properties
Search Scope
This property defines the Search Scope that is used to determine the level within the Search Path that events should be monitored and received. This works in conjunction with the value provided in the Publish Mode Search Path Property. This property can have one of three values:
- Base: Also known as zero-level. Only the base object defined by the Search Path is queried.
- OneLevel: Indicates a search of all AD objects immediately subordinate to the base object represented by the Search Path, but does not include the base object itself.
- SubTree (Default): This is a combination of Base + OneLevel. Indicates a search of the base object and the entire subtree of which the base object as defined by the Search Path, is the top most object.
Domain Name
This is the name of the server (specified by either the name or the IP Address) that hosts the AD Server that the AD Endpoint connects to for its operations.
Domain Membership
Domain Membership property (and its subordinate property, Windows Credential) controls the security context for all operations of the adapter against the AD server specified in the Domain Name property. This property can be one of two values:
- Member: Indicates that the Adapter Endpoint will run in the security context of the Neuron ESB Runtime or the RunAs Credential for the Adapter Endpoint (if specified). That security context will be used to authenticate and authorize the connection to the server specified in the Domain Name Property. This property should only be set if the Neuron ESB machine is on the same domain as the AD server.
- NonMember: When the Member value does not apply, the NonMember value provides the ability to specify a Windows Domain Credential that is used to authenticate and authorize. This is used for cases where the credential is separate from the context the Adapter Endpoint runs under. This method is necessary for cases where the Neuron ESB Services runs on a machine that is not a member of the domain that hosts the AD Server the AD Endpoint connects to for its operations.
Windows Credential
This is a conditional property that only applies when the Domain Membership Property = NonMember. To use this property, a Windows Domain Credential has to be created in the Solutions Security Section within the Neuron ESB Explorer. That credential will then appear in this property’s dropdown list.
Publish Mode Properties
These properties control how Active Directory change notification events are registered, received and published by the AD Adapter Endpoint. For these properties to be effective, the Mode property located on the General tab of the Adapter Endpoint must be set to Publish.
Publish Topic
This property is used to specify the Neuron ESB Topic to use when publishing the received AD event to the bus.
Search Path
This property specifies the search path to use to monitor a specified AD Server. For example, one wanted an event message for any user activity on the Neuron.local server, the following property combinations would be set:
- Search Scope: SubTree
- Search Path: DC=Neuron;DC=local;CN=Users
LDAP Path Syntax
The Search Path Property conforms to standard LDAP Path Syntax. The AD Adapter uses the standard Windows Active Directory Dialog, illustrated in Figure 2. You can also specify this property directly if you are familiar with LDAP syntax. A good resource to learn more about LDAP Path Syntax can be found here: https://social.technet.microsoft.com/wiki/contents/articles/1773.ldap-path-active-directory-distinguished-and-relative-distinguished-names.aspx .
In some cases, you may have to override portions of the AD Path that results from the picker. This is why it is important to understand the LDAP Path Syntax. This issue will be discussed in greater detail when specific use case examples are illustrated in this document.
Event Type
The Event Type property determines what AD changes the Adapter Endpoint will request to be notified by the AD Server for. This property has the following values:
- All (Default): Every event for the Search Path/Search Scope specified will be returned.
- Created: Only events that are triggered when creating a new entity are returned.
- Deleted: Only events that are triggered when deleting an existing entity are returned.
- Disabled: Only events that are triggered when disabling an existing entity are returned.
- LockedOut: Only events that are triggered when an entity is locked-out are returned. This applies to user entities that have too many failed login attempts as specified by the domains password policy.
- PasswordExpired: Only events that are triggered when a users password expired are returned.
Attributes Excluded
This property can be one of two values:
- None (Default)
- MicrosoftExchange: All data elements appended to the AD object data by MS Exchange are removed from the event data received by the Neuron ESB Adapter endpoint before being serialized and published to the bus.
Error Reporting
This property determines how all errors are reported in Event Log and Neuron Logs. Either as Errors, Warnings or Informational. This property can be one of three values:
- Error (Default)
- Information
- Warning
Error On Publish
This property determines if monitoring of the AD Server continues on error and if consecutive errors are reported. The property is used to determine consecutive reporting and whether or not it should shut down on if an exception occurs in the event handler. This property can be one of three values:
- StopPollingOnError (Default): Stops the Adapter when an error is encountered.
- SuppressConsecutiveErrors: The Adapter will only report the first error and will continue to run.
- ReportAllErrors: The Adapter will only report all errors and will continue to run.
Message Formats
Besides receiving events from AD when the Adapter Endpoint is configured for Publish Mode, the AD Adapter can be used to query or perform standard CRUD operations on any AD object when configured for Query Mode. In Query Mode, a request message must be published and received by an AD Adapter Endpoint in order for the AD Adapter Endpoint to work properly and return a reply message. The request and reply type messages can be either in XML or JSON, but regardless of format each type of message has the same structure.
Query Mode
Request Message
Every request message has a root named ActiveDirectory. Within this there is a Request node which contains all the relevant elements of the message that represent the properties that will be used to direct the operation of the AD Adapter Endpoint at runtime. The following is an example of a Request message in XML that returns the object for a specific user represented in the LdapPath node:
<ActiveDirectory> <Request> <LdapPath>CN=Marty,OU=Management,DC=corp,DC=neudesic,DC=net</LdapPath> <Class></Class> <Name></Name> <TransactionType>Get</TransactionType> <NewPassword></NewPassword> <Filter></Filter> <Properties></Properties> <MaxObjectsToReturn></MaxObjectsToReturn> </Request> </ActiveDirectory>
The next example is of a Request message in JSON that queries the Management OU for all users whose given name property starts with M:
{ "ActiveDirectory": { "Request": { "LdapPath": "OU=Management,OU=Divisions,OU=Neudesic,DC=corp,DC=neudesic,DC=net", "TransactionType": "Get", "Filter": "(&(objectClass=user)(givenname=M*))", "MaxObjectsToReturn": "" } } }
All Request messages must have the Neuron ESB Message Semantics property set to Request
Message Elements (Properties)
- LdapPath (Required): The LdapPath node is a standard ldap search path. For example, to create a new user on the Neuron.local domain, the following search path would be used:
- CN=Users,DC=Neuron,DC=local
- If on the other hand, a specific user entry (i.e. John Doe) is to be modified, the following is an example of a search path that would be used:
- CN=John Doe,CN=Users,DC=Neuron,DC=local
- Class (Optional): If the operation is to add a new entity, then the class must be specified. Supported classes are User and Group.
- Name (Optional): If the operation is to add a new entity, then the name must be specified. The name serves as the unique key under the specified directory tree (specified in the LdapPath).
- TransactionType (Required): This property specifies the type of transaction embodied in the message. The following transaction type values are supported:
- Get: Queries the AD server to return any objects matching the search clause provided in the Filter property.
- Add: Creates a new entity. Note: When the Transaction Type == Add, the Class and Entry nodes must be specified. If the entity already exists, an exception will be thrown and logged. Also, any relevant properties must be added to the Properties node
- Edit: Updates an existing entity. Note: when the Transaction Type == Edit, Only the LdapPath and any relevant properties within the Property node needs to be specified. If the entity does not exist, an exception will be thrown and logged.
- Delete: Deletes an existing entity. Note: Only the LdapPath needs to be specified.
- Enable: Enables an existing entity. Note: Only the LdapPath needs to be specified.
- Disable: Disables an existing entity. Note: Only the LdapPath needs to be specified.
- PasswordReset: Resets a password for an existing User Entity. Note: the NewPassword Node must be specified.
- NewPassword: Used in conjunction with the PasswordReset Transaction Type. The new password must comply with the domains password policy.
- Properties: Contains entries for each attribute that is used to define a new entity or update an existing entity.
- Filter: represents the active directory search clause to use for GET Transaction Types. More information regarding syntax can be found here: https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx .
- MaxObjectsToReturn: This determines the number of records to return if the TransactionType is set to GET. If the TransactionType is set to DELETE or ENABLE, it limits the number of records that will be affected by the operation. Default is 1000.
Response Message
NON GET Transaction Type
The AD Adapter generates two type of Response messages, one that contains AD object entity information, the other, a simple acknowledgement of success. For all NON GET Transaction Type messages, a Response element, within an ActiveDirectory root, with the value of OK is always returned either in JSON or XML. The format that is returned is dependent on the format of the original Request message received (e.g. JSON or XML). Either the XML format:
<ActiveDirectory> <Response>OK</Response> </ActiveDirectory>
Or the JSON format:
{"ActiveDirectory":{"Response":"OK"}}
GET Transaction Type
For all GET Transaction Type messages, either an empty Response message can be returned if there was no data in AD matching the Filter Search Clause or one containing all the entities and their respective AD properties. The empty Response message can be in either in XML format:
<ActiveDirectory> <Response></Response> </ActiveDirectory>
Or the JSON format:
{"ActiveDirectory":{"Response":""}}
A Response message that returns AD object information would have an ActiveDirectory root enclosing a Response element. Within that Response element would be one or more Entry elements, each one representing AD object that matched the Filter Search Clause as shown below. The Response will be in either JSON or XML format, depending on the format of the original Request message. In XML format:
<ActiveDirectory> <Response> <Entry> <givenname>ASDF</givenname> <codepage>0</codepage> <objectcategory> CN=Person,CN=Schema,CN=Configuration,DC=AD,DC=Server,DC=com </objectcategory> <usnchanged>32875</usnchanged> <instancetype>4</instancetype> <logoncount>0</logoncount> <name>ASDF</name> <badpasswordtime>0</badpasswordtime> <pwdlastset>0</pwdlastset> <objectclass_Attributes> <objectclass>top</objectclass> <objectclass>person</objectclass> <objectclass>organizationalPerson</objectclass> <objectclass>user</objectclass> </objectclass_Attributes> <badpwdcount>0</badpwdcount> <samaccounttype>805306368</samaccounttype> <usncreated>32874</usncreated> <sn>ASDF</sn> <objectguid>5f8815c1-5c32-4887-966c-89887beecf54</objectguid> <whencreated>5/10/2016 5:48:41 PM</whencreated> <adspath> LDAP://AD.Server.com/CN=ASDF,DC=AD,DC=Server,DC=com </adspath> <useraccountcontrol>546</useraccountcontrol> <cn>ASDF</cn> <countrycode>0</countrycode> <primarygroupid>513</primarygroupid> <whenchanged>5/10/2016 5:48:41 PM</whenchanged> <lastlogon>0</lastlogon> <distinguishedname> CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com </distinguishedname> <samaccountname>ASDF</samaccountname> <objectsid> S-1-5-21-2838431563-507545762-4290413218-1160 </objectsid> <lastlogoff>0</lastlogoff> <accountexpires>Never Expires</accountexpires> <userprincipalname>ASDF@AD.Server.com</userprincipalname> </Entry> </Response> </ActiveDirectory>
Or in JSON format:
{ "ActiveDirectory": { "Response": { "Entry": { "givenname": "qwer", "codepage": "0", "objectcategory": "CN=Person,CN=Schema,CN=Configuration,DC=AD,DC=Server,DC=com", "usnchanged": "32885", "instancetype": "4", "logoncount": "0", "name": "ASDF", "badpasswordtime": "0", "pwdlastset": "5/10/2016 10:59:27 AM", "objectclass_Attributes": { "objectclass": [ "top", "person", "organizationalPerson", "user" ] }, "badpwdcount": "0", "samaccounttype": "805306368", "usncreated": "32874", "sn": "ASDF", "objectguid": "5f8815c1-5c32-4887-966c-89887beecf54", "whencreated": "5/10/2016 5:48:41 PM", "adspath": "LDAP://AD.Server.com/CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com", "useraccountcontrol": "546", "cn": "ASDF", "countrycode": "0", "primarygroupid": "513", "whenchanged": "5/10/2016 5:59:27 PM", "lockouttime": "0", "lastlogon": "0", "distinguishedname": "CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com", "samaccountname": "ASDF", "objectsid": "S-1-5-21-2838431563-507545762-4290413218-1160", "lastlogoff": "0", "accountexpires": "Never Expires", "userprincipalname": "ASDF@AD.Server.com" } } } }
Publish Mode
When the Neuron AD Adapter is configured for Publish mode, it will use the values configured in its respective property grid to create an event registration against the AD server. When an event is received, the event information is serialized into an XML format. This format is identified by an ActiveDirectory root enclosing a single EventData node representing the AD object that was sent by the AD server. The EventData node will contain all the attributes of the AD object. The following provides an example of a fragment of information received:
<ActiveDirectory> <EventData> <accountExpires>Never Expires</accountExpires> <callbacknumber>3108544519</callbacknumber> <lastLogoff>0</lastLogoff> <msExchBypassModerationBL_Attributes></msExchBypassModerationBL_Attributes> <msRTCSIP-InternetAccessEnabled>TRUE</msRTCSIP-InternetAccessEnabled> <msNPAllowDialin>TRUE</msNPAllowDialin> <extensionAttribute6>1</extensionAttribute6> <extensionAttribute7>;3;</extensionAttribute7> <extensionAttribute5>0</extensionAttribute5> <msExchCoManagedObjectsBL_Attributes></msExchCoManagedObjectsBL_Attributes> <givenName>Steve</givenName> <sAMAccountName>steve.austin</sAMAccountName> <deliverAndRedirect>TRUE</deliverAndRedirect> <msRTCSIP-LineServer>sip:+13109544519@ccm2.corp.neuronesb.net</msRTCSIP-LineServer> <ciscoEcsbuAlternateDtmfIds>19</ciscoEcsbuAlternateDtmfIds> <whenCreated>3/26/2003 6:10:14 PM</whenCreated>
Message Serialization
All message generated by the AD Adapter are created using a custom serializer. The serializer converts all date time and zulu time based attributes such as lastlogon, badpasswordtime, lastlogontimestamp, pwdlastset and accountexpires attributes to human readable local time formats. It also converts all SID based attributes to human readable fields as well.
Use Cases
What follows are some of the typical use cases and associated example messages that can be addressed with the AD Adapter
Query Mode
Retrieve a specific user:
In XML format:
<ActiveDirectory> <Request> <LdapPath>CN=Marty Wasznicky, CN=Users,DC=AD,DC=Server,DC=com </LdapPath> <MaxObjectsToReturn>1</MaxObjectsToReturn> <TransactionType>get</TransactionType> </Request> </ActiveDirectory>
In JSON format:
{ "ActiveDirectory": { "Request": { "LdapPath": " CN=Marty Wasznicky, CN=Users,DC=AD,DC=Server,DC=com", "TransactionType": "Get", "MaxObjectsToReturn": "1" } } }
Retrieving a list of the users where the given name begins with M:
In XML format:
<ActiveDirectory> <Request> <LdapPath> CN=Users,DC=AD,DC=Server,DC=com </LdapPath> <Class></Class> <Name></Name> <TransactionType>Get</TransactionType> <Filter>(%26(objectClass=user)(givenname=M*))</Filter> <MaxObjectsToReturn></MaxObjectsToReturn> </Request> </ActiveDirectory>
In JSON format:
{ "ActiveDirectory": { "Request": { "LdapPath": "CN=Users,DC=AD,DC=Server,DC=com", "TransactionType": "Get", "Filter": "(&(objectClass=user)(givenname=M*))", "MaxObjectsToReturn": "2000" } } }
Setting a new password for a user:
In XML format:
<ActiveDirectory> <LdapPath> CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com </LdapPath> <TransactionType> passwordreset </TransactionType> <NewPassword> pass@word2 </ NewPassword > </ActiveDirectory>
In JSON format:
{ "ActiveDirectory": { "Request": { "LdapPath": "CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com", "TransactionType": "passwordreset", "NewPassword":"pass@word2" } } }
Creating a new AD User under the Users Group:
In XML format:
<ActiveDirectory> <Request> <LdapPath>CN=Users,DC=AD,DC=Server,DC=com</LdapPath> <TransactionType>add</TransactionType> <Class>User</Class> <Name>CN=ASDF</Name> <Properties> <sAMAccountName>ASDF</sAMAccountName> <userPrincipalName>ASDF@AD.Server.com</userPrincipalName> <sn>ASDF</sn> <givenName>ASDF</givenName> </Properties> </Request> </ActiveDirectory>
In JSON format:
{ "ActiveDirectory": { "Request": { "LdapPath": "CN=Users,DC=AD,DC=Server,DC=com", "TransactionType": "add", "Class": "user", "Name": "CN=ASDF", "Properties": { "sAMAccountName": "ASDF", "userPrincipalName": "ASDF@AD.Server.com", "sn": "ASDF", "givenName": "ASDF" } } } }
Disabling an AD Entity:
In XML format:
<ActiveDirectory> <LdapPath> CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com </LdapPath> <TransactionType> Disable </TransactionType> </ActiveDirectory>
In JSON format:
{ "ActiveDirectory": { "Request": { "LdapPath": "CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com", "TransactionType": "disable", } } }
To enable an entity, simply use the Enable Transaction Type.
Setting the Description for an AD Entity:
In XML format:
<ActiveDirectory> <Request> <LdapPath>CN=ASDF,CN=Users,DC=AD,DC=Server,DC=com</LdapPath> <TransactionType>edit</TransactionType> <Properties> <sAMAccountName>ASDF</sAMAccountName> <userPrincipalName>ASDF@AD.Server.com</userPrincipalName> <sn>ASDF</sn> <givenName>qwer</givenName> <description>who is this guy?</description> </Properties> </Request> </ActiveDirectory>
In JSON format:
{ "ActiveDirectory": { "Request": { "LdapPath": "CN=Users,DC=AD,DC=Server,DC=com", "TransactionType": "edit", "Class": "user", "Name": "CN=ASDF", "Properties": { "sAMAccountName": "ASDF", "userPrincipalName": "ASDF@AD.Server.com", "sn": "ASDF", "givenName": "ASDF", "description": "Whos that guy?" } } } }
In the Properties node, simply specify the attribute and the value you wish to set. In the event you list an attribute that does not exist, the adapter will throw and log an exception.
MetaData
The following illustrates an example of metadata returned when the Include MetaData option for the adapter endpoint is checked:
Exceptions
The following illustrates an example of an exception being thrown when an improperly formatted message is sent in Query Mode: