Skip to main content

Active Directory Query v2

This Integration is part of the Active Directory Query Pack.#

The Active Directory Query integration enables you to access and manage Active Directory objects (users, contacts, and computers). This integration was integrated and tested with version 1.5.0 of Active Directory Query v2

Some changes have been made that might affect your existing content. If you are upgrading from a previous version of this integration, see Breaking Changes.

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 contacts#
  • The 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 in Cortex#

ParameterDescriptionRequired
Server IP address (for example, 192.168.0.1)The Server IP that should be used to access Active Directory.True
PortServer port. If not specified, the default port is 389, or 636 for LDAPS.False
CredentialsUser credentials.True
PasswordTrue
NTLM authenticationIndicates whether to use NTLM authentication.False
Base DN (for example "dc=company,dc=com")The basic hierarchical path of objects in the active directory.True
Page sizeThe number of results to be returned, per page (page - response content from AD server), from a query. This may effect query run time.True
Secure ConnectionUse SSL or Start TLS for secure connection or ‘None’ for communication over clear-text.True
SSL VersionThe SSL\TLS version to use in SSL or Start TLS connections types. It is recommended to select the TLS_CLIENT option, which auto-negotiate the highest protocol version that both the client and server support, and configure the context client-side connections. For more information please see: ssl.PROTOCOLS).False
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)False
Incoming MapperUsed in the IAM commands.True
Outgoing MapperUsed in the IAM commands.True
Group CN for terminated employeesFalse
Create user if does not existIf true, the user is created if the user profile doesn't exist in AD. Used in IAM commands only.False
Identity Lifecycle Management premium pack configuration#

The premium ILM content pack introduces new functionality that uses both an incoming and an outgoing mapper.

  1. 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)".
  2. 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.

Commands#

You can execute these commands from the 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.

ad-expire-password#


Expires the password of an Active Directory user.

Base Command#

ad-expire-password

Required Permissions#

Requires Reset user passwords and force password change at next logon permissions.

Input#

Argument NameDescriptionRequired
usernameThe username (samAccountName) of the user to modify.Required
base-dnRoot (for example, DC=domain,DC=com).Optional

Context Output#

There is no context output for this command.

ad-modify-password-never-expire#


Modifies the AD account attribute "Password Never Expire".

Base Command#

ad-modify-password-never-expire

Required Permissions#

Requires Read userAccountControl and write userAccountControl permissions.

Input#

Argument NameDescriptionRequired
usernameThe sAMAccountName of the user to modify.Required
valueValue to set "Password Never Expire". Possible values are: true, false.Required

Context Output#

There is no context output for this command.

Command Example#
!ad-modify-password-never-expire username=jack value=true
Human Readable Output#
AD account jack has set "password never expire" attribute. Value is set to True

ad-create-user#


Creates an Active Directory user. This command requires a secure connection (SSL,TLS).

Base Command#

ad-create-user

Required Permissions#

Requires Create, delete, and manage user accounts permissions.

Input#

Argument NameDescriptionRequired
usernameThe username (samAccountName) of the user to modify.Required
passwordThe initial password to set for the user. The user is requested to change the password after login.Required
user-dnThe user DN.Required
display-nameThe user display name.Optional
descriptionA short description of the user.Optional
emailThe user email.Optional
telephone-numberThe user telephone number.Optional
titleThe user job title.Optional
custom-attributesSets basic or custom attributes of the user object. For example, custom-attributes="{\"notes\":\"a note about the contact\",\"company\":\"company name\"}".Optional

Context Output#

There is no context output for this command.

Command Example#
ad-create-user username="jack" password="1q2w3e4r!" user-dn="cn=jack,dc=demisto,dc=int" display-name="Samurai Jack"
Human Readable Output#
Created user with DN: cn=jack,dc=demisto,dc=int

ad-search#


Runs Active Directory queries.

For more information on the query syntax see the Microsoft documentation.

For more information on LDAP filters, see the LDAP documentation.

Base Command#

ad-search

Required Permissions#

Requires Read and Read and read all properties permissions in General permissions.

Input#

Argument NameDescriptionRequired
filterEnables you to define 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 syntax: https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax.Required
base-dnRoot. For example, DC=domain,DC=com). By default, the Base DN configured for the instance is used.Optional
attributesA CSV list of the object attributes to return. For example, "dn,memberOf". To return all object attributes, specify 'ALL'.Optional
size-limitThe maximum number of records to return. Default is 50.Optional
time-limitThe maximum time to pull records (in seconds).Optional
context-outputWhether to output the search results to the context. Possible values are: yes, no. Default is yes.Optional
page-sizeThe page size to query. The size-limit value will be ignored.Optional
page-cookieAn opaque string received in a paged search, used for requesting subsequent entries.Optional

Context Output#

PathTypeDescription
ActiveDirectory.Search.dnstringThe distinguished names that match the query.
ActiveDirectory.SearchunknownThe result of the search.
ActiveDirectory.SearchPageCookiestringAn opaque string received in a paged search, used for requesting subsequent entries.
Command Example#
ad-search filter="(&(objectCategory=person)(objectClass=user)(!(cn=andy)))"
Context Example#
{
"ActiveDirectory.Search": [
{
"dn": "CN=demistoadmin,CN=Users,DC=demisto,DC=int"
},
{
"dn": "CN=Guest,CN=Users,DC=demisto,DC=int"
}
]
}
Human Readable Output#

Active Directory Search#

dn
CN=demistoadmin,CN=Users,DC=demisto,DC=int
CN=Guest,CN=Users,DC=demisto,DC=int

ad-add-to-group#


Adds an Active Directory user or computer to a group.

Base Command#

ad-add-to-group

Required Permissions#

Requires Create, delete, and manage groups permissions.

Input#

Argument NameDescriptionRequired
usernameThe username of the user to add to the group. If this argument is not specified, the computer name argument must be specified.Optional
computer-nameThe name of the computer to add to the group. If this argument is not specified, the username argument must be specified.Optional
group-cnThe name of the group to add the user to.Required
base-dnRoot. For example, DC=domain,DC=com. By default, the Base DN configured for the instance is used.Optional

Context Output#

There is no context output for this command.

Command Example#
ad-add-to-group username="Jack" group-cn="Users"
Human Readable Output#
Object with dn CN=jack,DC=demisto,DC=int was added to group Users

ad-remove-from-group#


Removes an Active Directory user or computer from a group.

Base Command#

ad-remove-from-group

Required Permissions#

Requires Create, delete, and manage groups permissions.

Input#

Argument NameDescriptionRequired
usernameThe name of the user to remove from the group. If this argument is not specified, the computer name argument must be specified.Optional
computer-nameThe name of the computer to remove from the group. If this argument is not specified, the username argument must be specified.Optional
group-cnThe name of the group to remove the user from.Required
base-dnRoot. For example, DC=domain,DC=com). By default, the Base DN configured for the instance is used.Optional

Context Output#

There is no context output for this command.

Command Example#
ad-remove-from-group username="jack" group-cn="Users"
Human Readable Output#
Object with dn CN=jack,DC=demisto,DC=int removed from group Users

ad-update-user#


Updates attributes of an existing Active Directory user.

Base Command#

ad-update-user

Required Permissions#

Requires Write All Properties and Read All Properties permission from User objects.

Input#

Argument NameDescriptionRequired
usernameThe username of the account to update (sAMAccountName).Required
attribute-nameThe name of the attribute to modify. For example, sn, displayName, mail, and so on.Required
attribute-valueThe value to change the attribute to.Required
base-dnRoot. For example, DC=domain,DC=com. By default, the Base DN configured for the instance is used.Optional

Context Output#

There is no context output for this command.

Command Example#
!ad-update-user attribute-name=description attribute-value=Samurai username=jack
Human Readable Output#
Updated user's description to Samurai

ad-delete-user#


Deletes an Active Directory user.

Base Command#

ad-delete-user

Required Permissions#

Requires Create, delete, and manage user accounts permissions.

Input#

Argument NameDescriptionRequired
user-dnThe DN of the user to delete.Required

Context Output#

There is no context output for this command.

Command Example#
!ad-delete-user user-dn="cn=jack,dc=demisto,dc=int"
Human Readable Output#
Deleted object with dn cn=jack,dc=demisto,dc=int

ad-create-contact#


Creates an Active Directory contact.

Base Command#

ad-create-contact

Required Permissions#

Requires full control permission from Contact objects.

Input#

Argument NameDescriptionRequired
contact-dnThe contact DN.Required
display-nameThe contact display name.Optional
descriptionThe short description of the contact.Optional
emailThe email address of the contact.Optional
telephone-numberThe contact telephone number.Optional
custom-attributesSets basic or custom attributes of the contact object. For example, custom-attributes="{\"notes\":\"some note about the contact\",\"company\":\"some company\"}.".Optional
titleThe contact job title.Optional

Context Output#

There is no context output for this command.

Command Example#
!ad-create-contact contact-dn="cn=jack,dc=demisto,dc=int" description="Samurai" email=jack@company.com
Human Readable Output#
Created contact with DN: cn=jack,dc=demisto,dc=int

ad-update-contact#


Updates attributes of an existing Active Directory contact.

Base Command#

ad-update-contact

Required Permissions#

Requires Write All Properties and Read All Properties permission from Contact objects.

Input#

Argument NameDescriptionRequired
contact-dnThe contact DN.Required
attribute-nameThe attribute name to update.Required
attribute-valueThe attribute value to update.Required

Context Output#

There is no context output for this command.

Command Example#
ad-update-contact contact-dn="cn=Jack,dc=demisto,dc=int" attribute-name="displayName" attribute-value="Jack H."
Human Readable Output#
Updated contact’s displayName to: Jack H.

ad-disable-account#


Disables an Active Directory user account.

Base Command#

ad-disable-account

Required Permissions#

Requires Read userAccountControl and write userAccountControl permissions.

Input#

Argument NameDescriptionRequired
usernameThe username of the account to disable (sAMAccountName).Required
base-dnRoot (e.g., DC=domain,DC=com). By default, the Base DN configured for the instance is used.Optional

Context Output#

There is no context output for this command.

Command Example#
ad-disable-account username="jack"
Human Readable Output#
User “CN=jack,DC=demisto,DC=int” has been disabledUser jack was disabled

ad-enable-account#


Enables a previously disabled Active Directory account.

Base Command#

ad-enable-account

Required Permissions#

Requires Read userAccountControl and write userAccountControl permissions.

Input#

Argument NameDescriptionRequired
usernameThe username of the account to enable (sAMAccountName).Required
base-dnRoot. For example, DC=domain,DC=com). By default, the Base DN configured for the instance is used.Optional
restore_userIf true, the command will enable the user with his restored options. Possible values are: true, false.Optional

Context Output#

There is no context output for this command.

Command Example#
ad-enable-account username="jack"
Human Readable Output#
User jack was enabledUser “CN=jack,DC=demisto,DC=int” has been enabled

ad-unlock-account#


Unlocks a previously locked Active Directory user account.

Base Command#

ad-unlock-account

Required Permissions#

Requires Read lockoutTime and write lockoutTime permissions.

Input#

Argument NameDescriptionRequired
usernameThe username of the account to unlock (sAMAccountName).Required
base-dnRoot. For example, DC=domain,DC=com. By default, the Base DN configured for the instance is used.Optional

Context Output#

There is no context output for this command.

Command Example#
!ad-unlock-account username=mooncake
Human Readable Output#
User "CN=mooncake,CN=Users,DC=demisto,DC=int" has been unlocked

ad-set-new-password#


Sets a new password for an Active Directory user. This command requires a secure connection (SSL,TLS).

Base Command#

ad-set-new-password

Required Permissions#

Requires Reset password permissions.

Input#

Argument NameDescriptionRequired
usernameThe username of the account to disable (sAMAccountName).Required
passwordThe password to set for the user.Required
base-dnRoot. For example, DC=domain,DC=com. Base DN configured for the instance is used as default.Optional

Context Output#

There is no context output for this command.

Command Example#
!ad-set-new-password username="NoaCo" password="noni1q2w3e!"
Human Readable Output#
User password successfully set

ad-modify-computer-ou#


Modifies the computer organizational unit within a domain.

Base Command#

ad-modify-computer-ou

Required Permissions#

Requires Write All Properties permission from Computer objects.

Input#

Argument NameDescriptionRequired
computer-nameThe name of the computer to modify.Required
full-superior-dnSuperior DN. For example, OU=computers,DC=domain,DC=com (the specified domain must be the same as the current computer domain).Optional

Context Output#

There is no context output for this command.

Command Example#
!ad-modify-computer-ou computer-name=mike full-superior-dn=OU=Sarah,DC=demisto,DC=int
Human Readable Output#
"mike" was successfully moved to "OU=Sarah,DC=demisto,DC=int"

ad-modify-user-ou#


Modifies the user organizational unit within a domain.

Base Command#

ad-modify-user-ou

Required Permissions#

Requires Write All Properties permission from Computer objects.

Input#

Argument NameDescriptionRequired
user-nameThe name of the user to modify.Required
full-superior-dnSuperior DN. For example, OU=users,DC=domain,DC=com (the specified domain must be the same as the current user domain).Optional

Context Output#

There is no context output for this command.

Command Example#
!ad-modify-user-ou user-name=username full-superior-dn=OU=users,DC=demisto,DC=int
Human Readable Output#
"username" was successfully moved to "OU=users,DC=demisto,DC=int"

ad-get-user#


Retrieves 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 Command#

ad-get-user

Required Permissions#

Requires Read all user information permissions.

Input#

Argument NameDescriptionRequired
dnThe Distinguished Name of the user in which to return information.Optional
nameThe name of the user to return information.Optional
attributesAdds AD attributes of the resulting objects to the default attributes.Optional
attributes-to-excludeRemoves AD attributes of the resulting objects from the attributes.Optional
custom-field-typeQueries users by custom field type.Optional
custom-field-dataQueries users by custom field data (relevant only if the custom-field-type argument is provided).Optional
usernameQueries users by the samAccountName attribute.Optional
sAMAccountNameQueries users by the samAccountName attribute.Optional
limitThe maximum number of objects to return. Default is 20.Optional
emailQueries by the user's email address.Optional
user-account-control-outWhether to include verbose translation for UserAccountControl flags. Default is false. Possible values are: true, false. Default is false.Optional
page-sizeThe page size to query. The limit value will be ignored.Optional
page-cookieAn opaque string received in a paged search, used for requesting subsequent entries.Optional

Context Output#

PathTypeDescription
ActiveDirectory.Users.dnstringThe user distinguished name.
ActiveDirectory.Users.displayNamestringThe user display name.
ActiveDirectory.Users.namestringThe user common name.
ActiveDirectory.Users.sAMAccountNamestringThe user sAMAccountName.
ActiveDirectory.Users.userAccountControlnumberThe user account control flag.
ActiveDirectory.Users.mailstringThe user email address.
ActiveDirectory.Users.managerstringThe manager of the user.
ActiveDirectory.Users.memberOfstringGroups in which the user is a member.
ActiveDirectory.Users.userAccountControlFields.SCRIPTboolWhether the login script is run. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.ACCOUNTDISABLEboolWhether the user account is disabled. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.HOMEDIR_REQUIREDboolWhether the home folder is required. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.LOCKOUTboolWhether the user is locked out. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.PASSWD_NOTREQDboolWhether the password is required. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.PASSWD_CANT_CHANGEboolWhether the user can change the password. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.ENCRYPTED_TEXT_PWD_ALLOWEDboolWhether the user can send an encrypted password. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.TEMP_DUPLICATE_ACCOUNTboolWhether this is an account for users whose primary account is in another domain. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.NORMAL_ACCOUNTboolWhether this is a default account type that represents a typical user. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.INTERDOMAIN_TRUST_ACCOUNTboolWhether the account is permitted to trust a system domain that trusts other domains. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.WORKSTATION_TRUST_ACCOUNTboolWhether this is a computer account for a computer running Microsoft Windows NT 4.0 Workstation, Microsoft Windows NT 4.0 Server, Microsoft Windows 2000 Professional, or Windows 2000 Server and is a member of this domain.
ActiveDirectory.Users.userAccountControlFields.SERVER_TRUST_ACCOUNTboolWhether this is a computer account for a domain controller that is a member of this domain. Works for *Windows Server 2012 R2*.
ActiveDirectory.Users.userAccountControlFields.DONT_EXPIRE_PASSWORDboolWhether to never expire the password on the account.
ActiveDirectory.Users.userAccountControlFields.MNS_LOGON_ACCOUNTboolWhether this is an MNS login account.
ActiveDirectory.Users.userAccountControlFields.SMARTCARD_REQUIREDboolWhether to force the user to log in by using a smart card.
ActiveDirectory.Users.userAccountControlFields.TRUSTED_FOR_DELEGATIONboolWhether the service account (the user or computer account) under which a service runs is trusted for Kerberos delegation.
ActiveDirectory.Users.userAccountControlFields.NOT_DELEGATEDboolWhether the security context of the user isn't delegated to a service even if the service account is set as trusted for Kerberos delegation.
ActiveDirectory.Users.userAccountControlFields.USE_DES_KEY_ONLYboolWhether to restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
ActiveDirectory.Users.userAccountControlFields.DONT_REQ_PREAUTHboolWhether this account require Kerberos pre-authentication for logging on.
ActiveDirectory.Users.userAccountControlFields.PASSWORD_EXPIREDboolWhether the user password expired.
ActiveDirectory.Users.userAccountControlFields.TRUSTED_TO_AUTH_FOR_DELEGATIONboolWhether the account is enabled for delegation.
ActiveDirectory.Users.userAccountControlFields.PARTIAL_SECRETS_ACCOUNTboolWhether the account is a read-only domain controller (RODC).
ActiveDirectory.UsersPageCookiestringAn opaque string received in a paged search, used for requesting subsequent entries.
Account.DisplayNamestringThe user display name.
Account.GroupsstringGroups for which the user is a member.
Account.ManagerstringThe user manager.
Account.IDstringThe user distinguished name.
Account.UsernamestringThe user samAccountName.
Account.EmailstringThe user email address.
Command Example#
!ad-get-user name=*
Human Readable Output#

Active Directory - Get Users#

dndisplayNamemailmanagermemberOfnamesAMAccountNameuserAccountControl
CN=demistoadmin,CN=Users,DC=demisto,DC=intdemistoadmindemistoadmin@demisto.intCN=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=intdemistoadmindemistoadmin66048
CN=Guest,CN=Users,DC=demisto,DC=intCN=Guests,CN=Builtin,DC=demisto,DC=intGuestGuest66082

ad-get-computer#


Retrieves 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 Command#

ad-get-computer

Required Permissions#

Requires Read and Read and read all properties permissions from Computer objects.

Input#

Argument NameDescriptionRequired
dnThe computer's DN.Optional
nameThe name of the computer to return information about.Optional
attributesAdds AD attributes of the resulting objects to the default attributes.Optional
custom-field-dataSearch computers by custom field data (relevant only if the customFieldType argument is provided).Optional
custom-field-typeSearch the computer by custom field type.Optional
limitThe maximum number of records to return.Optional
page-sizeThe page size to query. The value limit will be ignored.Optional
page-cookieAn opaque string received in a paged search, used for requesting subsequent entries.Optional

Context Output#

PathTypeDescription
ActiveDirectory.Computers.dnunknownThe computer distinguished name.
ActiveDirectory.Computers.memberOfunknownGroups for which the computer is listed.
ActiveDirectory.Computers.nameunknownThe computer name.
Endpoint.IDunknownThe computer DN.
Endpoint.HostnameunknownThe computer host name.
Endpoint.GroupsunknownGroups for which the computer is listed as a member.
ActiveDirectory.ComputersPageCookiestringAn opaque string received in a paged search, used for requesting subsequent entries.
Command Example#
ad-get-computer name=noapc
Context Example#
{
"ActiveDirectory.Computers":
[ { "dn": "CN=noapc,OU=Shani,DC=demisto,DC=int",
"memberOf": [ "CN=Exchange Servers,OU=Microsoft Exchange Security Groups,DC=demisto,DC=int" ],
"name": [ "noapc" ] } ],
"Endpoint": [ { "Hostname": [ "noapc" ],
"Type": "AD", "ID": "CN=noapc,OU=Shani,DC=demisto,DC=int",
"Groups": [ "CN=Exchange Servers,OU=Microsoft Exchange Security Groups,DC=demisto,DC=int" ]
} ]
}
Human Readable Output#

Active Directory - Get Computers#

dnmemberOfname
CN=noapc,OU=Shani,DC=demisto,DC=intCN=Exchange Servers,OU=Microsoft Exchange Security Groups,DC=demisto,DC=intnoapc

ad-get-group-members#


Retrieves the list of users or computers that are members of the specified group.

Base Command#

ad-get-group-members

Required Permissions#

Requires Read members permissions.

Input#

Argument NameDescriptionRequired
group-dnThe Distinguished Name of the Group's Active Directory.Required
member-typeThe type of members to search. Can be: "Person", or "computer". Default is person. Possible values are: person, computer, group. Default is person.Required
attributesCSV list of attributes to include in the results, in addition to the default attributes.Optional
time_limitTime limit (in seconds) for the search to run. Default is 180.Optional
disable-nested-searchWhether to disable recursive retrieval of group memberships of a user. Possible values are: false, true. Default is false.Optional
sAMAccountNameQueries results by the samAccountName attribute. Default is *.Optional
limitThe maximum number of records to return.Optional
page-sizeThe page size to query. The limit value will be ignored.Optional
page-cookieAn opaque string received in a paged search, used for requesting subsequent entries.Optional

Context Output#

PathTypeDescription
ActiveDirectory.Groups.dnstringThe group DN.
ActiveDirectory.Groups.members.dnstringThe group member DN.
ActiveDirectory.Groups.members.categorystringThe group members category.
ActiveDirectory.GroupsPageCookiestringAn opaque string received in a paged search, used for requesting subsequent entries.

Command Example#

!ad-get-group-members group-dn="CN=Group124,OU=DemistoMng,DC=demisto,DC=int"
Context Example#
{ "Account":
[ { "DisplayName": [ "User 671 User 671" ],
"Email": null,
"Groups": [ "CN=Group124,OU=DemistoMng,DC=demisto,DC=int", "CN=Group2,OU=DemistoMng,DC=demisto,DC=int" ],
"ID": "CN=User 671 User 671,OU=DemistoMng,DC=demisto,DC=int",
"Managr": [],
"Type": "AD",
"Username": null } ],
"ActiveDirectory":
{ "Groups": { "dn": "CN=Group124,OU=DemistoMng,DC=demisto,DC=int",
"members": [ { "category": "person", "dn": "CN=User 671 User 671,OU=DemistoMng,DC=demisto,DC=int" } ] },
"Users": { "displayName": [ "User 671 User 671" ],
"dn": "CN=User 671 User 671,OU=DemistoMng,DC=demisto,DC=int",
"mail": [ "test@demisto.int" ],
"manager": [],
"memberOf": [ "CN=Group124,OU=DemistoMng,DC=demisto,DC=int",
"CN=Group2,OU=DemistoMng,DC=demisto,DC=int" ],
"name": [ "User 671 User 671" ],
"sAMAccountName": [ "User 671User 671" ],
"userAccountControl": [ 514 ] }
}
}
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

ad-create-group#


Creates a new security or distribution Active Directory group.

Base Command#

ad-create-group

Required Permissions#

Requires Create, delete, and manage groups permissions.

Input#

Argument NameDescriptionRequired
nameThe Active Directory name of the group.Required
group-typeThe type of group. Can be: "security", or "distribution". Possible values are: security, distribution.Required
dnThe Full Distinguished Name (DN) of the group. Use double quotes ("") rather than single quotes ('') when initializing this command.Required
membersThe Full DN Of users or groups that will be members of the newly created group.Optional

Context Output#

There is no context output for this command.

ad-delete-group#


Deletes an existing Active Directory security or distribution group.

Base Command#

ad-delete-group

Required Permissions#

Requires Create, delete, and manage groups permissions.

Input#

Argument NameDescriptionRequired
dnThe Active Directory Distinguished Name (DN) of the group.Required

Context Output#

There is no context output for this command.

ad-update-group#


Updates attributes of an existing Active Directory group.

Base Command#

ad-update-group

Required Permissions#

Requires Create, delete, and manage groups permissions.

Input#

Argument NameDescriptionRequired
groupnameThe group name of the group to update (sAMAccountName).Optional
attributenameThe name of the attribute to modify. For example, Description and displayName.Required
attributevalueThe value of the attribute to change.Required
basednRoot. For example, DC=domain,DC=com. By default, the Base DN configured for the instance is used.Optional

Context Output#

There is no context output for this command.

ad-test-credentials#


Test given credentials.

Base Command#

ad-test-credentials

Input#

Argument NameDescriptionRequired
usernameUsername to test. By itself or formatted as SERVER_IP\USERNAMERequired
passwordPassword to test.Required

Context Output#

PathTypeDescription
ActiveDirectory.ValidCredentialsUnknownList of usernames that successfully logged in.

iam-create-user#


Creates an Active Directory user. This command requires a secure connection (SSL,TLS). Used in the IAM premium pack.

Base Command#

iam-create-user

Required Permissions#

Requires Create, delete, and manage user accounts permissions.

Input#

Argument NameDescriptionRequired
user-profileA User Profile indicator that contains user information, such as name, email address, etc.Required
allow-enableWhen set to true, after the command execution the status of the user in the 3rd-party integration will be active. Possible values are: true, false. Default is true.Optional

Context Output#

PathTypeDescription
IAM.UserProfileUnknownThe user profile.
IAM.Vendor.activeBooleanIf true, the employee status is active.
IAM.Vendor.brandStringThe integration name.
IAM.Vendor.detailsUnknownTells the user if the API was successful, otherwise provides error information.
IAM.Vendor.emailStringThe employee email address.
IAM.Vendor.errorCodeNumberThe HTTP error response code.
IAM.Vendor.errorMessageStringThe reason the API failed.
IAM.Vendor.idStringThe employee user ID in the app.
IAM.Vendor.instanceNameUnknownThe name of the integration instance.
IAM.Vendor.successBooleanIf true, the command executed successfully.
IAM.Vendor.usernameStringThe employee username in the app.
IAM.Vendor.actionStringThe command name.

Command Example#

!iam-create-user user-profile={\"email\":\"testdemisto2@paloaltonetworks.com\", \"lastname\":\"Test\",\"firstname\":\"Demisto\"}

Human Readable Output#

Create User Results#

brandinstanceNamesuccessactiveidusernameemaildetails
Active Directory QueryIAM_instance_1truetruetestdemisto2testdemisto2@paloaltonetworks.comstatus: 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"}}}

iam-get-user#


Retrieves a single user resource. Used in the IAM premium pack.

Base Command#

iam-get-user

Required Permissions#

Requires Read all user information permissions.

Input#

Argument NameDescriptionRequired
user-profileA User Profile indicator that contains user information, such as name and email address.Required

Context Output#

PathTypeDescription
IAM.UserProfileUnknownThe user profile.
IAM.Vendor.activeBooleanIf true the employee status is active.
IAM.Vendor.brandStringThe integration name.
IAM.Vendor.detailsUnknownTells the user if the API was successful, otherwise provides error information.
IAM.Vendor.emailStringThe employee email address.
IAM.Vendor.errorCodeNumberThe HTTP error response code.
IAM.Vendor.errorMessageStringThe reason the API failed.
IAM.Vendor.idStringThe employee user ID in the app.
IAM.Vendor.instanceNameUnknownThe integration instance name.
IAM.Vendor.successBooleanIf true, the command was executed successfully.
IAM.Vendor.usernameStringThe employee username in the app.
IAM.Vendor.actionStringThe command name.

Command Example#

!iam-get-user user-profile={\"email\":\"testdemisto2@paloaltonetworks.com\"}

Human Readable Output#

Get User Results#

brandinstanceNamesuccessactiveidusernameemaildetails
Active Directory QueryIAM_instance_1truetruetestdemisto2testdemisto2@paloaltonetworks.comstatus: 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"}}}

iam-update-user#


Updates an existing user with the data in the User Profile indicator that is passed in the user-profile argument. Used in the IAM premium pack.

Base Command#

iam-update-user

Required Permissions#

Requires Create, delete, and manage user accounts permissions.

Input#

Argument NameDescriptionRequired
user-profileA User Profile indicator that contains user information, such as name and email address.Required
allow-enableWhen set to true, after the command executes the user status in the 3rd-party integration is active. Possible values are: true, false. Default is true.Optional

Context Output#

PathTypeDescription
IAM.UserProfileUnknownThe user profile
IAM.Vendor.activeBooleanGives the active status of user. Can be true or false.
IAM.Vendor.brandStringThe integration name.
IAM.Vendor.detailsUnknownTells the user if the API was successful, otherwise provides error information.
IAM.Vendor.emailStringThe employee email address.
IAM.Vendor.errorCodeNumberThe HTTP error response code.
IAM.Vendor.errorMessageStringThe reason the API failed.
IAM.Vendor.idStringThe employee user ID in the app.
IAM.Vendor.instanceNameUnknownThe integration instance name.
IAM.Vendor.successBooleanIf true, the command executed successfully.
IAM.Vendor.usernameStringThe employee username in the app.
IAM.Vendor.actionStringThe command name.

Command Example#

!iam-update-user user-profile={\"email\":\"testdemisto22@paloaltonetworks.com\", \"name\":\"testdemisto2\"}

Human Readable Output#

Update User Results#

brandinstanceNamesuccessactiveidusernameemaildetails
Active Directory QueryIAM_instance_1truetruetestdemisto2testdemisto22@paloaltonetworks.comstatus: 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"}}}

iam-disable-user#


Disables a user. Used in the IAM premium pack.

Base Command#

iam-disable-user

Required Permissions#

Requires Read userAccountControl and write userAccountControl permissions.

Input#

Argument NameDescriptionRequired
user-profileA User Profile indicator that contains user information, such as name and email address.Required

Context Output#

PathTypeDescription
IAM.UserProfileUnknownThe user profile.
IAM.Vendor.activeBooleanGives the active status of user. Can be true or false.
IAM.Vendor.brandStringThe integration name.
IAM.Vendor.detailsUnknownTells the user if the API was successful, otherwise provides error information.
IAM.Vendor.emailStringThe employee email address.
IAM.Vendor.errorCodeNumberThe HTTP error response code.
IAM.Vendor.errorMessageStringThe reason the API failed.
IAM.Vendor.idStringThe employee user ID in the app.
IAM.Vendor.instanceNameUnknownThe integration instance name.
IAM.Vendor.successBooleanIf true, the command was executed successfully.
IAM.Vendor.usernameStringThe employee username in the app.
IAM.Vendor.actionStringThe command name.

Command Example#

!iam-disable-user user-profile={\"email\":\"testdemisto2@paloaltonetworks.com\"}

Human Readable Output#

Disable User Results#

brandinstanceNamesuccessactiveidusernameemaildetails
Active Directory QueryIAM_instance_1truefalsetestdemisto2testdemisto2@paloaltonetworks.comstatus: 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#

get-mapping-fields#


Retrieves a User Profile schema which holds all of the user fields in the application. Used for outgoing mapping through the Get Schema option.

Base Command#

get-mapping-fields

Required Permissions#

Requires Read and Read and read all properties permissions in General permissions.

Input#

There are no input arguments for this command.

Context Output#

There is no context output for this command.

Incident Mirroring#

You can enable incident mirroring between Cortex XSOAR incidents and Active Directory Query v2 corresponding events (available from Cortex XSOAR version 6.0.0).

To set up the mirroring, enable Fetching incidents in your instance configuration.

Newly fetched incidents will be mirrored in the chosen direction. However, this selection does not affect existing incidents.

Important Note: To ensure the mirroring works as expected, mappers are required, both for incoming and outgoing, to map the expected fields in Cortex XSOAR and Active Directory Query v2.

Breaking changes from the previous version of this integration - Active Directory Query v2#

The following sections list the changes in this version.

Arguments#

The following arguments were added in this version:#

In the ad-get-user command:

  • attributes-to-exclude

In the ad-search command, support pagination with the following arguments:

  • page-size
  • page-cookie

In the following commands: ad-get-user, ad-get-computer, ad-get-group-members, support pagination with the following arguments:

  • limit
  • page-size
  • page-cookie