innovaphone wiki - User contributions [en]

Reference7:Configure Active Directory Replication

2010-01-07T21:48:47Z

Jens.hitzigrath:

==Applies To==
This information applies to

*innovaphone PBX V7
*Microsoft Windows Server Platforms

Tested with MS Windows 2000 Server and MS Windows 2003 Server.

==More Information==
Active Directory (AD) replication allows to import Windows Users into an innovaphone PBX as user objects. It is a read-only replication. Nothing is going to be written into the AD.

An attribute mapping mechanism allows to map arbitrary AD-http://wiki.innovaphone.com/index.php?title=Reference7:Configure_Active_Directory_Replication&action=editattributes into arbitrary innovaphone-attributes.

==Configuration==
The configuration can be divided into the two tasks [[#AD Settings|AD Settings]] and [[#Attribute Mapping|Attribute Mapping]]. This article focusses on Attribute Mapping.

*Maps for incoming attributes must be configured. An In-Map controls which content of which incoming attribute goes into a runtime symbol table.
*Maps for outgoing or local attributes must be configured. An out-map controls which runtime symbol table entry fills a local attribute.

==AD Settings==
Please see [[Reference7:Configuration/LDAP/Replicator|Reference7:Configuration/LDAP/Replicator]] for common server settings as IP address, DN, User, Password, LDAP Filter.

==Attribute Mapping==
There are a list of [[#Grammar For In-Maps|In-Maps]] and a list of [[#Grammar For Out-Maps|Out-Maps]]. That's it.
In-Maps allow for regular expressions<ref>Regular Expression, http://en.wikipedia.org/wiki/Regular_expression</ref>. Out-Maps merely consist of symbol names or literals (constants).

*On reception of of a source-ldap object, all existing attributes will be investigated and a corresponding in-map is being looked-up for each attribute.
*If there are many in-maps per attribute, all maps will be exececuted sequentially and the value assignment will be placed (if the pattern matches).
*In case of a matching map, then values will be maintained within a symbol table (see grammar: 'identifier' production)
*Values within the symbol table will be overwritten (if already existing).
*After completion, the target-ldap-obbject will be generated by means of the Out-Maps. If a value application without a value in the symbol table will be found(i.e. no In-Map matched and wrote something into the symbol), then the source-ldap-object is to be discarded.

===Grammar For In-Maps===
An in-map is a pair of <source-attr-name> (An AD-attribute name) and <assignment_pattern>.
Approximate Grammar:

<pre>
assignment_pattern ::= <symboldefinitions> ':' <regexp>
| <symboldefinitions>

symboldefinitions ::= <symboldefinitions> <symboldefinition>
| <symboldefinition>

symboldefinition ::= <identifier> '=' <value_expression>
| <identifier>

value_expression ::= '/' <VALUES> '/'

VALUES ::= <VALUES> <VALUE>
| <VALUE>

VALUE ::= '\' <NUM> # Back Reference
| '\'' <ALLCHARS> '\'' # Literal
| <ALLCHARS> # Const, synonymous to Literal

identifer ::= '%' <ALNUM>

regexp ::= <ALLCHARS>

ALNUMS ::= ALNUMS ALNUM
| ALNUM

ALNUM ::= ['a'-'z'|'A'-'Z'|'0-'9']

ALLCHARS ::= [.*]
</pre>

====In-Map Examples, Maps for ''telephoneNumber''====

* %dw=/\1/:07031 12345-(.*)
that assigns the extension to the symbol %dw

* %dw=/\2/%root=/\1/:07031(.*) -(.*)
this assigns the extension to the symbol %dw and the root-/subscriber number to %root.

* If the <value_expression> was skipped, it defaults to \n, wher n is the running index of the symbol_definition (starting with 1). The second example from above can therefore be written as: %root%dw:07031(.*) -(.*)

* A default value for a symbol may be defined by simply applying an an always-match-constant-value. That is, for instance for telephoneNumber
%dw=/0/:.*

* Because of the rule, that a missing regexp defaults to ''':(.*)''' , this can be written as
%dw=/0/

* If an attribute value is to copied straight, one simply writes
%e164

* which is identical with
%e164=/\1/:(.*)

===Grammar For Out-Maps===
An out-map is a pair of <destination-attr-name> (name of an innovaphone attribute) and <destination_values>.
Approximate Grammar:
<pre>
destination_values ::= <destination_values> <destination_value>
| <destination_value>

destination_value ::= <identifier>
| '\'' <ALLCHARS> '\'' # Literal
| <ALLCHARS> # Const, synonymous to Literal
</pre>
This grammar allows to fill the e.g. local cn-attribute not only with a single identifier, but with an intermixed concatenation of several identifiers and literals alike e.g.: ''"%sn', '%givenName"'' - yielding for instance: ''"Doe, Jon"''.

===Example===
The following example focusses on the generation of the e164-, node- and loc-attribute.
*Only Sindelfingen-Numbers (+49(7031)...) will match
*The numbering node (a.k.a. node-attribute) will then be set to ''root''.
*The hosting PBX (a.k.a. loc-attribute) will be set to ''sifi''.

Within the AD exists..:
''Btw, the Filter was configured to: (&(objectclass=user)(telephoneNumber=*))''
<pre>
Peter's telephoneNumber: +49(7031)12345-75
John's telephoneNumber: +49(7031)12345-74
Mary's telephoneNumber: +49(7031)12345-43
</pre>

Map configuration underneath Configuration/LDAP/Replicator:
<pre>
In Maps
Source Attribute Assignment Pattern Description
-------------- ------------------ -----------
cn %cn
telephoneNumber %tel%loc=/sifi/%node=/root/:\+49.*7031.*12345-(.*) Sindelfingen numbers with leading '+' at begin: then backref=1 into %tel. Constant=sifi into %loc. Constant=root into %node.
displayName %dn

Out Maps
Dest.-Attribute Destination Value
-------------- ----------------
cn %cn
e164 %tel
loc %loc
node %node
dn %dn
</pre>

This is how the output is written into the flash:
<pre>
mod cmd FLASHDIR0 add-item 102 (cn=Peter Schmidt)(repsrc=ad)(guid;bin=2B1DAA4655AE244D845734951F5F2F1B)(node=root)(loc=sifi)(dn=Peter Schmidt)(e164=74)(usn=3675)
mod cmd FLASHDIR0 add-item 102 (cn=John Doe)(repsrc=ad)(guid;bin=904AF5506116354E9E86BE9A6C5D67FF)(node=root)(loc=sifi)(dn=John Doe)(e164=75)(usn=3676)
mod cmd FLASHDIR0 add-item 102 (cn=Mary Fernandez)(repsrc=ad)(guid;bin=575743792731EE478EFB40754885BAAB)(node=root)(loc=sifi)(dn=Mary Fernandez)(e164=43)(usn=3678)
</pre>

'''Note''': According to the [[#Grammar For Out-Maps|Out-Maps Grammar]] a local attribute can be synthesized from multiple symbols and literals. Here comes an example for the aggregated synthesis of the local '''CN''' attribute.
<pre>
In Map
Source Attribute Assignment Pattern Description
-------------- ------------------ -----------
...
sn %sn Surname (e.g. Fernandez) into %sn
givenName %gn Name (e.g. Mary) into %gn
...

Out Map
Dest.-Attribute Destination Value
-------------- ----------------
...
cn %sn', '%gn
...
</pre>
yielding:
<pre>
mod cmd FLASHDIR0 add-item 102 (cn=Fernandez, Mary)(repsrc=ad)(guid;bin=575743792731EE478EFB40754885BAAB)(node=root)(loc=sifi)(dn=Mary Fernandez)(e164=43)(usn=3678)
</pre>
===AD Attributes Of Interest===
The following list names the attributes to be configured as ''Source Attribute'' within an In-Map or to be referenced within the LDAP filter:
*cn: The Common Name
**single-valued
**possible usage: for ''cn'' attribute

*sn: The Surname
**single-valued
**possible usage: for DECT display name ''dn'' attribute

*givenName: The Given Name.
**single-valued
**possible usage: for DECT display name ''dn'' attribute

*telephoneNumber: The primary business telephone number. To be found on a user's ''General'' tab.
**single-valued
**mostly in international form with leading plus sign (e.g. +49(7031)12345-44)
**possible usage: for ''e164'' attribute

*memberOf: Group memberships. Groups are named here by their Distinguished Name (DN).
**multi-valued
**possible usage: for ''root'' attribute
**'''Note''':Though there might be desires - PBX groups must still be configured manually. PBX groups cannot be configured through AD Replication.

*samAccountName: The logon name
**single-valued
**possible usage: for ''h323'' attribute

==Tips&Tricks==

===Investigating/Dumping An AD Object===
If you want to learn or study about how the AD stores user objects and which attributes are available per user, the tool '''ldifde.exe'''<ref>Using LDIFDE, http://support.microsoft.com/kb/237677 or LDIFDE, http://technet2.microsoft.com/WindowsServer/en/Library/32872283-3722-4d9b-925a-82c516a1ca141033.mspx?mfr=true</ref> will be of help.
Ldifde.exe is a Microsoft command line program which is part of a Windows Server installation. It allows to dump the complete AD content or parts of it into LDIF<ref>RFC2849, LDAP Data Interchange Format</ref> files.

To Dump the AD object for a Windows user ''John Doe'' into a file ''out.txt''
*On a Windows Server open up a command line box.
*Enter:
<pre>
ldifde -s 127.0.0.1 -r "(sn=doe)" -f out.txt
</pre>
Btw, from the file you can also learn which Distinguished Names (DNs) are available. A DN may be required as user name within the common server settings on the LDAP/Replicator page.

To Dump all AD user objects into a file ''out.txt''
*On a Windows Server open up a command line box.
*Enter:
<pre>
ldifde -s 127.0.0.1 -r "(objectclass=user)" -f out.txt
</pre>

===Deleting AD-Replicated Objects===
You may delete up to 100 objects in one instance.
*Proceed to [[Reference7:Configuration/LDAP/Expert|Reference7:Configuration/LDAP/Expert]]
*Enter the LDAP filter ''(repsrc=*)'' into the search edit field an click on '''Show'''
*Check the column selector to select all displayed objects
*Click '''Delete''' within the toolbar. A confirmation dialog will be shown.
*Confirm

===Display Non-AD-Replicated Objects===
*Proceed to [[Reference7:Configuration/LDAP/Expert|Reference7:Configuration/LDAP/Expert]]
*Enter the LDAP filter ''(!(repsrc=*))'' into the search edit field an click on '''Show'''

===Out-Filtering Disabled Windows Accounts===
Windows maintains the numerical attribute ''userAccountControl''<ref>userAccountControl, http://support.microsoft.com/?scid=kb%3Ben-us%3B305144</ref> for each user object within the AD.
If Bit 2 is set, the user account was disabled.

A NOT-Filter term, featuring a matching-rule, ensures that this bit isn't set, i.e. that it is not a disabled account:
*''(!(userAccountControl:1.2.840.113556.1.4.803:=2))''

A complete AND-filter may therefore look like this one:
*''(&(objectclass=user)(telephoneNumber=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))''

===Filtering For Group Memberships===
The multi-value AD attribute ''memberOf'' carries the information which groups a user is belonging to. Groups are named within the AD by their Distinguished Name (DN), instead of by their friendly name.
This is how the AD could be storing a group membership ''Berlin'':
*memberOf: ''CN=Berlin,CN=Users,DC=innovaphone,DC=sifi''

If you wanted to filter for members of the group ''Berlin'', the following AND-filter would do the job:
*''(&(objectclass=user)(memberOf=CN=Berlin,CN=Users,DC=innovaphone,DC=sifi))''

'''Note:''' The filter must be crafted for an equality match. According to MSDN ''memberOf'' does not allow for substring/wildcard matches.

==Known Problems==
===Freshly Deleted AD-Objects Aren't Deleted Locally===
Although the replicator receives change notify results from the AD, the AD might not send notifications about the deletion of objects.
The replicator will be deleting affected objects only after a stop+start of the replication session.

Lab experiments showed that the AD sent such deletion notifications only, if the replicator had authenticated with administrator credentials - which practically isn't recommendable.

To recover from this peculiarity the following procedure should be implemented:
*Please obey paragraph [[#Out-Filtering Disabled Windows Accounts|Out-Filtering Disabled Windows Accounts]] under the Tips&Tricks section.
*Don't delete AD objects as the first step of the administration procedure for user objects scheduled for deletion.
*Instead: Disable such objects as the first step.

==Notes==
<references/>



[[Category:Howto|{{PAGENAME}}]]

Reference7:Configure Active Directory Replication

2010-01-07T21:47:54Z

Jens.hitzigrath: