Reference7:Configure Active Directory Replication
Applies To
This information applies to
- This information applies to V7.
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.
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
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