Integration with Active Directory

You can integrate KUMA with the Active Directory services that are being used in your organization.

You can configure a connection to the Active Directory catalog service over the LDAP protocol. This lets you use information from Active Directory in correlation rules for enrichment of events and alerts, and for analytics.

If you configure a connection to a domain controller server, you can use domain authorization. In this case, you will be able to bind groups of users from Active Directory to KUMA role filters. The users belonging to these groups will be able to use their domain account credentials to log in to the KUMA web interface and will obtain access to application sections based on their assigned role.

It is recommended to create these groups of users in Active Directory in advance if you want to provide such groups with the capability to complete authorization using their domain account in the KUMA web interface. An email address must be indicated in the properties of a user account in Active Directory.

Connecting over LDAP

LDAP connections are created and managed under Settings → LDAP server in the KUMA web interface. The LDAP server integration by tenant section shows the tenants for which LDAP connections were created. Tenants can be created or deleted.

If you select a tenant, the LDAP server integration window opens to show a table containing existing LDAP connections. Connections can be created or edited. In this window, you can change the frequency of queries sent to LDAP servers and set the retention period for obsolete data.

After integration is enabled, information about Active Directory accounts becomes available in the alert window, the correlation events detailed view window, and the incidents window. If you click an account name in the Related users section of the window, the Account details window opens with the data imported from Active Directory.

Data from LDAP can also be used when enriching events in collectors and in analytics.

Imported Active Directory attributes

Enabling and disabling LDAP integration

You can enable or disable all LDAP connections of the tenant at the same time, or enable and disable an LDAP connection individually.

To enable or disable all LDAP connections of a tenant:

1. In the KUMA web interface, open Settings → LDAP server and select the tenant for which you want to enable or disable all LDAP connections.

   The LDAP server integration by tenant window opens.

2. Select or clear the Disabled check box.
3. Click Save.

To enable or disable a specific LDAP connection:

1. In the KUMA web interface, open Settings → LDAP server and select the tenant for which you want to enable or disable an LDAP connection.

   The LDAP server integration window opens.

2. Select the relevant connection and either select or clear the Disabled check box in the opened window.
3. Click Save.

Adding a tenant to the LDAP server integration list

To add a tenant to the list of tenants for integration with an LDAP server:

1. Open the KUMA web interface and select Settings → LDAP server.

   The LDAP server integration by tenant window opens.

2. Click the Add tenant button.

   The LDAP server integration window is displayed.

3. In the Tenant drop-down list, select the tenant that you need to add.
4. Click Save.

The selected tenant is added to the LDAP server integration list.

To delete a tenant from the list of tenants for integration with an LDAP server:

1. Open the KUMA web interface and select Settings → LDAP server.

   The LDAP server integration by tenant window is displayed.

2. Select the check box next to the tenant that you need to delete, and click Delete.
3. Confirm deletion of the tenant.

The selected tenant is deleted from the LDAP server integration list.

Creating an LDAP server connection

To create a new LDAP connection to Active Directory:

1. In the KUMA web interface, open Settings → LDAP server.
2. Select or create a tenant for which you want to create a LDAP connection.

   The LDAP server integration by tenant window opens.

3. Click the Add connection button.

   The Connection parameters window opens.

4. Add a secret containing the account credentials for connecting to the Active Directory server. To do so:
   1. If you previously added a secret, use the Secret drop-down list to select the existing secret resource (with the credentials type).

      The selected secret can be changed by clicking on the button.

   2. If you want to create a new secret, click the button.

      The Secret window opens.

   3. In the Name (required) field, enter the name of the resource. This name can contain from 1 to 128 Unicode characters.
   4. In the User and Password (required) fields, enter the account credentials for connecting to the Active Directory server.

      You can enter the user name in one of the following formats: <user name>@<domain> or <domain><user name>.

   5. In the Description field, you can enter up to 256 Unicode characters to describe the resource.
   6. Click the Save button.
5. In the Name (required) field, enter the unique name of the LDAP connection.

   Must contain from 1 to 128 Unicode characters.

6. In the URL (required) field, enter the address of the domain controller in the format <hostname or IP address of server>:<port>.

   In case of server availability issues, you can specify multiple servers with domain controllers by separating them with commas. All of the specified servers must reside in the same domain.

7. If you want to use TLS encryption for the connection with the domain controller, select one of the following options from the Type drop-down list:
   • startTLS.

     When the

     startTLS

     Text exchange protocol enhancement that lets you create an encrypted connection (TLS or SSL) directly over an ordinary TCP connection instead of opening a separate port for the encrypted connection.

     Text exchange protocol enhancement that lets you create an encrypted connection (TLS or SSL) directly over an ordinary TCP connection instead of opening a separate port for the encrypted connection.

     method is used, first it establishes an unencrypted connection over port 389, then it sends an encryption request. If the STARTTLS command ends with an error, the connection is terminated.

     Make sure that port 389 is open. Otherwise, a connection with the domain controller will be impossible.

   • ssl.

     When using SSL, an encrypted connection is immediately established over port 636.

   • insecure.

   When using an encrypted connection, it is impossible to specify an IP address as a URL.

8. If you enabled TLS encryption at the previous step, add a TLS certificate. You must use the certificate of the certification authority that signed the LDAP server certificate. You may not use custom certificates. To add a certificate:
   1. If you previously uploaded a certificate, select it from the Certificate drop-down list.

      If no certificate was previously added, the drop-down list shows No data.

   2. If you want to upload a new certificate, click the button on the right of the Certificate list.

      The Secret window opens.

   3. In the Name field, enter the name that will be displayed in the list of certificates after the certificate is added.
   4. Click the Upload certificate file button to add the file containing the Active Directory certificate. X.509 certificate public keys in Base64 are supported.
   5. If necessary, provide any relevant information about the certificate in the Description field.
   6. Click the Save button.

   The certificate will be uploaded and displayed in the Certificate list.

9. In the Timeout in seconds field, indicate the amount of time to wait for a response from the domain controller server.

   If multiple addresses are indicated in the URL field, KUMA will wait the specified number of seconds for a response from the first server. If no response is received during that time, the program will contact the next server, and so on. If none of the indicated servers responds during the specified amount of time, the connection will be terminated with an error.

10. In the Search base (Base DN) field, enter the base distinguished name of the directory in which you need to run the search query.
11. Select the Disabled check box if you do not want to use this LDAP connection.

    This check box is cleared by default.

12. Click the Save button.

The LDAP connection to Active Directory will be created and displayed in the LDAP server integration window.

Account information from Active Directory will be requested immediately after the connection is saved, and then it will be updated at the specified frequency.

If you want to use multiple LDAP connections simultaneously for one tenant, you need to make sure that the domain controller address indicated in each of these connections is unique. Otherwise KUMA lets you enable only one of these connections. When checking the domain controller address, the program does not check whether the port is unique.

Creating a copy of an LDAP server connection

You can create an LDAP connection by copying an existing connection. In this case, all settings of the original connection are duplicated in the newly created connection.

To copy an LDAP connection:

1. In the KUMA web interface, open Settings → LDAP server and select the tenant for which you want to copy an LDAP connection.

   The LDAP server integration window opens.

2. Select the relevant connection.
3. In the opened Connection parameters window, click the Duplicate connection button.

   The New Connection window opens. The word copy will be added to the connection name.

4. If necessary, change the relevant settings.
5. Click the Save button.

The new connection is created.

If you want to use multiple LDAP connections simultaneously for one tenant, you need to make sure that the domain controller address indicated in each of these connections is unique. Otherwise KUMA lets you enable only one of these connections. When checking the domain controller address, the program does not check whether the port is unique.

Changing an LDAP server connection

To change an LDAP server connection:

1. Open the KUMA web interface and select Settings → LDAP server.

   The LDAP server integration by tenant window opens.

2. Select the tenant for which you want to change the LDAP server connection.

   The LDAP server integration window opens.

3. Click the LDAP server connection that you want to change.

   The window with the settings of the selected LDAP server connection opens.

4. Make the necessary changes to the settings.
5. Click the Save button.

The LDAP server connection is changed. Restart the KUMA services that use LDAP server data enrichment for the changes to take effect.

Changing the data update frequency

KUMA queries the LDAP server to update account data. This occurs:

• Immediately after creating a new connection.
• Immediately after changing the settings of an existing connection.
• According to a regular schedule every several hours. Every 12 hours by default.
• Whenever a user creates a task to update account data.

When querying LDAP servers, a task is created in the Task manager section of the KUMA web interface.

To change the schedule of KUMA queries to LDAP servers:

1. In the KUMA web interface, open Settings → LDAP server → LDAP server integration by tenant.
2. Select the relevant tenant.

   The LDAP server integration window opens.

3. In the Data refresh interval field, specify the required frequency in hours. The default value is 12.

The query schedule has been changed.

Changing the data storage period

Received user account data is stored in KUMA for 90 days by default if information about these accounts is no longer received from the Active Directory server. After this period, the data is deleted.

After KUMA account data is deleted, new and existing events are no longer enriched with this information. Account information will also be unavailable in alerts. If you want to view information about accounts throughout the entire period of alert storage, you must set the account data storage period to be longer than the alert storage period.

To change the storage period for the account data:

1. In the KUMA web interface, open Settings → LDAP server → LDAP server integration by tenant.
2. Select the relevant tenant.

   The LDAP server integration window opens.

3. In the Data storage time field, specify the number of days you need to store data received from the LDAP server.

The account data storage period is changed.

Starting account data update tasks

After a connection to an Active Directory server is created, tasks to obtain account data are created automatically. This occurs:

• Immediately after creating a new connection.
• Immediately after changing the settings of an existing connection.
• According to a regular schedule every several hours. Every 12 hours by default. The schedule can be changed.

Account data update tasks can be created manually. You can download data for all connections or for one connection of the required tenant.

To start an account data update task for all LDAP connections of a tenant:

1. In the KUMA web interface, open Settings → LDAP server → LDAP server integration by tenant.
2. Select the relevant tenant.

   The LDAP server integration window opens.

3. Click the Import accounts button.

A task to receive account data from the selected tenant is added to the Task manager section of the KUMA web interface.

To start an account data update task for one LDAP connection of a tenant:

1. In the KUMA web interface, open Settings → LDAP server → LDAP server integration by tenant.
2. Select the relevant tenant.

   The LDAP server integration window opens.

3. Select the relevant LDAP server connection.

   The Connection parameters window opens.

4. Click the Import accounts button.

A task to receive account data from the selected connection of the tenant is added to the Task manager section of the KUMA web interface.

Deleting an LDAP server connection

To delete LDAP connection to Active Directory:

1. In the KUMA web interface, open Settings → LDAP server and select the tenant that owns the relevant LDAP connection.

   The LDAP server integration window opens.

2. Click the LDAP connection that you want to delete and click the Delete button.
3. Confirm deletion of the connection.

The LDAP connection to Active Directory will be deleted.

Authorization with domain accounts

To enable users to complete authorization in the KUMA web interface using their own domain account credentials, you must complete the following configuration steps.

1. Enable domain authorization if it is disabled.

   Domain authorization is enabled by default, but a connection to the domain is not yet configured.

2. Configure a connection to the domain controller.

   You can connect only to one domain.

3. Add groups of user roles.

   You can specify an Active Directory group for each KUMA role. After completing authorization using their own domain accounts, users from this group will obtain access to the KUMA web interface in accordance with their defined role.

   The program checks whether the Active Directory user group matches the specified filter according to the following order of roles in the KUMA web interface: operator → analyst → tenant administrator → general administrator. Upon the first match, the program assigns a role to the user and does not check any further. If a user matches two groups in the same tenant, the role with the least privileges will be used. If multiple groups are matched for different tenants, the user will be assigned the specified role in each tenant.

If you completed all the configuration steps but the user is unable to use their domain account for authorization in the KUMA web interface, it is recommended to check the configuration for the following issues:

• An email address is not indicated in the properties of the user account in Active Directory. If this is the case, an error message is displayed during the user's first authorization attempt and a KUMA account will not be created.
• There is already an existing local KUMA account with the email address indicated in the domain account properties. If this is the case, the user will see an error message when attempting authorization with the domain account.
• Domain authorization is disabled in the KUMA settings.
• An error was made when entering the group of roles.
• The domain user name contains a space.

Enabling and disabling domain authorization

Domain authorization is enabled by default, but a connection to the Active Directory domain is not yet configured. If you want to temporarily pause domain authorization after configuring a connection, you can disable it in the KUMA web interface without deleting the previously defined values of settings. If necessary, you will be able to enable authorization again at any time.

To enable or disable domain authorization of users in the KUMA web interface:

1. In the program web interface, select Settings → Domain authorization.
2. Do one of the following:
   • If you want to disable domain authorization, select the Disabled check box in the upper part of the workspace.
   • If you want to enable domain authorization, clear the Disabled check box in the upper part of the workspace.
3. Click the Save button.

Domain authorization will be enabled or disabled based on your selection.

Configuring a connection to the domain controller

You can connect only to one Active Directory domain. To do so, you must configure a connection to the domain controller.

To configure a connection to an Active Directory domain controller.

1. In the program web interface, select Settings → Domain authorization.
2. In the Connection settings block, in the Base DN field, enter the DistinguishedName of the root record to search for access groups in the Active Directory catalog service.
3. In the URL field, indicate the address of the domain controller in the format <hostname or IP address of server>:<port>.

   In case of server availability issues, you can specify multiple servers with domain controllers by separating them with commas. All of the specified servers must reside in the same domain.

4. If you want to use TLS encryption for the connection with the domain controller, select one of the following options from the TLS mode drop-down list:
   • startTLS.

     When the startTLS method is used, first it establishes an unencrypted connection over port 389, then it sends an encryption request. If the STARTTLS command ends with an error, the connection is terminated.

     Make sure that port 389 is open. Otherwise, a connection with the domain controller will be impossible.

   • ssl.

     When using SSL, an encrypted connection is immediately established over port 636.

   • insecure.

   When using an encrypted connection, it is impossible to specify an IP address as a URL.

5. If you enabled TLS encryption at the previous step, add a TLS certificate:
   • If you previously uploaded a certificate, select it from the Secret drop-down list.

     If no certificate was previously added, the drop-down list shows No data.

   • If you want to upload a new certificate, click the button on the right of the Secret list. In the opened window, in the Name field, enter the name that will be displayed in the list of certificates after the certificate is added. Add the file containing the Active Directory certificate (X.509 certificate public keys in Base64 are supported) by clicking the Upload certificate file button. Click the Save button.

     The certificate will be uploaded and displayed in the Secret list.

6. In the Timeout in seconds field, indicate the amount of time to wait for a response from the domain controller server.

   If multiple addresses are indicated in the URL field, KUMA will wait the specified number of seconds for a response from the first server. If no response is received during that time, the program will contact the next server, and so on. If none of the indicated servers responds during the specified amount of time, the connection will be terminated with an error.

7. If you want to configure domain authorization for a user with the KUMA general administrator role, specify the DistinguishedName of the Active Directory group containing the user in the General administrators group field.

   If a user matches two groups in the same tenant, the role with the least privileges will be used.

   Filter input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

8. Click the Save button.

A connection with the Active Directory domain controller is now configured. For domain authorization to work, you must also add group of KUMA user roles.

You can also check the connection for the previously entered domain controller connection settings.

To check the connection to the domain controller:

1. In the program web interface, select Settings → Domain authorization.
2. In the Test connection settings block, select the relevant secret in the User credentials field.

   If necessary, you can create a new secret by clicking the button or change the settings of an existing secret by clicking the button.

3. Click Test.

A pop-up notification is displayed with the test results. The pop-up notification shows the following message: Connection established. If a connection could not be established, the reason for the lack of connection is displayed.

Adding groups of user roles

You can specify groups only for those roles that require configuration of domain authorization. You can leave the rest of the fields empty.

To add groups of user roles:

1. In the program web interface, select Settings → Domain authorization.
2. In the Role groups settings block, click the Add role groups button.
3. In the Tenant drop-down list, select the tenant of the users for whom you want to configure domain authorization.
4. In the fields for the following roles, specify the DistinguishedName of the Active Directory group whose users must have the capability to complete authorization with their domain accounts:
   • Operator.
   • Analyst.
   • Administrator.

   Group input example: CN=KUMA team,OU=Groups,OU=Clients,DC=test,DC=domain.

   You can specify only one Active Directory group for each role. If you need to specify multiple groups, you must repeat steps 2–4 for each group while indicating the same tenant.

5. If necessary, repeat steps 2–4 for each tenant for which you want to configure domain authorization with operator, analyst, and tenant administrator roles.
6. Click the Save button.

The groups of user roles will be added. The defined settings will be applied the next time the user logs in to the KUMA web interface.

After the first authorization of the user, information about them is displayed under Settings → Users. The Login and Password fields received from Active Directory will be unavailable for editing. The user role will also be unavailable for editing. To edit a role, you will have to change the user role groups. Changes to a role are applied after the next authorization of the user. The user will continue to operate under the old role until the current session expires.

If the user name or email address is changed in the Active Directory account properties, these changes will need to be manually entered into the KUMA account.