Neuron ESB Active Directory Connector

Introduction

Neuron ESB’s 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 organization’s 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 our online help: https://www.peregrineconnect.com/documentation-kb/adapter-overview/. This document assumes you have the following knowledge:

1. What adapters are and how they are leveraged in Neuron ESB
2. Register a Neuron ESB Adapter within a Neuron ESB Solution
3. Create an Adapter Endpoint in a Neuron ESB Solution
4. Set a Neuron ESB Adapter Endpoint Properties
5. 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

Figure 1: Active Directory Adapter Endpoint Property Grid

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 Solution’s 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: http://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 domain’s password policy.
• PasswordExpired: Only events that are triggered when a user’s 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 domain’s 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": "Who’s 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:

Figure 3: Test Client illustrating a published message and meta data

Exceptions

The following illustrates an example of an exception being thrown when an improperly formatted message is sent in Query Mode:

Figure 4: Invalid Request Message Format Exception – Query Mode