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
Next revision Both sides next revision
tutorial:adm:manage_ad [2019/02/27 14:58]
fiserp [Before you start] 		tutorial:adm:manage_ad [2020/01/07 11:38]
doischert
Line 1: Line 1:
 ====== Systems - AD: Manage users ====== ====== Systems - AD: Manage users ======
 +<note warning>This tutorial uses AD bundle connector, which is OBSOLETE. Since CzechIdM v 9.7.x, it is advised to use our new AD+Powershell connector</note>
  
 ===== Introduction ===== ===== Introduction =====
Line 7: Line 8:
  
 ==== Adding Active Directory connector ==== ==== Adding Active Directory connector ====
 +
 First of all, you need to download the connector from Connid (e.g. [[http://repo1.maven.org/maven2/net/tirasa/connid/bundles/net.tirasa.connid.bundles.ad/1.3.4/net.tirasa.connid.bundles.ad-1.3.4.jar| Connid AD bundle 1.3.4 jar file]]). First of all, you need to download the connector from Connid (e.g. [[http://repo1.maven.org/maven2/net/tirasa/connid/bundles/net.tirasa.connid.bundles.ad/1.3.4/net.tirasa.connid.bundles.ad-1.3.4.jar| 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/''.  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/''. 
Line 19: Line 21:
  
 ==== Preparing Active Directory ==== ==== Preparing Active Directory ====
 +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.
 +  * 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.
 +  * Grant the CzechIdM user permissions on your AD.
  
 +=== 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:
 +    * ''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.
 +
 +  * 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=Users,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.
 +
 +**Granting full control to CzechIdM application user**
 +
 +The process is fairly straightforward. Just repeat it for every root of every subtree you need to grant the rights on.
 +
 +  - Open the ''Active Directory Users and Computers''.
 +  - Right-click a container (in our case it was simply marked ''Users'').
 +  - Choose ''Delegate Control''.
 +  - Choose the ''CzechIdM (czechidm@piskoviste.bcv)'' user.
 +  - Choose ''Create a custom task to delegate''.
 +  - 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.
 +  - Check the summary and finish the wizard. Changes are effective immediatelly.
 +  - Repeat for other subtrees as necessary.
 +
 +<note important>
 +**CzechIdM has to have access to objects directly referenced from objects you manage.**
 +
 +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.
 +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.
 +
 +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. 
Line 39: Line 90:
   * **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=aktest,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, inetOrgPerson,+  * **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** - container in AD where the groups are located. If the groups are in different container then 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
   * **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 "member", use this if you want to manage group membership of user accounts   * **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.+  * **pageSize** - this option is only available if you use connector that is customizes by BCV Solutions. Leave it at default (100), if you ask for more than the limit for AD is, you will get an error.
   * **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.**   * **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"   * **Object classes to synchronize** - usually the same as "Entry object classes"
 +  * **Specified attributes to be returned** - default "ldapGroups" and "sAMAccountName"
 +
 +<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. </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').</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').</note>
Line 74: Line 129:
   * Add all attributes that you want to work with. As a minimum, the "**\_\_NAME\_\_**" and "**sAMAccountName**" attributes should be mapped.   * 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**.    * Set all attributes as **Able to read, update, create**. 
 +
 +<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 warning>In order to activate a user in AD, you must send a password. The attribute password is not created by default in the schema, so you must add it manually: name<nowiki> "__PASSWORD__", </nowiki>type "eu.bcvsolutions.idm.core.security.api.domain.GuardedString".
 +If you want to use the workflow for groups synchronization, you must also create an attribute in schema, this time called "ldapGroups", type "java.lang.String".</note>
  
 ===== Mapping ===== ===== Mapping =====
Line 161: Line 221:
  
 {{ :tutorial:adm:ad_user_properties_general.png | CN = Name }} {{ :tutorial:adm:ad_user_properties_general.png | CN = Name }}
 +
 +===== ldapGroups not returned =====
 +
 +If you are running on a Windows server, the 'ldapGroups' in 'Specified attributes to be returned' has the wrong value 'ldapGroups\r' (this is only visible in Audit). The solution is to remove the value in 'Specified attributes to be returned' and write it again manually.
 +
 +===== 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:
 +{{: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 =====
 +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=BohemiaEnergy,DC=bohemiaenergy,DC=local'</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.
  
 ===== 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 neznajf