Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
tutorial:adm:manage_ad [2020/01/07 11:38] doischert |
tutorial:adm:manage_ad [2021/02/09 19:12] apeterova removed old info about ConnId - the connector is bundled, reformated some instructions |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Systems - AD: Manage users ====== | ====== Systems - AD: Manage users ====== | ||
| - | <note warning> | ||
| ===== 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. |
| ===== Before you start ===== | ===== Before you start ===== | ||
| Line 9: | Line 8: | ||
| ==== Adding Active Directory connector ==== | ==== Adding Active Directory connector ==== | ||
| - | First of all, you need to download | + | Since CzechIdM 9.2, the [[https://github.com/bcvsolutions/ad-connector|forked ConnId |
| - | Then add the jar file into CzechIdM folder | + | |
| - | + | ||
| - | <note tip>To preserve the connector during future upgrades of CzechIdM core, put the connector | + | |
| - | <code> | + | |
| - | ln -s / | + | |
| - | </code> | + | |
| - | </ | + | |
| - | + | ||
| - | 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). | + | |
| ==== Preparing Active Directory ==== | ==== Preparing Active Directory ==== | ||
| Line 54: | Line 44: | ||
| - Choose '' | - Choose '' | ||
| - Tick the '' | - Tick the '' | ||
| - | - Check the summary and finish the wizard. Changes are effective | + | - Check the summary and finish the wizard. Changes are effective |
| - Repeat for other subtrees as necessary. | - Repeat for other subtrees as necessary. | ||
| Line 84: | Line 74: | ||
| **Example configuration for our local AD:** | **Example configuration for our local AD:** | ||
| - | * **Server hostname** - hostname | + | |
| - | * **Server port** - usually | + | |
| - | * **Principal** - login of the user with admin privilege that CzechIdM will use for the connection. DN of the user should work too. | + | * **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 ''< | ||
| + | * **Principal** - login@domain | ||
| * **Principal password** - password of the administrator user | * **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. | + | * **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 | * **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, | * **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, | ||
| - | * **Base contexts for group entry searches** - container | + | * **Base contexts for group entry searches** - containers |
| * **Base contexts for user entry searches** - usually the same as "Root suffixes" | * **Base contexts for user entry searches** - usually the same as "Root suffixes" | ||
| - | * **Group members reference attribute** - usually | + | * **Group members reference attribute** - typically |
| - | * **pageSize** - this option is only available if you use connector that is customizes | + | * **useVlvControls** - enable the option. (This option is only available if you use connector that is customized |
| + | * **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 " | ||
| * **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 " | * **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 " | ||
| * **Object classes to synchronize** - usually the same as "Entry object classes" | * **Object classes to synchronize** - usually the same as "Entry object classes" | ||
| * **Specified attributes to be returned** - default " | * **Specified attributes to be returned** - default " | ||
| - | <note warning> | + | <note warning> |
| - | <note important> | + | <note important> |
| + | ];" error</ | ||
| - | <note important> | + | <note important> |
| <note important> | <note important> | ||
| Line 112: | Line 107: | ||
| {{ : | {{ : | ||
| - | 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' | + | 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' |
| 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 not sometimes generated by default. If so you must create it manually. Use the button **Add**, fill in the name " | * sAMAccountName - this attribute is not sometimes generated by default. If so you must create it manually. Use the button **Add**, fill in the name " | ||
| - | * \__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. | + | * \_\_ENABLE\_\_ |
| - | * \__NAME\__ (synonymous to DN, hard-coded in the connector). | + | * \_\_NAME\_\_ |
| + | * \_\_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 " | ||
| + | * ldapGroups - use this attribute if you want to manage users' group membership. This attribute is not created by default, add it manually: name " | ||
| <note tip>You do not need to use all of the schema attributes for provisioning afterwards</ | <note tip>You do not need to use all of the schema attributes for provisioning afterwards</ | ||
| Line 126: | Line 123: | ||
| If you want to set everything by yourself: | If you want to set everything by yourself: | ||
| - | * Use button **Add** to create a new scheme. For users, you need to name it " | + | * Use button **Add** to create a new scheme. For users, you need to name it " |
| * Add all attributes that you want to work with. As a minimum, the " | * Add all attributes that you want to work with. As a minimum, the " | ||
| * Set all attributes as **Able to read, update, create**. | * Set all attributes as **Able to read, update, create**. | ||
| Line 132: | Line 129: | ||
| <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 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 warning> | ||
| - | If you want to use the workflow for groups synchronization, | ||
| ===== Mapping ===== | ===== Mapping ===== | ||
| Line 148: | Line 143: | ||
| Then map scheme attributes to entity attributes as described below: | Then map scheme attributes to entity attributes as described below: | ||
| - | * **sAMAccountName** | + | **sAMAccountName** |
| - | * Name - sAMAccountName | + | * Name - sAMAccountName |
| - | * Identifier - true | + | * Identifier - true |
| - | * Entity attribute - true. Means that the attribute will be filled from basic Identity attribute set. | + | * Entity attribute - true. Means that the attribute will be filled from basic Identity attribute set. |
| - | * Entity field (selectbox) - User name | + | * Entity field (selectbox) - User name |
| - | <note tip>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 </ | + | <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 </ |
| Other options may stay with default values. | Other options may stay with default values. | ||
| - | **\_\_ENABLE\_\_**, | + | **\_\_ENABLE\_\_**, |
| 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: | ||
| Line 165: | Line 160: | ||
| * 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 '' | + | * The form of the DN varies on each instance of AD, so there usually will be some **transformation to system** like '' |
| ==== Password mapping ==== | ==== Password mapping ==== | ||
| - | <note tip>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, | ||
| + | * Attribute in schema - \_\_PASSWORD\_\_, | ||
| + | * Name - \_\_PASSWORD\_\_ | ||
| + | * Entity attribute - false | ||
| + | * Attribute with password - true | ||
| Line 184: | Line 185: | ||
| 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 " | 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 " | ||
| - | Finally, go to menu **Provisioning** and add new one set its **Name** and these fields: | ||
| - | |||
| - | * **Allowed: | ||
| - | * **Set of mapped attributes: | ||
| - | * **Correlation attribute: | ||
| - | |||
| - | You can leave the rest of configuration at the default values. | ||
| ====== Group membership ====== | ====== Group membership ====== | ||
| Line 196: | Line 190: | ||
| 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 usually | + | 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**. |
| 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. | * **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. | ||
| Line 205: | Line 199: | ||
| 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: | ||
| <note important> | <note important> | ||
| Line 237: | Line 233: | ||
| 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. | ||
| + | |||
| + | ===== SvcErr: DSID-031007E5 - unsupported special characters in DN ===== | ||
| + | |||
| + | The AD connector doesn' | ||
| + | < | ||
| + | javax.naming.NamingException: | ||
| + | </ | ||
| + | |||
| + | Please rename your containers so they don't contain special characters. | ||
| + | |||
| + | See more about this known issue here: https:// | ||
| + | |||
| + | ===== Failover ===== | ||
| + | |||
| + | 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). | ||
| + | |||
| + | The value of this property must be a proper URL, e.g. ''< | ||
| ===== Video Guide ===== | ===== Video Guide ===== | ||
| [[https:// | [[https:// | ||