LDAP Plugin for Risk Exchange

This document explains how to configure the LDAP v1.0.0 plugin for the Risk Exchange module of the Netskope Cloud Exchange platform. This plugin fetches users from the provided Search Base path. It also supports Add to group and Remove from group action on users.

Prerequisites

To complete this integration, you need:

• A Netskope tenant (or multiple, for example, production and development/test instances).
• A Netskope Cloud Exchange tenant with the Tenant plugin and Risk Exchange plugin already configured.
• LDAP Server address, Port, Username, Password, Search Base, and Certificate (Only in case of secured port).

LDAP Plugin Support

LDAP plugin fetches users from provided Search Base path. It also supports Add to group and Remove from group action on users.

Type of Data Pulled	Users
Actions Supported	Add to group Remove from group No Action

Mappings

Mapping will be used to view the pulled Users and their respective details. Mapped fields during plugin configuration will be visible on the Records page once the data is pulled. Below is the suggested mapping that should be used while configuring the plugin.

Pull Mapping for Users

Plugin Field Label	Expected Data Type	Suggested Field Label	Suggested Aggregate Strategy
User Principal Name	String	User Principal Name	Unique
Distinguished Name (DN)	String	Distinguished Name (DN)	Override
Email Address	String	Email Address	Override
User Groups	List	User Groups	Override
User Name	String	User Name	Override

Permissions

The user account that you are using to configure the LDAP plugin should have these permissions: Create, delete and manage groups.

API Details

This plugin uses the ldap3 (v2.9.1) python library in order to perform its workflow.

• Plugin uses Server class from ldap3 to create server objects and Connection class to create connections. It also uses TLS class to create a secure TLS connection using certificates.
• Here is the script that shows its usage:

tls = Tls(
    validate=ssl.CERT_REQUIRED,
    version=ssl.PROTOCOL_TLS,
    ca_certs_data=ldap_cert,
)
server = Server(
    host=(f"ldaps://{server_ip}" if ldap_cert else f"ldap://{server_ip}"),
    port=port,
    use_ssl=True if ldap_cert else self.ssl_validation,
    tls=tls if ldap_cert else None,
    connect_timeout=VALIDATION_TIMEOUT if is_validation else TIMEOUT,
)
conn = Connection(
    server,
    username,
    password,
    auto_bind=True,
    authentication="SIMPLE",
    raise_exceptions=True,
    receive_timeout=(VALIDATION_TIMEOUT if is_validation else TIMEOUT),
)

Note that the VALIDATION_TIMEOUT is 60 seconds for validation calls, and TIMEOUT is 300 seconds for other functionality.

• Plugin uses conn.extend.standard.paged_search method to pull users and groups using pagination. In 1 page maximum 10000 users can be pulled.

USER_SEARCH_FILTER = (
    "(|(objectClass=person)(objectClass=inetOrgPerson)(objectClass=User))"
)
attributes = conn.extend.standard.paged_search(
    search_base=search_base,
    search_filter=USER_SEARCH_FILTER,  #
    attributes={
        "userPrincipalName",
        "mail",
        "distinguishedName",
        "name",
        "memberOf",
    },
    search_scope="SUBTREE",
    paged_size=10000,
    generator=True,
    time_limit=TIMEOUT,
)
for attribute in attributes:
    # Logic to fetch users.

The search_filter will vary for different use cases.

• Pull Users: “(|(objectClass=person)(objectClass=inetOrgPerson)(objectClass=User))”
• Update Users: “(&(|(objectClass=person)(objectClass=inetOrgPerson)(objectClass=User))(|(userPrincipalName=testuser.ldap.local)))”
• Pull groups:
  • Search filter: (objectClass=group)
  • Attributes: {“name”, “distinguishedName”}
• For the Add to group action ad_add_members_to_groups method is used.

ad_add_members_to_groups(
       connection=conn,
       members_dn=user_info.get("dn"),
       groups_dn=group_info.get("dn"),
       raise_error=True,
)

• For the Remove from group ad_remove_members_from_groups method is used.

ad_remove_members_from_groups(
      connection=conn,
      members_dn=user_id,
      groups_dn=group_id,
      fix={
            "member": user_id,
            "group": group_id,
      },
      raise_error=True,
)

Performance Matrix

Here is the performance matrix conducted on a Large CE Stack with these specifications by pulling 500K Users.

Stack Size	Large RAM: 32 GB Core: 16
Time taken to store the pulled and updated host records	~74 mins

Workflow

1. Get a Search Base Path.
2. Add permissions for a user.
3. Configure the LDAP plugin.
4. Add a Risk Exchange Business Rule for LDAP.
5. Add Risk Exchange Actions for LDAP.
6. Validate the LDAP plugin.

Click play to watch a video.

Get a Search Base Path

Search Base is the Base path from which the group needs to be fetched; you can get it from the Server backend.

1. Go to the LDAP server.
2. Open Server Manager.
3. Click Tools and select Active Directory Administrative Center.
   
4. The screen shown will appear.
   
5. Select any of the folders your groups are stored in. For example, the groups are stored under Users directory. 
   
6. Click the top screen Active Directory Administrative Center > ldapstest(local).
7. Clicking it will display this screen.
   
8. Copy that Path and use it in the plugin configuration.

Provide Permissions to a User

Follow these steps to provide the permissions to the user:

1. Open your server manager.
2. Click Tools and open Active Directory Users and Computers.
3. Select the folder in which your user exists. For example, the user Test LDAP exists in users directory. Right-click on that directory and open Delegate Control. 
   
4. Click Next.
5. Click Add to add the user for which you want to add permission.
6. After clicking Add, this window will appear. Enter the object name and click Check Names. If the user is present, it will automatically add the full name.
   
7. Click OK.
8. Click Next.
9. You’ll see this window.
   
10. To run the LDAP plugin, you need to provide these permissions:
    Create, delete, and manage groups.
11. Click Next, and then click Finish.
12. The user has the permissions to run the LDAP plugin.

Configure the LDAP Plugin

1. In Cloud Exchange, go to Settings > Plugins. Search for and select the LDAP 1.0.0 (CRE) plugin box.
   
2. Enter a Configuration Name, change the Sync Interval as per your requirement, or keep as default.
   
3. Click Next. Enter the Server Address (IP/DNS), Port, Username, Password, Search Base, and Certificate (In case of a secured port).
   • Server Address, Port, Username, and Password can be obtained from the server configuration.
   • Search Base is the Base path from where the Users and groups can be fetched.

   example: CN=Users,DC=ldapstest,DC=local. Here, DC is the Domain Component and CN is the Component Name.

   

4. Enter the Server Address (IP/DNS), Port, Username, Password, Search Base, and Certificate (In case of a secured port).
   • Server Address, Port, Username, and Password can be obtained from the server configuration.
   • Search Base is the Base path from where the Users and groups can be fetched.

   example: CN=Users,DC=ldapstest,DC=local. Here, DC is the Domain Component and CN is the Component Name.

5. A certificate can also be obtained from the server administrator.
6. Click Next. Select the Entity from the Entity dropdown. The Entity fields can be created from the Schema Editor page, or using the + Add Field option from the field dropdown. Provide the field mapping. For the suggested mappings, refer to the Mappings section.
   
7. Click Save.
8. You’ll be able to see the LDAP plugin in Risk Exchange > Plugins.
   

Add a Risk Exchange Business Rule for LDAP

1. In Risk Exchange, go to Business Rules.
2. Click Create New Rule in the top right corner.
3. Enter a Rule Name. Select the Entity for the Fields you configured for the LDAP plugin, and configure the query based on your requirements. This example fetches all the Users fetched from the LDAP plugin.
   
4. Click Save. Here are some examples of Business Rules that can be created.
   

Add Risk Exchange Actions for LDAP

The LDAP plugin supports these action types:

1. No Action: No action will be performed for this action. Users can generate UBA alerts in Ticket Orchestrator by using this action, and enabling the Generate Alerts toggle.
2. Add to Group: This action adds users to a selected group on LDAP.
3. Remove from Group: This action removes users from the selected group on LDAP.

Add to Group

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your configured plugin Configuration.
3. For Actions, select Add to Group.
4. In the Action Parameters, select Source and Email Address if users need to filter out users using business rules, or provide a static email.
5. In the Groups dropdown, select the Static option from the left dropdown list, and then select the existing group for which you want to add Users. Or select Create new group to create a new group, and add Users to it on the LDAP plugin. Multiple groups can be selected.
6. In the New Group Name dropdown, provide the name of the new group if you have selected Create new group in the Groups dropdown.
7. In the Remove From All Other Groups parameter, select Static from the left dropdown, and then select Yes or No depending on the use case. If Yes is selected, then the user will be added to selected groups and removed from all other groups.
8. Enable the Require Approval toggle if Approval is needed before performing action on the users.
   
9. Click Save.

Remove from Group

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your configured plugin Configuration.
3. For Actions, select Remove from Group.
4. In the Action Parameters, select Source and Email Address if users need to filter out users using business rules, or provide a static email.
5. In the Groups dropdown, select the Static option from the left dropdown list, and then select the existing group for which you want to add Users. Or select Create new group to create a new group, and add Users to it on the LDAP plugin. Multiple groups can be selected.
6. Enable the Require Approval toggle if Approval is needed before performing action on the users.
7. Click Save.

No Action

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your configured plugin Configuration.
3. For Actions, select No actions.
4. Enable the Generate Alert toggle to generate alerts in the Ticket Orchestrator module.
5. Enable the Require Approval toggle if Approval is needed before performing action on the users.
   
6. Click Save.

Validate the LDAP Plugin

Validate on Cloud Exchange

To validate the pulling of users from LDAP, go to Logging and filter the logs based on configuration name. Example: message Like “CRE LDAP”.

To verify the pulled records stored in Cloud Exchange, go to Risk Exchange > Records. Select the same entity for which the LDAP plugin is configured.

To validate the Action workflow:

Add to Group

Go to Logging to check logs, and it can be seen that the group has been created successfully, and the User has been added to the group successfully.

Remove from Group

Go to Logging to check logs, and it can be seen that the User has been removed from the group successfully.

Validate on LDAP

To verify the users available on LDAP, go to the Search Base Path configured in the plugin.
To verify the user added/removed to a group on LDAP, follow these steps:

1. Open Server Manager in your LDAP server
2. Click Tools and open the Active Directory Administrative Center by selecting it in the dropdown menu.
3. Open the Search Base path that you provided in the Search Base while configuring the LDAP plugin.
   
4. Here you’ll be able to see the group that you selected in performing actions.
   

If the Add to group action is executed, then New users added will be shown in the Members page of their respective group.

For the Remove from the group action, the users removed will be removed from the Members page of their respective group.

Troubleshooting the LDAP Plugin

Unable to configure the CRE LDAP plugin.

If you are unable to configure the CRE LDAP plugin, it could be due to one of these reasons:

• Provided Incorrect Server Address, Port, LDAP Server Username, LDAP Server Password, Search Base, or LDAP Certificate.
• Provided users don’t have sufficient permissions.

To resolve these issues, follow these steps:

1. To get the Search Base Path, follow the steps in the Get a Search Base Path section.
2. To provide proper permissions to the configuration parameter, follow the steps in the Provide permissions to a user section.

Unable to pull users from LDAP

If you are unable to pull Users from the LDAP plugin, it could be due to one of these reasons:

• No Users present on the LDAP Search Path provided in the plugin.
• An error is received while pulling Users from the platform.
• Mapping is not added while configuring the plugin in the entity source page.

To resolve these issues, follow these steps:

1. Check on the LDAP Search Base path on the platform if Users exist or not. Check the steps available in the Validate on LDAP section.
2. If any error occurred in between the pulling of users, if would be captured in logs.
3. Check if the permissions for the users are modified on the platform.
4. Make sure that the mapping is added and the User Principal Name field is mapped while configuring the plugin.

Unable to perform action on the Users

If you are unable to perform action on the User, it could be due to one of these reasons:

• Insufficient permission was provided for the action.
• Receiving an error while performing an action.
• Users are not present on the LDAP Platform.
• The Require Approval toggle button was enabled while configuring the Action, and the request is not approved.

To resolve these issues, follow these steps:

1. Insufficient permission was provided for the action.
2. Go to the LDAP Platform, and verify if the user for which an action needs to be performed is present or not.
3. Verify that the group for which the action is needed to be performed exists on the platform.
4. Go to Action Logs, select the logs that you want to approve the requests for, and click on the Approve icon, or disable the Require Approval toggle on the configured action, and then perform the action again.