Active Directory Query v2
Use the Active Directory Query integration to access and manage Active Directory objects (users, contacts, and computers) and run AD queries.
This integration can be used along with our Identity Lifecycle Management premium pack. For more information, please refer to the Identity Lifecycle Management article.
#
Use Cases#
Query for Active Directory objects- Use the
!ad-search
command to run a query for Active Directory objects (users, contacts, computers, and so on). This command enables you to determine which data fields should be returned for the objects.
#
Manage users and contactsThe integration enables you to create, update, and delete users and contacts in Active Directory using the following commands:
ad-create-user
ad-create-contact
ad-update-user
ad-update-contact
ad-delete-user
(to delete both users and contacts)
Add or remove users from groups using the following commands:
ad-add-to-group
ad-remove-from-group
Enable or disable a user account using the following commands:
ad-enable-account
ad-disable-user-account
#
Manage Computers- Modify a computer organizational unit using the ‘ad-modify-computer-ou’ command.
- Add or remove a computer from a group using the following commands:
ad-add-to-group
ad-remove-from-group
#
IAM premium pack uses- Create or modify Active Directory users.
- Manage user accounts and their status
#
Configure Active Directory Query v2 on DemistoNavigate to Settings > Integrations > Servers & Services.
Search for Active Directory Query v2.
Click Add instance to create and configure a new integration instance.
- Name: a textual name for the integration instance.
- Server IP address (e.g., 192.168.0.1): The Server IP that should be used to access Active Directory.
- Port: Server port. If not specified, the default port is 389, or 636 for LDAPS.
- Credentials: User credentials.
- NTLM authentication: Indicates whether to use NTLM authentication.
- Base DN (for example “dc=company,dc=com”): The basic hierarchical path of objects in the active directory.
- Page size: The number of results to be returned, per page (page - response content from AD server), from a query. This may effect query run time.
- Secure Connection: Use SSL secure connection or ‘None’ (communication over clear-text).
- Trust any certificate (not secure):Select to avoid server certification validation. You may want to do this in case Cortex XSOAR cannot validate the integration server certificate (due to a missing CA certificate)
Click Test to validate the URLs, token, and connection.
#
Identity Lifecycle Management premium pack configurationThe premium ILM content pack introduces new functionality that uses both an incoming and an outgoing mapper.
- Configure the "Incoming Mapper" with the name of the incoming mapper that you're using. ILM's default mapper is "User Profile - Active Directory (Incoming)".
- Configure the "Outgoing Mapper" with the name of the outgoing mapper that you're using. ILM's default mapper is "User Profile - Active Directory (Outgoing)".
Note: As part of the configuration of the mapper, you must map a value to the OU (organizational unit) required field. To do this, create a transformer that maps a user attribute of your choice to an OU value.
To allow the integration to access the mapper from within the code, as required by the ILM pack, both mappers have to be configured in their proper respective fields and not in the "Mapper (outgoing)" dropdown list selector.
#
CommandsYou can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.
#
1. Expire a passwordExpires the password of an Active Directory user.
#
Base Commandad-expire-password
#
InputArgument Name | Description | Required |
---|---|---|
username | The username (samAccountName) of the user to modify. | Required |
base-dn | Root (e.g., DC=domain,DC=com). | Optional |
#
Context OutputThere is no context output for this command.
#
2. Create an AD userCreates a user in Active Directory.
#
Base Commandad-create-user
#
InputArgument Name | Description | Required |
---|---|---|
username | The username (samAccountName) of the user to modify. | Required |
password | The initial password to set for the user. The user will be asked to change the password after the initial login. | Required |
user-dn | The user’s DN. | Required |
display-name | The user’s display name. | Optional |
description | A description of the user or their function. | Optional |
The user’s email address. | Optional | |
telephone-number | The user’s telephone number. | Optional |
title | The user’s job title. | Optional |
custom-attributes | set basic or custom attributes of the user object. For example, custom-attributes="{\"notes\":\"a note about the contact\",\"company\":\"company name\"}" | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
3. Perform a search in Active DirectoryRuns queries in Active Directory.
For more information on the query syntax see the Microsoft documentation.
For more information on LDAP filters, see the LDAP documentation.
#
Base Commandad-search
#
InputArgument Name | Description | Required |
---|---|---|
filter | Defines search criteria in the Query Active Directory using Active Directory syntax. For example, the following query searches for all user objects, except Andy: "(&(objectCategory=person)(objectClass=user)(!(cn=andy)))". NOTE if you have special characters such as "","(",or "\" the character must be preceded by two backslashes "\". For example, to use "", type "\*". For more information about search filters, see Microsoft documentation. | Required |
base-dn | Root (e.g. DC=domain,DC=com). By default, the Base DN configured for the instance that will be used. | Required |
attributes | A CSV list of the object attributes to return, e.g., “dn,memberOf”. To get all object attributes, specify ‘ALL’. | Optional |
size-limit | The maximum number of records to return. | Optional |
time-limit | The maximum time to pull records (in seconds). | Optional |
context-output | If “no”, will not output the search results to the context. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
ActiveDirectory.Search.dn | string | The distinguished names that match the query. |
ActiveDirectory.Search | unknown | Result of the search. |
#
Command Example#
Context Example#
Human Readable Output#
Active Directory Search
dn CN=demistoadmin,CN=Users,DC=demisto,DC=int CN=Guest,CN=Users,DC=demisto,DC=int
#
4. Add an AD user or computer to a groupAdds an Active Directory user or computer to a group.
#
Base Commandad-add-to-group
#
InputArgument Name | Description | Required |
---|---|---|
username | The username of the user to add to the group. If this argument is not specified, the computer name argument must be specified. | Optional |
computer-name | The name of the computer to add to the group. If this argument is not specified, the username argument must be specified. | Optional |
group-cn | The name of the group to add to the group | Required |
base-dn | Root (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
5. Remove an AD user or computer from a groupRemoves an Active Directory user or computer from a group.
#
Base Commandad-remove-from-group
#
InputArgument Name | Description | Required |
---|---|---|
username | The name of the user to remove from the group. If this argument is not specified, the computer name argument must be specified. | Optional |
computer-name | The name of the computer to remove from the group. If this argument is not specified, the username argument must be specified. | Optional |
group-cn | The name of the group to remove the user from | Required |
base-dn | Root (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Required |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
6. Update attributes for an AD userUpdates attributes of an existing Active Directory user.
#
Base Commandad-update-user
#
InputArgument Name | Description | Required |
---|---|---|
username | The username of the account to update (sAMAccountName) | Required |
attribute-name | The name of the attribute to modify (e.g., sn, displayName, mail, etc.). | Required |
attribute-value | The value the attribute should be changed to. | Required |
base-dn | Root (e.g. DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
7. Delete an AD userDeletes an Active Directory user.
#
Base Commandad-delete-user
#
InputArgument Name | Description | Required |
---|---|---|
user-dn | The DN of the user to delete. | Required |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
8. Create an AD contactCreates an Active Directory contact.
#
Base Commandad-create-contact
#
InputArgument Name | Description | Required |
---|---|---|
contact-dn | The contact’s DN. | Required |
display-name | The contact’s display name. | Optional |
description | A short description of the contact. | Optional |
The contact’s email address. | Optional | |
telephone-number | The contact’s telephone number. | Optional |
custom-attributes | Sets basic or custom attributes of the user object. For example, custom-attributes="{\"notes\":\"a note about the contact\",\"company\":\"companyname\"}" | Optional |
title | The contact’s job title. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
9. Update attributes of an AD contactUpdates attributes of an existing Active Directory contact.
#
Base Commandad-update-contact
#
InputArgument Name | Description | Required |
---|---|---|
contact-dn | The contact’s DN. | Required |
attribute-name | The name of the attribute to update. | Required |
attribute-value | The attribute value to update. | Required |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
10. Disable an AD user accountDisables an Active Directory user account.
#
Base Commandad-disable-account
#
InputArgument Name | Description | Required |
---|---|---|
username | The username of the account to disable (sAMAccountName). | Required |
base-dn | Root (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
11. Enable an AD user accountEnables a previously disabled Active Directory account.
#
Base Commandad-enable-account
#
InputArgument Name | Description | Required |
---|---|---|
username | The username of the account to enable (sAMAccountName). | Required |
base-dn | Root (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
12. Unlock an AD user accountUnlocks a previously locked Active Directory user account.
#
Base Commandad-unlock-account
#
InputArgument Name | Description | Required |
---|---|---|
username | The username of the account to unlock (sAMAccountName). | Required |
base-dn | Root (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
13. Set a new password for an AD user accountSets a new password for an Active Directory user. This command requires a secure connection (SSL,TLS).
#
Base Commandad-set-new-password
#
InputArgument Name | Description | Required |
---|---|---|
username | The username of the account to set a new password for. | Required |
password | The new password to set for the user. | Required |
base-dn | Root (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance will be used. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Human Readable Output#
14. Modify the computer organizational unit in a domainModifies the computer organizational unit within a domain.
#
Base Commandad-modify-computer-ou
#
InputArgument Name | Description | Required |
---|---|---|
computer-name | The name of the computer to modify. | Required |
full-superior-dn | Superior DN, e.g., OU=computers,DC=domain,DC=com (The specified domain must be the same as the current computer domain). | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example#
Context OutputThere is no context output for this command.
#
Human Readable Output#
15. Get information for an AD user accountRetrieves detailed information about a user account. The user can be specified by name, email address, or as an Active Directory Distinguished Name (DN). If no filter is specified, all users are returned.
#
Base Commandad-get-user
#
InputArgument Name | Description | Required |
---|---|---|
dn | The Distinguished Name of the user to get information for. | Optional |
name | The name of the user to get information for. | Optional |
attributes | Include these AD attributes of the resulting objects in addition to the default attributes. | Optional |
custom-field-type | Query users by this custom field type. | Optional |
custom-field-data | Query users by this custom field data (relevant only if the custom-field-type argument is provided). | Optional |
username | Query users by the samAccountName attribute | Optional |
limit | Maximum number of objects to return (default is 20). | Optional |
Query by the user’s email address. | Optional | |
user-account-control-out | Include verbose translation for UserAccountControl flags. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
ActiveDirectory.Users.dn | string | The user’s distinguished name |
ActiveDirectory.Users.displayName | string | The user’s display name |
ActiveDirectory.Users.name | string | The user’s common name |
ActiveDirectory.Users.sAMAccountName | string | The user’s sAMAccountName |
ActiveDirectory.Users.userAccountControl | number | The user’s account control flag |
ActiveDirectory.Users.mail | string | The user’s email address |
ActiveDirectory.Users.manager | string | The user’s manager |
ActiveDirectory.Users.memberOf | string | Groups the user is member of |
Account.DisplayName | string | The user’s display name |
Account.Groups | string | Groups the user is member of |
Account.Manager | string | The user’s manager |
Account.ID | string | The user’s distinguished name |
Account.Username | string | The user’s samAccountName |
Account.Email | string | The user’s email address |
#
Command Example#
Human Readable Output#
Active Directory - Get Users
dn displayName manager memberOf name sAMAccountName userAccountControl CN=demistoadmin,CN=Users,DC=demisto,DC=int demistoadmin demistoadmin@demisto.int CN=Discovery Management,OU=Microsoft Exchange Security Groups,DC=demisto,DC=int,CN=Organization Management,OU=Microsoft Exchange Security Groups,DC=demisto,DC=int,CN=Group Policy Creator Owners,CN=Users,DC=demisto,DC=int,CN=Domain Admins,CN=Users,DC=demisto,DC=int,CN=Enterprise Admins,CN=Users,DC=demisto,DC=int,CN=Schema Admins,CN=Users,DC=demisto,DC=int,CN=Administrators,CN=Builtin,DC=demisto,DC=int demistoadmin demistoadmin 66048 CN=Guest,CN=Users,DC=demisto,DC=int CN=Guests,CN=Builtin,DC=demisto,DC=int Guest Guest 66082
#
16. Get information for a computer accountRetrieves detailed information about a computer account. The computer can be specified by name, email address, or as an Active Directory Distinguished Name (DN). If no filters are provided, all computers are returned.
#
Base Commandad-get-computer
#
InputArgument Name | Description | Required |
---|---|---|
dn | The computer’s DN. | Optional |
name | The name of the computer to get information for. | Optional |
attributes | Include these AD attributes of the resulting objects in addition to the default attributes. | Optional |
custom-field-data | Search computers by this custom field data (relevant only if the customFieldType argument is provided). | Optional |
custom-field-type | The custom field type to search by. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
ActiveDirectory.Computers.dn | unknown | The computer distinguished name |
ActiveDirectory.Computers.memberOf | unknown | Groups the computer is listed as a member |
ActiveDirectory.Computers.name | unknown | The computer name |
Endpoint.ID | unknown | The computer DN |
Endpoint.Hostname | unknown | The computer name |
Endpoint.Groups | unknown | Groups the computer is listed as a member of |
#
Command Example#
Context Example#
Human Readable Output#
Active Directory - Get Computers
dn memberOf name CN=noapc,OU=Shani,DC=demisto,DC=int CN=Exchange Servers,OU=Microsoft Exchange Security Groups,DC=demisto,DC=int noapc
#
17. Get a list of users or computers for a groupRetrieves the list of users or computers that are members of the specified group.
#
Base Commandad-get-group-members
#
InputArgument Name | Description | Required |
---|---|---|
group-dn | Group’s Active Directory Distinguished Name. | Required |
member-type | The member type to query by. | Required |
attributes | A CSV list of attributes to include in the results (in addition to the default attributes). | Optional |
time_limit | Time limit (in seconds) for the search to run. | Optional |
disable-nested-search | Disable recursive retrieval of a user's group memberships. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
ActiveDirectory.Groups.dn | string | The group DN. |
ActiveDirectory.Groups.members.dn | string | The group member DN. |
ActiveDirectory.Groups.members.category | string | The category ("person" or "computer". |
#
Command Example#
Context Example#
Human Readable Output###Active Directory - Get Group Members | dn | displayName | mail | manager | memberOf | name | sAMAccountName | userAccountControl |---| ---| ---|---| ---| ---|---| ---| | CN=User 671 User | User 671 | test@demisto.int | | CN=Group124,OU=DemistoMng,DC=demisto,DC=int | User 671 | User 671User 671 | 514 | 671,OU=DemistoMng,DC=demisto,DC=int | User 671 | | | CN=Group2,OU=DemistoMng,DC=demisto,DC=int | User 671 | User 671User 671 | 514
#
18. Create an AD userCreate an AD user. Used in the IAM premium pack.
#
Base Commandiam-create-user
#
InputArgument Name | Description | Required |
---|---|---|
user-profile | A User Profile indicator that contains user information, such as name, email address, etc. | Required |
allow-enable | When set to true, after the command execution the status of the user in the 3rd-party integration will be active. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
IAM.Vendor.active | Boolean | When true, indicates that the employee's status is active. |
IAM.Vendor.brand | String | Name of the integration. |
IAM.Vendor.details | String | Indicates if the API was successful or provides error information. |
IAM.Vendor.email | String | The email address of the employee. |
IAM.Vendor.errorCode | Number | HTTP error response code. |
IAM.Vendor.errorMessage | String | Reason why the API failed. |
IAM.Vendor.id | String | The employee's user ID in the app. |
IAM.Vendor.instanceName | String | Name of the integration instance. |
IAM.Vendor.success | Boolean | When true, indicates that the command was executed successfully. |
IAM.Vendor.username | String | The employee's username in the app. |
IAM.Vendor.action | String | The command name. |
#
Command Example#
Human Readable Output#
Create User Resultsbrand | instanceName | success | active | id | username | details | |
---|---|---|---|---|---|---|---|
Active Directory Query | IAM_instance_1 | true | true | testdemisto2 | testdemisto2@paloaltonetworks.com | status: PROVISIONED created: 2020-10-18T17:54:30.000Z activated: 2020-10-18T17:54:30.000Z statusChanged: 2020-10-18T17:54:30.000Z lastLogin: null lastUpdated: 2020-10-18T17:54:30.000Z passwordChanged: null type: {"id": "oty8zfz6plq7b0r830h7"} profile: {"firstName": "Demisto", "lastName": "Test", "mobilePhone": null, "secondEmail": null, "login": "testdemisto2@paloaltonetworks.com", "email": "testdemisto44@paloaltonetworks.com"} credentials: {"provider": {"type": "Active Directory Query", "name": "Active Directory Query"}}} |
#
19. Update an AD userUpdates an existing AD user with the data passed in the user-profile argument. Used in the IAM premium pack.
#
Base Commandiam-update-user
#
InputArgument Name | Description | Required |
---|---|---|
user-profile | A User Profile indicator that contains user information, such as name, email address, etc. | Required |
allow-enable | When set to true, after the command execution the status of the user in the 3rd-party integration will be active. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
IAM.Vendor.active | Boolean | When true, indicates the employee's status is active. |
IAM.Vendor.brand | String | Name of the integration. |
IAM.Vendor.details | String | Indicates if the API was successful or provides error information. |
IAM.Vendor.email | String | The email address of the employee. |
IAM.Vendor.errorCode | Number | HTTP error response code. |
IAM.Vendor.errorMessage | String | Reason why the API failed. |
IAM.Vendor.id | String | The employee's user ID in the app. |
IAM.Vendor.instanceName | String | Name of the integration instance. |
IAM.Vendor.success | Boolean | When true, indicates that the command was executed successfully. |
IAM.Vendor.username | String | The employee's username in the app. |
IAM.Vendor.action | String | The command name. |
#
Command Example#
Human Readable Output#
Update User Resultsbrand | instanceName | success | active | id | username | details | |
---|---|---|---|---|---|---|---|
Active Directory Query | IAM_instance_1 | true | true | testdemisto2 | testdemisto22@paloaltonetworks.com | status: PROVISIONED created: 2020-10-18T17:54:30.000Z activated: 2020-10-18T17:54:30.000Z statusChanged: 2020-10-18T17:54:30.000Z lastLogin: null lastUpdated: 2020-10-18T17:54:30.000Z passwordChanged: null type: {"id": "oty8zfz6plq7b0r830h7"} profile: {"firstName": "Demisto", "lastName": "Test", "mobilePhone": null, "secondEmail": null, "login": "testdemisto2@paloaltonetworks.com", "email": "testdemisto44@paloaltonetworks.com"} credentials: {"provider": {"type": "Active Directory Query", "name": "Active Directory Query"}}} |
#
20. Update an AD userRetrieves a single AD user resource. Used in the IAM premium pack.
#
Base Commandiam-get-user
#
InputArgument Name | Description | Required |
---|---|---|
user-profile | A User Profile indicator that contains user information, such as name, email address, etc. | Required |
#
Context OutputPath | Type | Description |
---|---|---|
IAM.Vendor.active | Boolean | When true, indicates that the employee's status is active. |
IAM.Vendor.brand | String | Name of the integration. |
IAM.Vendor.details | String | Indicates if the API was successful or provides error information. |
IAM.Vendor.email | String | The email address of the employee. |
IAM.Vendor.errorCode | Number | HTTP error response code. |
IAM.Vendor.errorMessage | String | Reason why the API failed. |
IAM.Vendor.id | String | The employee's user ID in the app. |
IAM.Vendor.instanceName | String | Name of the integration instance. |
IAM.Vendor.success | Boolean | When true, indicates that the command was executed successfully. |
IAM.Vendor.username | String | The employee's username in the app. |
IAM.Vendor.action | String | The command name. |
#
Command Example#
Human Readable Output#
Get User Resultsbrand | instanceName | success | active | id | username | details | |
---|---|---|---|---|---|---|---|
Active Directory Query | IAM_instance_1 | true | true | testdemisto2 | testdemisto2@paloaltonetworks.com | status: PROVISIONED created: 2020-10-18T17:54:30.000Z activated: 2020-10-18T17:54:30.000Z statusChanged: 2020-10-18T17:54:30.000Z lastLogin: null lastUpdated: 2020-10-18T17:54:30.000Z passwordChanged: null type: {"id": "oty8zfz6plq7b0r830h7"} profile: {"firstName": "Demisto", "lastName": "Test", "mobilePhone": null, "secondEmail": null, "login": "testdemisto2@paloaltonetworks.com", "email": "testdemisto44@paloaltonetworks.com"} credentials: {"provider": {"type": "Active Directory Query", "name": "Active Directory Query"}}} |
#
22. Disable an AD userDisable an active AD user. Used in the IAM premium pack.
#
Base Commandiam-disable-user
#
InputArgument Name | Description | Required |
---|---|---|
user-profile | A User Profile indicator that contains user information, such as name, email address, etc. | Required |
#
Context OutputPath | Type | Description |
---|---|---|
IAM.Vendor.active | Boolean | When true, indicates that the employee's status is active. |
IAM.Vendor.brand | String | Name of the integration. |
IAM.Vendor.details | String | Indicates if the API was successful or provides error information. |
IAM.Vendor.email | String | The email address of the employee. |
IAM.Vendor.errorCode | Number | HTTP error response code. |
IAM.Vendor.errorMessage | String | Reason why the API failed. |
IAM.Vendor.id | String | The employee's user ID in the app. |
IAM.Vendor.instanceName | String | Name of the integration instance. |
IAM.Vendor.success | Boolean | When true, indicates that the command was executed successfully. |
IAM.Vendor.username | String | The employee's username in the app. |
IAM.Vendor.action | String | The command name. |
#
Command Example#
Human Readable Output#
Disable User Resultsbrand | instanceName | success | active | id | username | details | |
---|---|---|---|---|---|---|---|
Active Directory Query | IAM_instance_1 | true | false | testdemisto2 | testdemisto2@paloaltonetworks.com | status: PROVISIONED created: 2020-10-18T17:54:30.000Z activated: 2020-10-18T17:54:30.000Z statusChanged: 2020-10-18T17:54:30.000Z lastLogin: null lastUpdated: 2020-10-18T17:54:30.000Z passwordChanged: null type: {"id": "oty8zfz6plq7b0r830h7"} profile: {"firstName": "Demisto", "lastName": "Test", "mobilePhone": null, "secondEmail": null, "login": "testdemisto2@paloaltonetworks.com", "email": "testdemisto44@paloaltonetworks.com"} credentials: {"provider": {"type": "Active Directory Query", "name": "Active Directory Query"}}} |
#
Additional Information- LDAP attributes: https://msdn.microsoft.com/en-us/library/ms675090(v=vs.85).aspx
- Distinguished Names explanation and examples: https://ldap.com/ldap-dns-and-rdns/