Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
tutorial:adm:manage_ad [2021/06/24 07:07]
soval [Password mapping] 		tutorial:adm:manage_ad [2021/08/11 06:50] (current)
neznajf old revision restored (2021/06/25 12:41)
Line 1: Line 1:
 ====== Systems - AD: Manage users ====== ====== Systems - AD: Manage users ======
 +
 ===== Introduction ===== ===== Introduction =====
 +
 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. 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.
  
-You can as well use [[tutorial:adm:manage_ad_wizard|newer tutorial to use wizard for AD connection]] - you still will need this page to explain attributes not covered by wizard and troubleshooting.+You can as well use [[.:manage_ad_wizard|newer tutorial to use wizard for AD connection]] - you still will need this page to explain attributes not covered by wizard and troubleshooting.
  
 ===== Before you start ===== ===== Before you start =====
 +
 ==== Adding Active Directory connector ==== ==== Adding Active Directory connector ====
-Since CzechIdM 9.2, the [[https://github.com/bcvsolutions/ad-connector|forked ConnId AD connector]] is bundled inside CzechIdM by default. You can use it out of hand to test the basic functionality. However, it is advised to use the [[devel:documentation:adm:systems:winrm_ad_connector|WinRM + AD connector]] for the production-ready integration of CzechIdM <-> AD, as it enables more complex functionality.+ 
 +Since CzechIdM 9.2, the [[https://github.com/bcvsolutions/ad-connector|forked ConnId AD connector]] is bundled inside CzechIdM by default. You can use it out of hand to test the basic functionality. However, it is advised to use the [[:devel:documentation:adm:systems:winrm_ad_connector|WinRM + AD connector]] for the production-ready integration of CzechIdM <→ AD, as it enables more complex functionality.
  
 ==== Preparing Active Directory ==== ==== Preparing Active Directory ====
 +
 You must prepare your Active Directory for the CzechIdM integration, mainly: You must prepare your Active Directory for the CzechIdM integration, mainly:
 +
   * Enable LDAPS (SSL-protected LDAP protocol) on the AD. This is vital for production deployments. Also, CzechIdM will not manage users' passwords if not connected to AD through LDAPS.   * Enable LDAPS (SSL-protected LDAP protocol) on the AD. This is vital for production deployments. Also, CzechIdM will not manage users' passwords if not connected to AD through LDAPS.
   * Create an user account for the CzechIdM. Identity manager will use this account to perform operations on your AD. Although you can use a Domain Administrator account, we highly discourage it.   * Create an user account for the CzechIdM. Identity manager will use this account to perform operations on your AD. Although you can use a Domain Administrator account, we highly discourage it.
-    * This is simply a Domain User account like any other, but you should create it in different subtree than you want to manage through IdM.+      * This is simply a Domain User account like any other, but you should create it in different subtree than you want to manage through IdM.
   * Grant the CzechIdM user permissions on your AD.   * Grant the CzechIdM user permissions on your AD.
  
 === Granting permissions === === Granting permissions ===
-Suppose we have a domain ''PISKOVISTE.BCV'' with corresponding domain components ''DC=piskoviste,DC=bcv'' and the IdM application user is ''CzechIdM (czechidm@piskoviste.bcv)''. 
  
-  * CzechIdM needs to ''read'' AD configuration and schema subtrees. In our case: +Suppose we have a domain ''PISKOVISTE.BCV''  with corresponding domain components ''DC=piskoviste,DC=bcv''  and the IdM application user is ''CzechIdM (czechidm@piskoviste.bcv)''.
-    * ''CN=Configuration,DC=piskoviste,DC=bcv'' +
-    * ''CN=Schema,CN=Configuration,DC=piskoviste,DC=bcv''+
  
 +  * CzechIdM needs to ''read''  AD configuration and schema subtrees. In our case:
 +      * ''CN=Configuration,DC=piskoviste,DC=bcv''
 +      * ''CN=Schema,CN=Configuration,DC=piskoviste,DC=bcv''
 Ability to read schema and sufficient AD configuration should be there by default for an authenticated user. Probably no need to adjust it. Ability to read schema and sufficient AD configuration should be there by default for an authenticated user. Probably no need to adjust it.
  
-  * CzechIdM needs ''full control'' on subtrees which it will manage. Suppose we need to manage users, groups and computers and that we have a fairly simple setup. We grant full control to those subtrees: +  * CzechIdM needs ''full control''  on subtrees which it will manage. Suppose we need to manage users, groups and computers and that we have a fairly simple setup. We grant full control to those subtrees: 
-    * ''CN=Computers,DC=piskoviste,DC=bcv'' +      * ''CN=Computers,DC=piskoviste,DC=bcv'' 
-    * ''CN=Users,DC=piskoviste,DC=bcv'' +      * ''CN=Users,DC=piskoviste,DC=bcv'' 
-    * ''OU=Groups,DC=piskoviste,DC=bcv'' +      * ''OU=Groups,DC=piskoviste,DC=bcv''
 Which subtrees you need to grant privileges on depends on the actual directory tree of your Active Directory. Which subtrees you need to grant privileges on depends on the actual directory tree of your Active Directory.
  
Line 39: Line 44:
   - Right-click a container (in our case it was simply marked ''Users'').   - Right-click a container (in our case it was simply marked ''Users'').
   - Choose ''Delegate Control''.   - Choose ''Delegate Control''.
-  - Choose the ''CzechIdM (czechidm@piskoviste.bcv)'' user.+  - Choose the ''CzechIdM (czechidm@piskoviste.bcv)''  user.
   - Choose ''Create a custom task to delegate''.   - Choose ''Create a custom task to delegate''.
   - Choose ''This folder, existing objects in this folder, and creation of new objects in this folder''.   - Choose ''This folder, existing objects in this folder, and creation of new objects in this folder''.
-  - Tick the ''Full Control'' checkbox. This will tick all possible checkboxes in the dialog window.+  - Tick the ''Full Control''  checkbox. This will tick all possible checkboxes in the dialog window.
   - Check the summary and finish the wizard. Changes are effective immediately.   - Check the summary and finish the wizard. Changes are effective immediately.
   - Repeat for other subtrees as necessary.   - Repeat for other subtrees as necessary.
  
-<note important> +<note important> **CzechIdM has to have access to objects directly referenced from objects you manage.**
-**CzechIdM has to have access to objects directly referenced from objects you manage.**+
  
 For example: For example:
  
-A user is member of some groups, this is noted in his ''member'' attribute. If you want to manage the ''member'' attribute, the CzechIdM also has to have full access to the subtree with user groups. +A user is member of some groups, this is noted in his ''member''  attribute. If you want to manage the ''member''  attribute, the CzechIdM also has to have full access to the subtree with user groups. However this requirement is not transitive in groups hierarchy. In AD, you have a ''Groups\Domain Users''  group and every domain user is a member of this group. This means that every domain user has a ''member''  attribute which contains the ''Groups\Domain Users''  group DN. But the ''Groups\Domain Users''  is itself a member of ''Builtin\Users''  group.
-However this requirement is not transitive in groups hierarchy. +
-In AD, you have a ''Groups\Domain Users'' group and every domain user is a member of this group. This means that every domain user has a ''member'' attribute which contains the ''Groups\Domain Users'' group DN. +
-But the ''Groups\Domain Users'' is itself a member of ''Builtin\Users'' group.+
  
-If you want to manage your users and their group membership, you therefore need to grant full control on ''Users'' (to manage users) and ''Groups'' (because this is where ''Domain Users'' group is) **even if you do not want to manage groups themselves**. This is because of consistency checks performed by CzechIdM upon account provisioning.+If you want to manage your users and their group membership, you therefore need to grant full control on ''Users''  (to manage users) and ''Groups''  (because this is where ''Domain Users''  group is) **even if you do not want to manage groups themselves**. This is because of consistency checks performed by CzechIdM upon account provisioning. 
 + 
 +But you **do not need**  to grant anything on ''Builtin''  because this is referenced from an user account only indirectly. </note>
  
-But you **do not need** to grant anything on ''Builtin'' because this is referenced from an user account only indirectly. 
-</note> 
 ===== Basic configuration ===== ===== Basic configuration =====
-Go to **Systems** from main menu, then above list of current systems use Add button. On the first page just fill system name. + 
 +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. 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.
Line 67: Line 69:
 ===== Connector configuration ===== ===== Connector configuration =====
  
-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.+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. Thereafter fill important fields.
  
-**Example configuration for our local AD:**  +**Example configuration for our local AD:**
- +
-  * **SSL** - this is strongly advised to enable and also vital for managing the users' password +
-  * **Server hostname** - hostname of the AD domain controller. (IP address could be used as well, but then it must be stated in the server's certificate Subject Alternative Name) +
-  * **Server port** - typically 636. (389 if not using SSL) +
-  * **Failover** - an optional list of other domain controllers used in the case that the primary server is not available. Use URL format ''<nowiki>ldaps://123.456.789.012:636</nowiki>''. If using multiple values, write each value at a separate line. +
-  * **Principal** - login@domain of the user with admin privilege that CzechIdM will use for the connection. DN of the user works 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=company,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, user. +
-  * **Base contexts for group entry searches** - containers in AD where the groups are located. This must be specified if the groups are in different container than people and the group container is not under the path which is in "Root suffixes". You need to put it here, otherwise connector will not be able to load users' groups membership +
-  * **Base contexts for user entry searches** - usually the same as "Root suffixes". +
-  * **Group members reference attribute** - typically "member", use this if you want to manage group membership of user accounts +
-  * **useVlvControls** - enable the option. (This option is only available if you use connector that is customized by BCV solutions) +
-  * **pageSize** - we advise to set it to **100**. If you let the default 0, or ask for more than the limit for AD is, you will get an error when reading accounts. (This option is only available if you use connector that is customized by BCV solutions) +
-  * **vlvSortAttribute** - set to "sAMAccountName" +
-  * **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" +
-  * **Specified attributes to be returned** - default "ldapGroups" and "sAMAccountName". This option is also used when you need to read attributes from AD, that are not returned by default, a typical example is extensionAttribute1 and other additional attributes.+
  
 +  * **SSL**  - this is strongly advised to enable and also vital for managing the users' password
 +  * **Server hostname**  - hostname of the AD domain controller. (IP address could be used as well, but then it must be stated in the server's certificate Subject Alternative Name)
 +  * **Server port**  - typically 636. (389 if not using SSL)
 +  * **Failover**  - an optional list of other domain controllers used in the case that the primary server is not available. Use URL format ''<nowiki>ldaps://123.456.789.012:636</nowiki>''. If using multiple values, write each value at a separate line.
 +  * **Principal**  - login@domain of the user with admin privilege that CzechIdM will use for the connection. DN of the user works 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=company,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, user.
 +  * **Base contexts for group entry searches**  - containers in AD where the groups are located. This must be specified if the groups are in different container than people and the group container is not under the path which is in "Root suffixes". You need to put it here, otherwise connector will not be able to load users' groups membership
 +  * **Base contexts for user entry searches**  - usually the same as "Root suffixes".
 +  * **Group members reference attribute**  - typically "member", use this if you want to manage group membership of user accounts
 +  * **useVlvControls**  - enable the option. (This option is only available if you use connector that is customized by BCV solutions)
 +  * **pageSize**  - we advise to set it to **100**. If you let the default 0, or ask for more than the limit for AD is, you will get an error when reading accounts. (This option is only available if you use connector that is customized by BCV solutions)
 +  * **vlvSortAttribute**  - set to "sAMAccountName"
 +  * **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"
 +  * **Specified attributes to be returned**  - default "ldapGroups" and "sAMAccountName". This option is also used when you need to read attributes from AD, that are not returned by default, a typical example is extensionAttribute1 and other additional attributes.
 <note warning>If you are setting this on a Windows server, make sure to delete the 'Specified attributes to be returned' values and write them manually. Otherwise, ldapGroups will not be returned due to some white space problems</note> <note warning>If you are setting this on a Windows server, make sure to delete the 'Specified attributes to be returned' values and write them manually. Otherwise, ldapGroups will not be returned due to some white space problems</note>
  
-<note important>Beware on **useVlvControls** option. CzechIdM now only supports vlv control, so **useVlvControls** option should be enabled and **vlvSortAttribute** must be set (recommended option - 'sAMAccountName'). **DO NOT** use **CN**, **distinguishedName** or any other unindexed attribute or you'll end up with "[LDAP: error code 12 - 0000217A: SvcErr: DSID-03140414, problem 5010 (UNAVAIL_EXTENSION), data 0 +<note important>Beware on **useVlvControls**  option. CzechIdM now only supports vlv control, so **useVlvControls**  option should be enabled and **vlvSortAttribute**  must be set (recommended option - 'sAMAccountName'). **DO NOT**  use **CN**, **distinguishedName**  or any other unindexed attribute or you'll end up with "[LDAP: error code 12 - 0000217A: SvcErr: DSID-03140414, problem 5010 (UNAVAIL_EXTENSION), data 0 ];" error</note>
-];" error</note>+
  
-<note important>Since connector version 1.3.4.25 we support change of **sAMAccountName**, even if it is used as identifier (in provisioning mapping use sAMAccountName instead of \_\_Uid\_\_)</note> +<note important>Since connector version 1.3.4.25 we support change of **sAMAccountName**, even if it is used as identifier (in provisioning mapping use sAMAccountName instead of \_\_Uid\_\_)</note> <note important>Since connector version 1.3.4.25 we support objectGUID as identifier, but only with this property turned off: 
-<note important>Since connector version 1.3.4.25 we support objectGUID as identifier, but only with this property turned off: <code>idm.sec.acc.provisioning.allowedAutoMappingOnExistingAccount=false</code> (in create action you have to send random String, because UID cannot be null and objectGUID will be obtained after create of user/group)</note>+<code> 
 + 
 +idm.sec.acc.provisioning.allowedAutoMappingOnExistingAccount=false 
 + 
 +</code> 
 + 
 +(in create action you have to send random String, because UID cannot be null and objectGUID will be obtained after create of user/group)</note>
  
 ===== Scheme ===== ===== Scheme =====
-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\__. +For next step, go to menu **Scheme**  on your system. 
-{{ :tutorial:adm:schema_generation.png | Schema generation}} + 
-  +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.png  | 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 or contains 6 or less, check that **Root suffixes** in the system configuration contains the value of the top container (so the connector can read the schema definitions).+ 
 +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 or contains 6 or less, 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: 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 sometimes not generated by default (mainly if it isn't used as Uid). 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.   * sAMAccountName - this attribute is sometimes not generated by default (mainly if it isn't used as Uid). 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. This attribute is not generated by default, so you can create it manually. Use the button **Add**, fill in the name "\_\_ENABLE\_\_", type "java.lang.Boolean", able to read, update, create and returned by default. +  * _\_ENABLE_\_ - if you want to allow disabling a user in AD. This attribute is not generated by default, so you can create it manually. Use the button **Add**, fill in the name "\_\_ENABLE\_\__ckgedit>, type "java.lang.Boolean", able to read, update, create and returned by default. * \_\_NAME\_\_ (synonymous to DN, hard-coded in the connector). This attribute should be generated by default. If not, use the button **Add**, fill in the name "\_\_NAME\_\__ckgedit>, type "java.lang.String", able to read, update, create and returned by default.
-  * \_\_NAME\_\_ (synonymous to DN, hard-coded in the connector). This attribute should be generated by default. If not, use the button **Add**, fill in the name "\_\_NAME\_\_", type "java.lang.String", able to read, update, create and returned by default.+
   * \_\_PASSWORD\_\_ - this special attribute is used for setting the passwords for user accounts. User in AD can't be activated when a password is not set. This attribute is not created by default in the schema, so you must add it manually: name "\_\_PASSWORD\_\_", type "eu.bcvsolutions.idm.core.security.api.domain.GuardedString", able to update, create   * \_\_PASSWORD\_\_ - this special attribute is used for setting the passwords for user accounts. User in AD can't be activated when a password is not set. This attribute is not created by default in the schema, so you must add it manually: name "\_\_PASSWORD\_\_", type "eu.bcvsolutions.idm.core.security.api.domain.GuardedString", able to update, create
   * ldapGroups - use this attribute if you want to manage users' group membership. This attribute is not created by default, add it manually: name "ldapGroups", type "java.lang.String", able to read, multivalued, able to create, edit, returned by default   * ldapGroups - use this attribute if you want to manage users' group membership. This attribute is not created by default, add it manually: name "ldapGroups", type "java.lang.String", able to read, multivalued, able to create, edit, returned by default
Line 118: Line 123:
 <note tip>You do not need to use all of the schema attributes for provisioning afterwards</note> <note tip>You do not need to use all of the schema attributes for provisioning afterwards</note>
  
-{{ :tutorial:adm:schema_attributes_list.png |}}+{{  .:schema_attributes_list.png  }}
  
 <note tip>It is possible you will not see the full scheme even with root suffix set to the top container. In that case, check that schemas are not stored separately and if they are, set root suffixes to the appropriate DC.</note> <note tip>It is possible you will not see the full scheme even with root suffix set to the top container. In that case, check that schemas are not stored separately and if they are, set root suffixes to the appropriate DC.</note>
- 
  
 ===== Mapping ===== ===== Mapping =====
Line 128: Line 132:
  
 At first set: 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**. 
  
-{{ :tutorial:adm:attributes_mapping.png |}}+  * **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**. 
 + 
 +{{  .:attributes_mapping.png  }} 
 + 
 +Then map scheme attributes to entity attributes as described below: **sAMAccountName**
  
-Then map scheme attributes to entity attributes as described below: 
-**sAMAccountName** 
   * Name - sAMAccountName   * Name - sAMAccountName
   * Identifier - true   * Identifier - true
Line 142: Line 147:
   * Entity field (selectbox) - User name   * Entity field (selectbox) - User name
  
-<note tip>It is strongly advised to use **sAMAccountName** 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 </note>+<note tip>It is strongly advised to use **sAMAccountName**  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 </note>
  
 Other options may stay with default values. Other options may stay with default values.
  
-**\_\_ENABLE\_\_**, mapping configuration is almost the same as **sAMAccountName**, 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 will fill the window with the script call, but you must also add the line ''.addParameter('attributeValue', attributeValue)'' after the similar line with "scriptEvaluator" (see [[tutorial:adm:transformation_scripts#a_library_script_use|this tutorial]] for using Standard transformation scripts).+**\_\_ENABLE\_\_**, mapping configuration is almost the same as **sAMAccountName**, 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 will fill the window with the script call, but you must also add the line ''.addParameter('attributeValue', attributeValue)''  after the similar line with "scriptEvaluator" (see [[.:transformation_scripts#a_library_script_use|this tutorial]] for using Standard transformation scripts). 
 + 
 +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:
  
-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\_\_,   * Attribute in schema - \_\_NAME\_\_,
   * Name - DN(\_\_NAME\_\_)   * Name - DN(\_\_NAME\_\_)
   * Entity attribute - true   * 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.   * 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 [[tutorial:adm:transformation_scripts|tutorials]]+  * 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 [[.:transformation_scripts|tutorials]]
  
 ==== Password mapping ==== ==== Password mapping ====
Line 159: Line 165:
 If you want to send passwords into Active Directory, you need to configure SSL communication. If you want to send passwords into Active Directory, you need to configure SSL communication.
  
-To enable passwords provisioning, add the attribute **\_\_PASSWORD\_\_** to the schema attributes (as written above) and map it as follows:+To enable passwords provisioning, add the attribute **\_\_PASSWORD\_\_**  to the schema attributes (as written above) and map it as follows: 
   * Attribute in schema - \_\_PASSWORD\_\_,   * Attribute in schema - \_\_PASSWORD\_\_,
   * Name - \_\_PASSWORD\_\_   * Name - \_\_PASSWORD\_\_
Line 165: Line 172:
   * Attribute with password - true   * Attribute with password - true
  
 +==== Forced password change (User must change password at next logon) ====
  
-==== Send additional attributes with password ====+When mapping AD attributes, it is sometimes useful to be able to set a forced password change option. This requirement is often set for two different cases:
  
-It's possible to send additional attributes to provisioning, when password is changed (e.g. password expiration in extended attribute). New flag ''sendOnPasswordChange'' was added to system attribute mapping - attribute with this flag checked will be send together with changed password to provisioning. Two ways for provisioning additional attributes are implemented: +* We need to change the password when logging into AD **for a new user account**  * We need to force a password change but **only after a password reset**
-  - send additional attributes together with new password in one provisioning operation +
-  - send additional attributes after password is changed in another provisioning operation  +
-Two ways are be configurable by application configuration ''idm.sec.acc.provisioning.sendPasswordAttributesTogether'': +
-    * ''true'': additional password attributes will be send in one provisioning operation together with password +
-    * ''false'': additional password attributes will be send in new provisioning operation, after password change operation (some systems doesn't support to change other attributes in the same request with password)+
  
-<note tip>Configuration is effective for all target systems. All target system will be using one configured way (configuration per-system is not implemented, coming soon).</note>+1/ To force a password change for newly created users, map the **"pwdLastSet"**  attribute. The attribute should be in the generated system schema, object "**\_\_ACCOUNT\_\_**" name "pwdLastSet", Data type "java.lang.Boolean". So add the attribute to the mapping and put "return true" in the transformation script(Transformation to system) and set the strategy "Write only on create of the entity".
  
-=== Send attribute only on password change === +2/ If we need to force password change every time password is reset, map attribute pwdLastSet too, but **with checkbox "Include on password" and "Include only when password is changed"**  and strategy "Set value as it is". This can only be set since IdM version 11.0. In the picture you can see the attribute in the active directory.
-Since version **11.0.0** a new flag **Send only on password change** was added to the attribute detail.+
  
-If is this flag checked, then the attribute will be send to the system only during change of password operation. It means that this attribute will be ignored in standard provisioning operations (create/update). +{{.:user_must_change-password_properties.png}}
-<note important>This checkbox can be use only if attribute has checked flag **Send additional attributes with password**.</note> +
  
 ===== Role for AD ===== ===== Role for AD =====
-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 [[tutorial:adm:new_role| How to create a role]].+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 [[.:new_role|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. 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.
  
-{{ :tutorial:adm:ad_user.png |}}+{{  .:ad_user.png  }}
  
-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" +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"
  
 <note important>Check if the user created in IdM has password according to Active directory password policy, otherwise user can be created in IdM but not provisioned to AD system.</note> <note important>Check if the user created in IdM has password according to Active directory password policy, otherwise user can be created in IdM but not provisioned to AD system.</note>
- 
  
 ====== Group membership ====== ====== 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**.+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 named **ldapGroups**. Make sure, it can be read,create,update,delete. Attribute is multivalued. +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 named **ldapGroups**. Make 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.
-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** (recommended for AD) or AUTHORITATIVE MERGE ([[devel:documentation:adm:systems#synchronizationprovisioning_strategies|info about strategies]]).+  * **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**  (recommended for AD) or AUTHORITATIVE MERGE ([[:devel:documentation:adm:systems#synchronizationprovisioning_strategies|info about strategies]]).
  
-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, make sure to use the same as in the provisioning mapping). Then **add a transformation** that is the value of DN of the group in AD ' " ' sign on each side of the text.+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, make sure to use the same as in the provisioning mapping). 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. Thus every user that has the role assigned is added to the group with provided DN via ldapGroups attribute.
  
-For managing group membership in multi domain AD environment follow [[tutorial:adm:systems_-_manage_groups_membership_in_multi_domain_cross_domain_ad_environment|this tutorial]]+For managing group membership in multi domain AD environment follow [[.:systems_-_manage_groups_membership_in_multi_domain_cross_domain_ad_environment|this tutorial]]
  
 <note important>Merge was fixed in connector version 1.3.4.25. Before Merge behaved like Authoritative Merge</note> <note important>Merge was fixed in connector version 1.3.4.25. Before Merge behaved like Authoritative Merge</note>
Line 220: Line 219:
 ===== Distinguished Name (DN), Common Name (CN) ===== ===== Distinguished Name (DN), Common Name (CN) =====
  
-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.+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.
  
-<note>If you do not see the Attributes editor, you have to switch it on. Go to ''Active Directory Users and Commputers'' -> ''View'' and select ''Advanced features''.</note>+<note>If you do not see the Attributes editor, you have to switch it on. Go to ''Active Directory Users and Commputers''  → ''View''  and select ''Advanced features''.</note>
  
-{{ :tutorial:adm:ad_user_properties_attributes.png | Attributes editor}}+{{  .:ad_user_properties_attributes.png  | 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.+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.
  
-{{ :tutorial:adm:ad_user_properties_general.png | CN = Name }}+{{  .:ad_user_properties_general.png  | CN = Name }}
  
 ===== ldapGroups not returned ===== ===== ldapGroups not returned =====
Line 237: Line 236:
  
 AD enables additional attributes named extensionAttribute1 - extensionAttribute10. If you want to fill these attributes by IdM, you must do following steps in the configuration of the connected system: AD enables additional attributes named extensionAttribute1 - extensionAttribute10. If you want to fill these attributes by IdM, you must do following steps in the configuration of the connected system:
-  * Go to **Configuration** -> **Specified attributes to be returned (multi)**, add **extensionAttribute1** to a new line under existing values. + 
-  * Go to **Scheme** -> **\_\_ACCOUNT\_\_** -> use the button **Add**, fill in the name **extensionAttribute1**, type "java.lang.String", select able to read, update, create and returned by default. +  * Go to **Configuration**  → **Specified attributes to be returned (multi)**, add **extensionAttribute1**  to a new line under existing values. 
-  * Go to **Mapping** -> **Provisioning mapping** -> use the button **Add** and map the attribute according to your choice. The following example can be used when you want to fill the extensionAttribute1 by personal numbers of identities +  * Go to **Scheme**  → **\_\_ACCOUNT\_\_**  → use the button **Add**, fill in the name **extensionAttribute1**, type "java.lang.String", select able to read, update, create and returned by default. 
-    * Attribute in schema - extensionAttribute1 +  * Go to **Mapping**  → **Provisioning mapping**  → use the button **Add**  and map the attribute according to your choice. The following example can be used when you want to fill the extensionAttribute1 by personal numbers of identities 
-    * Name - extensionAttribute1 +      * Attribute in schema - extensionAttribute1 
-    * Entity attribute - true +      * Name - extensionAttribute1 
-    * Entity field - Personal number+      * Entity attribute - true 
 +      * Entity field - Personal number
  
 ===== Connection via SSL not working ===== ===== Connection via SSL not working =====
-If you just imported root certificate to IdM truststore, but SSL connection to AD is still not working try following method to find which server hostname you should use. + 
-Configure connection via SSL to AD in Apache Directory Studio during connection you will see this window: +If you just imported root certificate to IdM truststore, but SSL connection to AD is still not working try following method to find which server hostname you should use. Configure connection via SSL to AD in Apache Directory Studio during connection you will see this window: {{.:trust.png?400}}click on View certificate → tab General → field Issued To → Common name(CN) and use this value as server hostname.
-{{:tutorial:adm:trust.png?400|}} +
-click on View certificate -> tab General -> field Issued To -> Common name(CN) and use this value as server hostname.+
  
 ===== LdapErr: DSID-0C0907C5 ===== ===== LdapErr: DSID-0C0907C5 =====
 +
 If you see this error when reconciliating AD groups: If you see this error when reconciliating AD groups:
-<code>org.identityconnectors.framework.common.exceptions.ConnectorException: javax.naming.OperationNotSupportedException: [LDAP: error code 12 - 00000057: LdapErr: DSID-0C0907C5, comment: Error processing control, data 0, v1db1]; remaining name 'OU=company,DC=domain,DC=tld'</code>+<code> 
 + 
 +org.identityconnectors.framework.common.exceptions.ConnectorException: javax.naming.OperationNotSupportedException: [LDAP: error code 12 - 00000057: LdapErr: DSID-0C0907C5, comment: Error processing control, data 0, v1db1]; remaining name 'OU=company,DC=domain,DC=tld' 
 + 
 +</code>
  
 the likely cause is that some groups have many members. AD has a property MaxPageSize which is probably set to lower than necessary (default is 1000). Increasing the value to an arbitrary large number (30000) helped in our case but only AD admin can change this. the likely cause is that some groups have many members. AD has a property MaxPageSize which is probably set to lower than necessary (default is 1000). Increasing the value to an arbitrary large number (30000) helped in our case but only AD admin can change this.
Line 260: Line 263:
  
 The AD connector doesn't support containers (OU) that contain some special characters in their names, namely the forward slash ("/"). When you try to update some user, whose DN contains this character (even when updating only some other attributes), then the provisioning fails with the following exception: The AD connector doesn't support containers (OU) that contain some special characters in their names, namely the forward slash ("/"). When you try to update some user, whose DN contains this character (even when updating only some other attributes), then the provisioning fails with the following exception:
 +
 <code> <code>
 javax.naming.NamingException: [LDAP: error code 1 - 000020D6: SvcErr: DSID-031007E5, problem 5012 (DIR_ERROR), data 0 javax.naming.NamingException: [LDAP: error code 1 - 000020D6: SvcErr: DSID-031007E5, problem 5012 (DIR_ERROR), data 0
 +
 </code> </code>
  
 Please rename your containers so they don't contain special characters. Please rename your containers so they don't contain special characters.
  
-See more about this known issue here: https://redmine.czechidm.com/issues/2294.+See more about this known issue here: [[https://redmine.czechidm.com/issues/2294|https://redmine.czechidm.com/issues/2294]].
  
 ===== Failover ===== ===== Failover =====
Line 272: Line 277:
 The configuration property Failover is used when the primary server (configured in the Server hostname) is unavailable. The attribute contains a list of AD servers that connector can use. The configuration property Failover is used when the primary server (configured in the Server hostname) is unavailable. The attribute contains a list of AD servers that connector can use.
  
-Please note that this property is not used in the case that the primary server is accessible on the given port, but there is some other problem with the communication (e.g. the credentials are incorrect). +Please note that this property is not used in the case that the primary server is accessible on the given port, but there is some other problem with the communication (e.g. the credentials are incorrect).
  
 The value of this property must be a proper URL, e.g. ''<nowiki>ldaps://some.hostname:636</nowiki>''. If using multiple values, write each value at a separate line. The value of this property must be a proper URL, e.g. ''<nowiki>ldaps://some.hostname:636</nowiki>''. If using multiple values, write each value at a separate line.
- 
  
 ===== Video Guide ===== ===== Video Guide =====
 +
 [[https://www.youtube.com/watch?v=ZbQCH_BYd-k&list=PLBeAQt3pe3EcdVE8QpCDEJcDsi_jtNQUb&index=7|How to create role for AD group]] - czech language [[https://www.youtube.com/watch?v=ZbQCH_BYd-k&list=PLBeAQt3pe3EcdVE8QpCDEJcDsi_jtNQUb&index=7|How to create role for AD group]] - czech language
 +
 +
  • by soval