Reference7:Configure Active Directory Replication
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-attributes into arbitrary innovaphone-attributes.
Configuration
The configuration can be divided into the two tasks AD Settings and 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 for common server settings as IP address, DN, User, Password, LDAP Filter.
Replicating in a Domain Forest
A company foo.bar maintains three domain controllers (DC).
- A root DC for the naming context dc=foo, dc=bar
- A sub DC for the naming context dc=sales, dc=foo, dc=bar
- A sub DC for the naming context dc=support, dc=foo, dc=bar
The task may now be to replicate all users within dc=foo, dc=bar recursing down into all sub-domains.
By default this isn't possible, because MS designed a DC to only answer LDAP search requests with search results it is authoritative for.
The role of a global catalog (GC) is supposed to overcome this limitation. A DC acts as a GC if contacted on TCP port 3862.
Therefore..if it's desired to replicate from a forest of DCs
- Enter as LDAP/Replicator/Server the destination as [IP Address]:[port]
- IP Address shall be the IP address of the root DC
- port must be 3268
Attribute Mapping
There are a list of In-Maps and a list of Out-Maps. That's it. In-Maps allow for regular expressions[1]. 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:
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 ::= [.*]
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:
destination_values ::= <destination_values> <destination_value> | <destination_value> destination_value ::= <identifier> | '\'' <ALLCHARS> '\'' # Literal | <ALLCHARS> # Const, synonymous to Literal
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=*))
Peter's telephoneNumber: +49(7031)12345-75 John's telephoneNumber: +49(7031)12345-74 Mary's telephoneNumber: +49(7031)12345-43
Map configuration underneath Configuration/LDAP/Replicator:
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
This is how the output is written into the flash:
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)
Note: According to the 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.
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 ...
yielding:
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)
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[2] 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[3] 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:
ldifde -s 127.0.0.1 -r "(sn=doe)" -f out.txt
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:
ldifde -s 127.0.0.1 -r "(objectclass=user)" -f out.txt
Deleting AD-Replicated Objects
You may delete up to 100 objects in one instance.
- Proceed to 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
- 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[4] 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 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
- ↑ Regular Expression, http://en.wikipedia.org/wiki/Regular_expression
- ↑ 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
- ↑ RFC2849, LDAP Data Interchange Format
- ↑ userAccountControl, http://support.microsoft.com/?scid=kb%3Ben-us%3B305144