Active Directory V2
LAST UPDATED: OCTOBER 3, 2025
Overview
Active Directory is a directory service from Microsoft that allows network administrators to manage users, domains, and objects within a network. D3's integration with Active Directory can perform operations such as disabling/enabling user accounts, resetting passwords, retrieving user and computer information, listing users, and more.
D3 SOAR is providing REST operations to function with Active Directory V2.
Active Directory V2 is available for use in:
D3 SOAR | V16.2+ |
Category | Identity & Access Management |
Deployment Options |
Known Limitations
A few known limitations of Active Directory are listed below.
A domain controller can create slightly less than 2.15 billion objects during its lifetime.
Users, groups, and computer accounts (security principals) can be members of a maximum of approximately 1,015 groups.
A limit of 999 Group Policy Objects (GPOs) can be applied to a user account or a computer account.
Avoid performing more than 5,000 operations per LDAP transaction when writing scripts or applications or an LDAP transaction.
Active Directory does not support Microsoft Entra ID Protection.
Refer to Microsoft Active Directory: The Ultimate AD FAQ - JumpCloud for more information.
Connection
To connect to Active Directory V2 from D3 SOAR, follow this part to collect the required information below:
Parameter | Description | Example |
Server Address | The server URL with a port number. Use port 636 for LDAPS. By default, the port is 389 (LDAP). For LDAPS, append the port number to the server address after a colon (:). | ***.***.***.***:*** |
Domain Name | The Active Directory domain name. | *****.***** |
User Logon Name | The logon name of the Active Directory user account used to establish the connection. The recommended format is the User Principal Name (UPN), which follows an email address structure. | Administrator |
Password | The Active Directory user password used for connection. | ***** |
Permission Requirements
Each endpoint in the Active Directory V2 API requires a certain permission scope (Active Directory security group). The following are required scopes for the commands in this integration:
Command | Required Permission |
Add Users to Groups | Domain Users |
Disable AD User Accounts | Account Operators |
Enable AD User Accounts | |
Find Users | Domain Users |
Get Computers | |
Get User Attribute Fields | |
Get User Logon and Logoff Information | Event Log Readers |
Get Users by Group | Domain Users |
Get Users by Username | |
List Computers | |
List Groups | |
List Users | |
Remove Users From Groups | |
Reset User Password |
|
Update User Attributes | Domain Users |
Update Users | |
Test Connection |
READER NOTE
When a user is created, the default assigned role is Domain Users, which provides the minimum permissions. Additional permissions may be required to run certain commands. For instructions on granting permissions, refer to Modifying a User (Granting Permissions and Modifying Account Options).
Configuring Active Directory V2 to Work with D3 SOAR
To connect with D3, users must obtain the domain name, user logon name, and configure the required permissions, which may include creating a new user. It is recommended that users with administrative permissions perform these configuration steps to avoid disruptions.
Refer to Active Directory security groups to review Active Directory security groups and the permissions associated with them.
Identifying the Domain Name
In the Azure Directory Users and Computers console, locate the domain name in the left navigation panel.
Enter this domain name in the Domain Name field when setting up the D3 connection. Refer to Step 3.i.2 in Configuring D3 SOAR to Work with Active Directory V2.
Creating a User
Navigate to the Users folder within the domain, right-click in the right pane, and choose New > User.
Enter the user's first name, full name, and User logon name, then click the Next button.
The User logon name should be input into the User Logon Name field when configuring the integration connection in D3. Refer to 3.i.3 in Configuring D3 SOAR to Work with Active Directory V2.
Enter and confirm the user's password, configure any additional attributes, then click the Next button.
Refer to 3.i.4 in Configuring D3 SOAR to Work with Active Directory V2.
Click the Finish button.
.png?inst-v=9d16beaf-952a-4ae4-8fe8-e35f7a3745da)
Modifying a User (Granting Permissions and Modifying Account Options)
Navigate to the Users folder, right-click on the user to modify, then select the Properties option.
Select the Member Of tab, then click the Add button.
Enter the desired permissions in the Enter the object names to select field, click the Check Names button, then save the configuration.
Refer to Permission Requirements for the minimum permission scope required for each command.
Click the Apply button to apply the changes.
Select the Account tab, configure the account options as desired, then click the Apply and OK buttons.
Configuring for the Reset Password Command
To run the Reset Password command for a specific user, that user must be granted the required permissions. Follow the steps below.
On Active Directory, select View > Advanced Features.
Navigate to the Users folder, right click on the desired user, then select the Properties option.
Configure the permissions and apply.
Open the Security tab.
Click the desired user.
Check the Allow checkboxes for Change password and Reset password.
Click the Apply button to save the changes.
Configuring D3 SOAR to Work with Active Directory V2
Log in to D3 SOAR.
Find the Active Directory V2 integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Active Directory V2 in the search box to find the integration, then click it to select it.
Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Active Directory V2.
Connection Name: The desired name for the connection.
Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): The description for the connection.
Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: The checkbox that enables the connection to be used when selected.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input the Server Address.
2. Input the Domain Name. Refer to Identifying the Domain Name.
3. Input the account Username. See step 2 of Creating a User.
4. Input the account Password. See step 3 of Creating a User.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
Test the connection.
Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Commands
Active Directory V2 includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.
READER NOTE
Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Active Directory V2 to Work with D3 SOAR for details.
Note for Time-related parameters
The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.
The selected time format will now be visible when configuring Date/Time command input parameters.
Add Users to Groups
Adds the specified Active Directory user accounts to the specified groups.
READER NOTE
Group Names is a required parameter to run this command.
Run the List Groups command to obtain the Group Names. Group Names can be found in the raw data at the path $.results[*].GroupName.
Usernames and Login Names are optional parameters to run this command.
Run the List Users or Find Users commands to obtain the Usernames. Usernames can be found in the raw data at the path $[*].User for both commands.
Run the List Users or Find Users commands to obtain the Login Names. Login Names can be found in the raw data at the path $[*].LoginName for both commands.
One of the Usernames or Login Names parameters must be specified. If both are provided, Usernames are omitted.
Changes may not appear in the Active Directory application immediately after running this command. Refresh the AD page to view the updates.
This command requires the Domain Users permission. Without this permission, the command may appear successful, but the users will not be added and their status will remain unchanged upon refresh.
Input
Input Parameter | Required/Optional | Description | Example |
Usernames | Optional | The full usernames of the Active Directory user accounts to add to the groups. Usernames can be obtained using the List Users or Find Users commands. One of the Usernames or Login Names parameters must be specified. If both are provided, Usernames are omitted. |
JSON
|
Group Names | Required | The names of the groups to which the Active Directory user accounts are added. Group names can be obtained using the List Groups command. |
JSON
|
Login Names | Optional | The login names (SamAccountNames) of the Active Directory user accounts to add to the groups. Login names can be obtained using the List Users or Find Users commands. One of the Usernames or Login Names parameters must be specified. If both are provided, Usernames are omitted. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Add Users to Groups failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The group 'group' is not found in AD. |
Error Sample Data Add Users to Groups failed. Status Code: 404. Message: The group 'group' is not found in AD. |
Disable AD User Accounts
Disables the specified Active Directory user accounts.
READER NOTE
Login Names is a required parameter to run this command.
Run the List Users or Find Users command to obtain the Login Names. Login Names can be found in the raw data at $[*].LoginName for both commands.
Changes may not appear in the Active Directory application immediately after running this command. Refresh the AD page to view the updates.
This command requires the Account Operators permission. Without this permission, the command may appear successful, but the user will not be disabled and their status will remain unchanged upon refresh.
Disabling the account used by the current connection will prevent other commands from running.
Input
Input Parameter | Required/Optional | Description | Example |
Login Names | Required | The login names of the AD user accounts to disable. Login names can be obtained using the List Users or Find Users commands. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Disable AD User Accounts failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user is not found in AD. |
Error Sample Data Disable AD User Accounts failed. Status Code: 404. Message: The user is not found in AD. |
Enable AD User Accounts
Enables the specified Active Directory user accounts.
READER NOTE
Login Names is a required parameter to run this command.
Run the List Users or Find Users command to obtain the Login Names. Login Names can be found in the raw data at $[*].LoginName for both commands.
Changes may not appear in the Active Directory application immediately after running this command. Refresh the AD page to view the updates.
This command requires the Account Operators permission. Without this permission, the command may appear successful, but the user will not be enabled and their status will remain unchanged upon refresh.
Input
Input Parameter | Required/Optional | Description | Example |
Login Names | Required | The login names of the AD user accounts to enable. Login names can be obtained using the List Users or Find Users commands. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Enable AD User Accounts failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user is not found in AD. |
Error Sample Data Enable AD User Accounts failed. Status Code: 404. Message: The user is not found in AD. |
Find Users
Returns detailed user information based on the specified query criteria.
READER NOTE
All input parameters are optional. It is recommended to specify at least one parameter to narrow the results. Multiple parameters can be specified simultaneously, and they are applied using "AND" logic
Input
Input Parameter | Required/Optional | Description | Example |
First Name | Optional | The full or partial first name of the user. Use an asterisk (*) for partial matches. For instance:
| *angy* |
Last Name | Optional | The full or partial last name of the user. Use an asterisk (*) for partial matches. For instance:
| Gils* |
Login Name | Optional | The full or partial login name of the user. Use an asterisk (*) for partial matches. For instance:
| *user1* |
Email Address | Optional | The full or partial email address of the user. Use an asterisk (*) for partial matches. For instance:
| *support@d3soar.com |
Query Count | Optional | The maximum number of users to return. By default, up to 1,000 matching users are returned. Use additional filters to refine results. To query more than 1000 users, use the List Users command. | 10 |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Find Users failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Users not found. |
Error Sample Data Find Users failed. Status Code: 404. Message: Users not found. |
Get Computers
Retrieves detailed information about the specified Active Directory computers.
READER NOTE
Computer Names is a required parameter to run this command.
Run the List Computers command to obtain the Computer Names. Computer Names can be found in the raw data at the path $[*].ComputerName.
Input
Input Parameter | Required/Optional | Description | Example |
Computer Names | Required | The names of the Active Directory computers to retrieve. Computer names can be obtained using the List Computers command. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Computers failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The hostname is not found in AD. |
Error Sample Data Get Computers failed. Status Code: 404. Message: The hostname is not found in AD. |
Get User Attribute Fields
Retrieves the attribute fields of the specified Active Directory user accounts.
READER NOTE
Login Names is a required parameter to run this command.
Run the List Users or Find Users command to obtain the Login Names. Login Names can be found in the raw data at $[*].LoginName for both commands.
Input
Input Parameter | Required/Optional | Description | Example |
Login Names | Required | The login names of the Active Directory user accounts for which to retrieve attribute fields. Login names can be obtained using the List Users or Find Users commands. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get User Attribute Fields failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user 'xxx' is not found in AD. |
Error Sample Data Get User Attribute Fields failed. Status Code: 404. Message: The user 'xxx' is not found in AD. |
Get User Logon and Logoff Information
Returns the logon and logoff times of the Azure Directory users on the specified hosts.
READER NOTE
Usernames and Host Names are optional parameters to run this command.
Run the List Users or Find Users command to obtain the Usernames. Usernames can be found in the raw data at $[*].User for both commands.
Run the List Computers command to obtain the Host Names. Host Names can be found in the raw data at the path $[*].ComputerName.
Logon and logoff information is available in the Event Viewer. This command retrieves only user logon and logoff information with the task category set to Other Logon/Logoff Events.
The following example shows a logon and logoff event log for an administrator in the Event Viewer.
Input
Input Parameter | Required/Optional | Description | Example |
Usernames | Optional | The usernames of the Active Directory user accounts for which to retrieve logon and logoff times. Usernames can be obtained using the List Users or Find Users commands. At least one of the Usernames or Host Names parameters must be specified. |
JSON
|
Host Names | Optional | The names of the hosts for which to retrieve logon and logoff information of users. Host Names can be obtained using the List Computers command. At least one of the Usernames or Host Names parameters must be specified. |
JSON
|
Start Time | Optional | The start time of the range to filter returned logs (in UTC). | 2023-06-13 00:00 |
End Time | Optional | The end time of the range to filter returned logs (in UTC). | 2023-06-14 00:00 |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get User Logon and Logoff Information failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid server address. |
Error Sample Data Get User Logon and Logoff Information failed. Status Code: 403. Message: Invalid server address. |
Get Users by Group
Retrieves a list of Active Directory users from the specified group.
READER NOTE
Group Name is a required parameter to run this command.
Run the List Groups command to obtain the Group Name. Group Names can be found in the raw data at the path $.results[*].GroupName.
If the command appears successful but returns no results, the group is likely a system group; search for a custom group instead.
Input
Input Parameter | Required/Optional | Description | Example |
Group Name | Required | The name of the group for which to return users. Group Name can be obtained using the List Groups command. | Discovery Management |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Users by Group failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The Group Name is not found in AD. |
Error Sample Data Get Users by Group failed. Status Code: 404. Message: The Group Name is not found in AD. |
Get Users by Username
Retrieves detailed information about the specified Active Directory user accounts.
READER NOTE
Login Names is a required parameter to run this command.
Run the List Users or Find Users command to obtain the Login Names. Login Names can be found in the raw data at $[*].LoginName for both commands.
Input
Input Parameter | Required/Optional | Description | Example |
Login Names | Required | The login names of the Active Directory user accounts to retrieve. Login names can be obtained using the List Users or Find Users commands. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Users by Username failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user is not found in AD. |
Error Sample Data Get Users by Username failed. Status Code: 404. Message: The user is not found in AD. |
List Computers
Retrieves all computers from Active Directory.
READER NOTE
If the command runs successfully but returns no results, the specified search value might not exist; review the input filters.
The Next Page Cookie value can be found in the Key Fields returned by this command at $.NextPageCookie.
Input
Input Parameter | Required/Optional | Description | Example |
Computer Name | Optional | The full or partial computer name. Use an asterisk (*) for partial matches. For instance:
| *cyberlab* |
Operating System | Optional | The full or partial operating system name. Use an asterisk (*) for partial matches. For instance:
| windows 11* |
Other Filters | Optional | Additional filters used to narrow returned computers. |
JSON
|
Query Count | Optional | The maximum number of computers to return. By default, up to 1,000 matching computers are returned. A large count may cause performance issues; use a moderate number and the Next Page Cookie parameter to retrieve remaining results. | 10 |
Next Page Cookie | Optional | The cookie string used to retrieve remaining computers not returned in the last command execution. Obtain this value from the NextPageCookie field in the command’s Key Fields output. A non-empty value indicates more data is available. This cookie is typically maintained by AD for several minutes, but the duration may vary based on server configuration and load. An expired or unmaintained cookie will result in a query error. | AQAA*****AA== |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Computers failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid server address. |
Error Sample Data List Computers failed. Status Code: 401. Message: Invalid server address. |
List Groups
Retrieves all groups from Active Directory.
READER NOTE
The Next Page Cookie value can be found in the Key Fields returned by this command at $.NextPageCookie.
Input
Input Parameter | Required/Optional | Description | Example |
Group Name | Optional | The full or partial group name. Use an asterisk (*) for partial matches. For instance:
| *security* |
Query Count | Optional | The maximum number of groups to return. By default, up to 1,000 matching groups are returned. A large count may cause performance issues; use a moderate number and the Next Page Cookie parameter to retrieve remaining results. | 10 |
Next Page Cookie | Optional | The cookie string used to retrieve remaining groups not returned in the last command execution. Obtain this value from the NextPageCookie field in the command’s Key Fields output. A non-empty value indicates more data is available. This cookie is typically maintained by AD for several minutes, but the duration may vary based on server configuration and load. An expired or unmaintained cookie will result in a query error. | AQAA*****AA== |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Groups failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid server address. |
Error Sample Data List Groups failed. Status Code: 401. Message: Invalid server address. |
List Users
Retrieves all users from Active Directory.
READER NOTE
The Next Page Cookie value can be found in the Key Fields returned by this command at $.NextPageCookie.
Input
Input Parameter | Required/Optional | Description | Example |
Show Active Users Only | Optional | The option to return only active users when set to True. By default, both active and inactive users are returned. | False |
Query Count | Optional | The maximum number of users to return. By default, up to 1,000 matching users are returned. A large count may cause performance issues; use a moderate number and the Next Page Cookie parameter to retrieve remaining results. | 10 |
Next Page Cookie | Optional | The cookie string used to retrieve remaining users not returned in the last command execution. Obtain this value from the NextPageCookie field in the command’s Key Fields output. A non-empty value indicates more data is available. This cookie is typically maintained by AD for several minutes, but the duration may vary based on server configuration and load. An expired or unmaintained cookie will result in a query error. | AQAA*****AA== |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Users failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid server address. |
Error Sample Data List Users failed. Status Code: 401. Message: Invalid server address. |
Remove Users From Groups
Removes the specified Active Directory user accounts from the specified groups.
READER NOTE
Group Names is a required parameter to run this command.
Run the List Groups command to obtain the Group Names. Group Names can be found in the raw data at the path $.results[*].GroupName.
Usernames and Login Names are optional parameters to run this command.
Run the List Users or Find Users commands to obtain the Usernames. Usernames can be found in the raw data at the path $[*].User for both commands.
Run the List Users or Find Users commands to obtain the Login Names. Login Names can be found in the raw data at the path $[*].LoginName for both commands.
One of the Usernames or Login Names parameters must be specified. If both are provided, Usernames are omitted.
An error occurs if the user account is not a member of the specified group. To prevent this, use the List Groups command to identify the group, confirm membership with the Get Users by Group command, and then run this command with the correct group–user pair.
Input
Input Parameter | Required/Optional | Description | Example |
Usernames | Optional | The usernames of the Active Directory user accounts to remove from the groups. Usernames can be obtained using the List Users or Find Users commands. One of the Usernames or Login Names parameters must be specified. If both are provided, Usernames are omitted. |
JSON
|
Group Names | Required | The names of the groups from which the Active Directory user accounts are removed. Group names can be obtained using the List Groups command. |
JSON
|
Login Names | Optional | The login names (SamAccountNames) of the Active Directory user accounts to remove from the groups. Login names can be obtained using the List Users or Find Users commands. One of the Usernames or Login Names parameters must be specified. If both are provided, Usernames are omitted. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Remove Users From Groups failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The group 'xxx' is not found in AD. |
Error Sample Data Remove Users From Groups failed. Status Code: 404. Message: The group 'xxx' is not found in AD. |
Reset User Password
Resets the specified Active Directory user’s password. The password reset requires an SSL (LDAPS) connection using port 636.
READER NOTE
The Domain Admin role, along with the Reset password and Change password permissions, are required to run this command. Refer to Configuring for the Reset Password Command.
Login Name is a required parameter to run this command.
Run the List Users or Find Users command to obtain the Login Name. Login Names can be found in the raw data at the path $[*].LoginName for both commands.
If the "LDAPStartTLSError: startTLS failed - unavailable" error occurs, configure LDAPS on the Windows Server. A step-by-step guide for setting up LDAPS is available at Step by Step Guide to Setup LDAPS on Windows Server | Microsoft Community Hub. Once LDAPS is configured, the error should no longer occur.
Input
Input Parameter | Required/Optional | Description | Example |
Login Name | Required | The login name of the Active Directory user account whose password will be reset. Login names can be obtained using the List Users or Find Users commands. | user1 |
New Password | Required | The new password. The password must comply with the Active Directory server’s password policy. Review the policy under Local Computer Policy > Computer Configuration > Windows Settings > Security Settings > Account Policies > Password Policy. | ***** |
Confirm Password | Required | The new password re-entered for confirmation. | ***** |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Reset User Password failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user is not found in AD. |
Error Sample Data Reset User Password failed. Status Code: 404. Message: The user is not found in AD. |
Update User Attributes
Updates the specified attribute values for the specified Active Directory user accounts. This command updates a single attribute. To update multiple attributes, use the Update Users command.
READER NOTE
Login Names and Attribute Name are required parameters to run this command.
Run the List Users or Find Users command to obtain the Login Names. Login Names can be found in the raw data at the path $[*].LoginName for both commands.
Run the Get User Attribute Fields command to obtain the Attribute Name. Available Attribute Names are contained within the attributes object in the raw data at the path $[*].attributes. For example, the attributes object may include arrays such as countryCode and displayName.
Input
Input Parameter | Required/Optional | Description | Example |
Login Names | Required | The login names of the Active Directory user accounts whose attributes will be updated. Login names can be obtained using the List Users or Find Users commands. |
JSON
|
Attribute Name | Required | The attribute name of the Active Directory user accounts to update. Available attribute names can be obtained using the Get User Attribute Fields command. Refer to Active Directory User Object: An Introduction for the Active Directory attribute list. | displayName |
Attribute Value | Required | The attribute value of the Active Directory user accounts to update. | user1_NEW_DisplayName |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Update User Attributes failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user 'xxx' is not found in AD. |
Error Sample Data Update User Attributes failed. Status Code: 404. Message: The user 'xxx' is not found in AD. |
Update Users
Updates the specified attribute values of the specified Active Directory user accounts.
READER NOTE
Login Names and Attribute Name are required parameters to run this command.
Run the List Users or Find Users command to obtain the Login Names. Login Names can be found in the raw data at the path $[*].LoginName for both commands.
Run the Get User Attribute Fields command to obtain the Attribute Name. Available Attribute Names are contained within the attributes object in the raw data at the path $[*].attributes. For example, the attributes object may include arrays such as countryCode and displayName.
Input
Input Parameter | Required/Optional | Description | Example |
Login Names | Required | The login names of the Active Directory user accounts to update. Login names can be obtained using the List Users or Find Users commands. |
JSON
|
User Attributes | Required | The key-value pairs of the attributes of the Active Directory user accounts to update. Available attribute names can be obtained using the Get User Attribute Fields command. Refer to Active Directory User Object: An Introduction for the Active Directory attribute list. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Update Users failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The user 'xxx' is not found in AD. |
Error Sample Data Update User failed. Status Code: 404. Message: The user 'xxx' is not found in AD. |
Test Connection
Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Output Type | Description | Return Data Type |
Return Data | Indicates one of the possible command execution states: Successful or Failed. The Failed state can be triggered by any of the following errors:
More details about an error can be viewed in the Error tab. | String |
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Test Connection failed. Failed to check the connector. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Active Directory V2 portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid server address. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 401. Message: Invalid server address. |