Import users and groups from Active Directory

The main functionality of the AD import in iGrafx Origins is the correct setting and filtering of attributes. These attributes compose the hierarchy of the AD and are arranged differently in every AD.

It is not common that you have more than one LDAP directory in the iGrafx Directories list. This should be an exceptional case and should be treated with extra caution.

About user directories

The documentation usually refers to Active Directory as a synonym for any LDAP directory service, however the exact attributes may differ for other services.  

The iGrafx platform can import users and groups from an Active Directory to allow the administrator to assign users or groups to security roles on different levels controlling user access privileges, see Assigning Security Roles. The imported groups and users are used to assign permissions to them as well as allowing the application to resolve user and group permissions in a timely manner, without producing recurring load on the domain controller for each user operation. The directory connection is also used to authenticate the individual users against the Active Directory using their credentials or Single Sign On mechanisms like Kerberos or SAML2 (ADF, Okta).

When you configure an Active Directory connection the users and groups are imported in a one time operation, or automatically on a defined interval. A one time or manual import will require you to come back to the directory configuration and update the Active Directory if required, but it will present you with a list of changes made.

Important attributes

Here is a quick overview of the most important attributes. 

Attribute	Meaning
sAMAccountName	A must attribute for user objects that has to be set when a user is created in the AD. It is used as the login name of the user, e.g. katharinah.
user	The user attribute itself. Meant to illustrate that someone is a user in the AD.
cn	Common name. Used as the name displayed in the AD, e.g. Hecht, Katharina.
sn	Surname. Not used by the AD itself but generated in order to be able to display the surname of a person.
group	The group attribute itself. Meant to illustrate that this is a group defined in the AD.
mail	The attribute displaying the Email direction of a user.
ou	Organizational Unit. Used to display the hierarchy of the Active Directory.
dc	Domain Component. Means part of the DNS name, e.g. igrafx.local (DC=igrafx,DC=local).
givenName	Given name of a person. Not used by the AD itself but generated in order to be able to display the surname of a person. E.g. Katharina Hecht.
memberOf	Meant to display that a user is a member of a group.

Here is also a quite helpful article on the attributes and queries in LDAP (German only).

How to configure the directory settings

The following gives an example on how to import users from the Active Directory to Origins. One pre-assumption is that - as it is most convenient - users are primarily classified into AD groups and we only want to import users that are explicitly in these groups and the groups themselves.There also is a so-called attribute generator in the Active Directory that provides you with the attributes and the correct order of these. You can find that by clicking on a user or a group in the AD. Then you can copy the statements out of this generator into your filter.

See below for exemplary filter settings.

Directory

 First of all, the import filter asks for the name of the directory (you can provide any name you like) as well as for the LDAP server name and port. It could look like that:

Service User

Afterwards the structure of the service user is requested. This could for example look like that: CN=service colo,OU=Service User,OU=Colo Users,DC=ad,DC=igrafxdemo,DC=com

This statement means we are searching for the user with the common name service colo that is located in the AD below the Organizational Units Service User, Colo Users and below the Domain Components ad.igrafxdemo.com. So we are searching from bottom to top in the hierarchy of the AD. 

Always be sure that this is the exact place where you are searching for and if something changes, then you have to adapt the filter as well

Afterwards provide the password for the service user. The password is encrypted and stored in the iGrafx platform.

Search base

The next is the search base, i.e. the place in the hierarchy where you are locating the search. In our example this could simply be DC=ad,DC=igrafxdemo,DC=com

but also you can define the search a little more and add that you are only searching below an organizational unit in order to have a search base like OU=Colo Users,DC=ad,DC=igrafxdemo,DC=com 

Always be aware that the service user needs to have a view permission on items that are located in this path of the AD. Otherwise the filter will not provide you with any results.

User search filter

A user search filter in order to search for users that are all member of a certain group could then be defined the following:

(&(objectCategory=Person)(sAMAccountName=*)(|(memberOf=CN=Training Preview Users,OU=Training,OU=External,OU=Colo Users,DC=ad,DC=igrafxdemo,DC=com)(memberOf=CN=iGrafx Preview Administrators,OU=External,OU=Colo Users,DC=ad,DC=igrafxdemo,DC=com)))

So that means we are searching for persons with any name (*) that are member of a group. And here for the group you have to provide the same structure as above, so what is the common name of the group and where it is located. The '&' at the beginning indicates we are linking more items that all have to be true at the same time whereas the "Pipe" symbol ('|') is needed as logical 'or'.

Be careful not to use line feed/carriage return characters. Make sure there is no hidden line break at the end of a text field like 'User Search Filter'.

It will display an unrelated error message like: "Missing 'equals'; nested exception is javax.naming.directory.InvalidSearchFilterException: Missing 'equals'; remaining name 'ou=xxx users,dc=yyy, dc=zzz' "

Remaining settings

The remaining settings are also predefined and can be kept like

How do I build LDAP queries?

If you have specific issues search the internet. But if you look for basics the following resources might be a good starting point to learn how to write a LDAP query: 

https://technet.microsoft.com/en-us/library/aa996205(v=exchg.65).aspx

http://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx

Multiple directories

It is not common that you have more than one LDAP directory in the iGrafx Directories list. This should be an exceptional case and should be treated with extra caution.

What should you consider if you actually have two or more LDAP hosts or another special requirement?

When you setup a connection to more than one directory in iGrafx you should give every directory a prefix to separate their namespaces. If you started with one directory and have to add an additional directory later the users from the first directory most likely have to use a prefix and the ones of the additional directories will have a prefix requirement.

A user in two directories is not the same user, like it is not a separate user in two Active Directory domains. If you connect more than one directory and the user LDAP query want to import a username which already exist in another directory the import of the second user will fail unless the directory has a prefix. If you import the same user multiple times into iGrafx LDAP directories with different prefixes they will be treated as different users with regards to license and permission management.

Please see the following table for an example, login is the test the user has to enter into the credentials as username to authenticate with his password. If the environment is setup for any kind of Single Sign On you need to make sure that the login is matching the format expected by your authentication provider.