Systems - AD: Manage users

This tutorial will show you how to connect AD as a target system for users (their accounts) from CzechIdM. We will use an AD bundle connector from Connid.

First of all, you need to download the connector from Connid (e.g. Connid AD bundle 1.3.4 jar file). Then add the jar file into CzechIdM folder inside the application server. In case you installed CzechIdM into tomcat by standard installation, the path would be /opt/tomcat/current/webapps/idm/WEB-INF/lib/.

To preserve the connector during future upgrades of CzechIdM core, put the connector in e.g. /opt/czechidm/lib/ and create symbolic link in the CzechIdM webapp folder:
ln -s /opt/czechidm/lib/net.tirasa.connid.bundles.ad-1.3.4.jar /opt/tomcat/current/webapps/idm/WEB-INF/lib/net.tirasa.connid.bundles.ad-1.3.4.jar

Then restart the application server. If you had CzechIdM already running in the web browser, refresh also the web browser window (e.g. Ctrl+F5).

Go to Systems from main menu, then above list of current systems use Add button. On the first page just fill system name.

On the same page you may need to set new password policy in case that your default policy does not meet all requirements of AD configuration. If you do not want to generate passwords for AD accounts, you can skip this step at all.

In next step switch to menu Configuration of your new system. At first, you need to chose connector, which in this case is net.tirasa.connid.bundles.ad.ADConnector(connId). It will open specific configuration for that choice.

Thereafter fill important fields.

Example configuration for our local AD:

  • Server hostname - hostname or IP
  • Server port - usually 389 or 636
  • Principal - login of the user with admin privilege that CzechIdM will use for the connection. DN of the user should work too.
  • Principal password - password of the administrator user
  • Root suffixes - the list distinguished names of the roots that connector uses for managing users. If you do not want to manage some account, it is advised not to include them in the Root suffixes. When you configure the system for the first time, root suffix should lead to the top container (e.g. DC=aktest,DC=local), so the system schema can be correctly generated.
  • User search scope - manage users in specified container or subtrees. Usually subtree
  • Entry object classes - only objects (accounts) with object classes specified there will be managed. Each object class on new line, no comma or another separator. Usual values: top, person, organizationalPerson, inetOrgPerson,
  • Base contexts for user entry searches - usually the same as "Root suffixes".
  • Group members reference attribute - usually "member", use this if you want to manage group membership of user accounts
  • pageSize - this option is only available if you use connector that is customizes by BCV Solutions. It is advised to use number higher that number of accounts. E.g. 10000 for hundreds of accounts.
  • Uid Attribute - this is one of the most important option. It defines the primary key/UID of the account. Attribute values will be stored in CzechIdM for each account. Must be unique and should not change. It is strongly advised to use "sAMAccountName", since connId connector has some problem with returning this specific attribute if mapped by other means.
  • Object classes to synchronize - usually the same as "Entry object classes"
Beware on useVlvControls option. CzechIdM now only supports vlv control, so useVlvControls option should be enabled and vlvSortAttribute must be set (recommended option - 'sAMAccountName').
Since connector version 1.3.4.25 we support change of sAMAccount name, even if it is used as identifier (in provisioning mapping use sAMAccountName instead of __Uid__)
Since connector version 1.3.4.25 we support objectGUID as identifier, but only with this property turned off:
idm.sec.acc.provisioning.allowedAutoMappingOnExistingAccount=false

(in create action you have to send random String, because UID cannot be null and objectGUID will be obtained after create of user/group)

For next step, go to menu Scheme on your system.

You can let CzechIdM generate a scheme for you by clicking on Generate scheme button and that is also the preferred way. For MS AD, the connector usually creates 3 object types. _ACCOUNTS_, _ALL_, _GROUP_.  Schema generation

For user management, we will use ACCOUNT. Click on the detail of the object type and check that the scheme attributes list consists of all attributes you want to manage in AD. If the list doesn't contain any attribute, check that Root suffixes in the system configuration contains the value of the top container (so the connector can read the schema definitions).

If you are connecting AD for the first time, it is a good idea to check some minimal set of attributes that allows you to create an account, which is usually:

  • sAMAccountName - this attribute is not sometimes generated by default. If so you must create it manually. Use the button Add, fill in the name "sAMAccountName", type "java.lang.String", able to read, update, create and returned by default.
  • __ENABLE__ - if you want to allow disabling a user in AD. Sometimes this attribute is not generated by default, so you can create it manually.
  • __NAME__ (synonymous to DN, hard-coded in the connector).
You do not need to use all of the schema attributes for provisioning afterwards

If you want to set everything by yourself:

  • Use button Add to create a new scheme. For users, you need to name it "__ACCOUNT__", because it is a Connid constant
  • Add all attributes that you want to work with. As a minimum, the "__NAME__" and "sAMAccountName" attributes should be mapped.
  • Set all attributes as Able to read, update, create.

Now go to menu Mapping. There you must set, which attribute from scheme is mapped to which attribute in CzechIdM.

At first set:

  • Operation type: Provisioning - we want to manage data in AD from CzechIdM
  • Object name: __ACCOUNT__ - this is a standard type of scheme object in AD
  • Entity type: Identity - this entity type in CzechIdM we want to provision
  • As Mapping name set whatever you want, for example AD users prov mapping.

Then map scheme attributes to entity attributes as described below:

  • sAMAccountName
    • Name - sAMAccountName
    • Identifier - true
    • Entity attribute - true. Means that the attribute will be filled from basic Identity attribute set.
    • Entity field (selectbox) - User name
It is strongly advised to use __UID__ as an identifier, so that the identifier of the connector is the same as the identifier of the provisioning. Then some advanced CzechIdM features can be used and the debugging is also much easier

Other options may stay with default values.

__ENABLE__, mapping configuration is almost the same as __UID__, but do not set it as identifier. Map this schema attribute to entity attribute "Disabled". You should also add transformation to the system, because CzechIdM holds the attribute "disabled" and AD has attribute "enable". So the transformation should return opposite value of the attribute in CzechIdM. To do so, click on the Insert script button in "Transformation to system" window and find the script getOppositeBoolean. This should fill the window with the script call.

If you also want to create entities in AD, which is probable, map __NAME__ attribute that holds the DN of the account in AD. The configuration of the attribute may look like:

  • Attribute in schema - __NAME__,
  • Name - DN(__NAME__)
  • Entity attribute - true
  • Entity field - user name. In case that the DN on AD consists of the login of the user. Otherwise, you should choose other attribute or EAV.
  • The form of the DN varies on each instance of AD, so there usually will be some transformation to system like return "CN=" + attributeValue + ",OU=employees,DC=yourcompany,DC=com" . Of course your tree can be more complex, in that case you should follow some of our tutorials.

Password mapping

If you want to send passwords into Active Directory, you need to configure SSL communication.

When the mapping is set, the last step is to define a role in CzechIdM, that grants the user the account in AD. Prepare a new role in CzechIdM only with basic attributes. Name should be sufficient.

If you want some more options, follow How to create a role.

Then in the role detail, go the the menu tab Systems, add a new system and choose previously created one - "AD users and roles". Then also choose your provisioning mapping, there should be only one, and save it.

From now on, every time user gets the role, it is provisioned into the connected system AD. You can see that on users detail menu tab "Provisioning" or in the audit "Provisioning"

Finally, go to menu Provisioning and add new one set its Name and these fields:

  • Allowed: true
  • Set of mapped attributes: Select mapping from previous step.
  • Correlation attribute: __NAME__

You can leave the rest of configuration at the default values.

Group membership

If you want to add a user to an AD group via CzechIdM, you need appropriate Role there. So create a role that is almost similar to AD - Users above. Give it some better name that represents the group in AD, good idea is to use sAMAccountName or CN e.g. CRM basic user.

In the system AD - users schema setting, you need to have a special attribute defined that add the user to the group. The attribute is usually ldapGroups. Be sure, it can be read,create,update,delete. Attribute is multivalued. In the system configuration tab, there are some configuration properties, that must be set in order to allow group membership management.

  • Group members reference attribute - usually member. This represents the name of the attribute in AD that is present in Group. Its value is usually a DN of the user in the group.

Then continue to AD - users Mappings and edit provisioning mapping. Add there a ldapGroups attribute. It is not filled from any identity attribute and has no transformation. (It will be filled from the role). Since the attribute is multivalued, its filling strategy must be either MERGE or AUTHORITATIVE MERGE.

Get back to your role CRM basic user. In the tab Systems add a system AD - users and roles, save it. Then add an attribute that will be filled by this role - ldapGroups. Again choose the filling strategy MERGE or AUTH.MERGE. Then add a transformation that is the value of DN of the group in AD ' " ' sign on each side of the text.

Thus every user that has the role assigned is added to the group with provided DN via ldapGroups attribute.

Merge was fixed in connector version 1.3.4.25. Before Merge behaved like Authoritative Merge

Tips & Tricks

You can easily find DN of a user account with the help of Active Directory Users and Computers in your Windows server. Open the user's detail and switch to the tab Attribute Editor. You can see here the attributes in the same format as IdM sees them.

 Attributes editor

Moreover, CN of the user account is the same as Name so you can see it on the first page of the user's detail next to the icon.

 CN = Name