.. _set_up_ldap_custom_role_mappings:

Set up LDAP Custom Role Mappings
--------------------------------

.. _19.1.2|VOSS-541:


This feature is used to apply customized roles to LDAP Synced and moved users,
and to overwrite the default roles that are applied to them following an LDAP User
Sync or Move User operation.


.. important::

   For LDAP User Sync
   
   * When a user is synced in from an LDAP server, by default they are assigned
     the role configured in the 'User Role (default)' in the LDAP User Sync.
   * If the user's **Active Directory Group** Membership matches a group
     configured in the Custom Role Mapping, and the hierarchy of the LDAP User Sync
     matches the **Target Role Context**, then the role specified in the Custom
     Role Mapping will take precedence over the 'User Role (default)'.
     
   For Move User     
     
   * When a user is moved to a hierarchy manually using 'Move Users', by default
     they are assigned the role specified in the 'Set Default Role'.
   * If the user's **Active Directory Group** matches a group configured in the
     Custom Role Mapping, and the user's destination hierarchy type matches the
     **Target Role Context**, then the role specified in the Custom Role Mapping
     will take precedence over the 'Set Default Role' chosen in 'Move Users'.
   * When a user is moved to a hierarchy automatically using a filter, they are
     assigned the role specified in the filter in 'Set Default Role' by default.
   * If the user's **Active Directory Group** Membership matches a group configured
     in the Custom Role Mapping, and the user's destination hierarchy type,
     specified in the filter matches the **Target Role Context**, then the role
     specified in the Custom Role Mapping will take precedence over the
     'Set Default Role' set in the filter.   

    
   

Procedure
.........

1. Log in as provider or reseller administrator.
2. Set the hierarchy path to where the LDAP Custom Role Mapping must be added.
3. Choose **LDAP Management > LDAP Custom Role Mappings**.
4. Click **Add**.
5. Complete the following mandatory fields:

.. tabularcolumns:: |p{2cm}|p{13cm}|

+---------------------+--------------------------------------------------+
| Field               | Description                                      |
+=====================+==================================================+
| Active Directory    | A group in the Active Directory to which the     |
| Group*              | user belongs. This is derived from the 'memberOf'|
|                     | from the LDAP Schema. This must be an exact      |
|                     | match of the value defined in Active Directory,  |
|                     | e.g. CN=Administrators,CN=Builtin,DC=test,DC=net.|
+---------------------+--------------------------------------------------+
| Target Role Context*| This value defines the hierarchy for which the   |
|                     | Custom Role Mapping will be applied. This must   |
|                     | match the hierarchy type where the users are     |
|                     | Synced, or their destination hierarchy when      |
|                     | moved.                                           |
|                     |                                                  |
|                     | For example, if the user is assigned a           |
|                     | 'CustomerAdmin' role, and the LDAP User Sync is  |
|                     | configured at Customer level then the **Target   |
|                     | Role Context** must be set to Customer. If the   |
|                     | user is assigned a 'SiteAdmin' role, and the     |
|                     | user is being moved either manually or           |
|                     | automatically using 'Filter to a Site', then the |
|                     | **Target Role Context** must be set to Site.     |
|                     |                                                  |
|                     | Choose the hierarchy node type from the drop-down|
|                     | list.                                            |
+---------------------+--------------------------------------------------+
| Target Role*        | The role which will be applied to the user if    |
|                     | their **Active Directory Group** and **Target    |
|                     | Role Context** are matched. This must be a valid |
|                     | role at the user's destination hierarchy. This   |
|                     | can be defined at a specific role or defined as a|
|                     | macro, e.g. if the user is assigned a 'SiteAdmin'|
|                     | role then the role can be defined as the exact   |
|                     | name of the role or defined as a macro, which    |
|                     | allows re-use for any site name e.g.             |
|                     | {{macro.SITENAME}}SiteAdmin.                     |
+---------------------+--------------------------------------------------+

6. Click **Save**.