.. _set_up_ldap_custom_role_mappings:

Set Up LDAP Custom Role Mappings
--------------------------------

.. _19.1.2|VOSS-541:


This procedure applies customized roles to LDAP synced and moved users,
and overwrites the default roles that are applied following an LDAP User
Sync or Move User operation.

.. note::

   This procedure is relevant only for top-down deployments.


.. important::

   For LDAP User Sync

   * By default, users synced in from an LDAP server are assigned
     the role configured in the 'User Role (default)' in the LDAP User Sync.
   * The role specified in the Custom Role Mapping takes precedence over the 'User Role
     (default)', when both of the following conditions are met:

     * The user's **Active Directory Group** Membership matches a group
       configured in the Custom Role Mapping.
     * The hierarchy of the LDAP User Sync matches the **Target Role Context**.

   For Move User

   * By default, users moved manually to a hierarchy (using 'Move Users') are
     assigned the role specified in the 'Set Default Role'.
   * The role specified in the Custom Role Mapping takes precedence
     over the 'Set Default Role' chosen in 'Move Users', when both of the following
     conditions are met:

     * The user's **Active Directory Group** matches a group configured in the
       Custom Role Mapping.
     * The user's destination hierarchy type matches the **Target Role Context**.

   * By default, a user moved to a hierarchy automatically (using a filter), is
     assigned the role specified in the filter in 'Set Default Role'.
   * The role specified in the Custom Role Mapping takes precedence over the
     'Set Default Role' set in the filter, when both of the following conditions are
     met:

     * The user's **Active Directory Group** Membership matches a group configured
       in the Custom Role Mapping.
     * The user's destination hierarchy type (specified in the filter), matches
       the **Target Role Context**,



**Perform these steps**:

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**.