Fortinet black logo

Active Directory

Home FortiSOAR Connectors Active Directory

Active Directory v2.1.0

2.1.0
2.4.0
2.3.0
2.2.1
2.2.0
2.1.1
2.1.0
2.0.1
2.0.0
Copy Link
Copy Doc ID 914f670b-f4d3-40ba-b92e-53835f4361e7:1

About the connector

Active Directory (AD) is a directory service that Microsoft developed for Windows domain networks. You can directly query AD to retrieve information about users, groups, and computers, in an organization, by using the Lightweight Directory Access Protocol (LDAP) to directly query the AD.

This document provides information about the Active Directory connector, which facilitates automated interactions with an Active Directory server using FortiSOAR™ playbooks. Add the Active Directory connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically retrieving all the information for users, groups, and computers in the AD and retrieving a list of search attributes that you can use to search AD.

Version information

Connector Version: 2.1.0

FortiSOAR™ Versions Tested on: 5.1.0-464

Authored By: Fortinet.

Certified: Yes

Release Notes for version 2.1.0

Following enhancements have been made to the Active Directory Connector in version 2.1.0:

  • Added the following new operations and playbooks:

    • Add Object

    • Remove Object

    • Update Object

    • Add Group Members

    • Remove Group Members

  • Added the Page Size, Size Limit, Paged Cookie input parameters to the following new operations:

    • Global Search
    • Advanced Search
    • Get All Object Details.

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-activedirectory

For the detailed procedure to install a connector, click here

Prerequisites to configuring the connector

  • You must have the IP address or Hostname of the Active Directory server to which you will connect and perform the automated operations and credentials to access that server.
  • You must open port 389, for TCP or UDP connections, or 636 for TCP connections over SSL, on the firewall to allow communication between FortiSOAR™ and the Active Directory server.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Active Directory connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Hostname IP address or Hostname of the Active Directory (AD) server.
Port Port number used for connecting to the AD server.
Username Valid AD service account with a minimum of read access.
Password Password for your AD user.
Base DN The base, or node from where the LDAP search should start.
All connector operations are carried out using the Base DN as a root to the AD organization tree.
You can restrict the AD lookup by providing appropriate filters in this parameter. Some examples of the same are as follows:
DC=cspune,DC=com
OU=workstation,DC=cspune,DC=com
OU=Develop,OU=workstation,DC=cspune,DC=com
Bind DN The fully distinguished name that is used to bind to the LDAP server.
Use TLS Specifies whether SSL and TLS will be required to establish the connection between the Active Directory connector and the AD server.
By default, this option is set as false, and therefore, SSL is used by default.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Global Search Searches and retrieves records from AD using global search, based on the specified search object, such as user, computer, group, search attribute, or a search attribute value, such as SamAccount Name, Distinguished Name, Common Name, Display Name, or Email. When you search a record based on a search attribute value, the record from AD is retrieved based on the specified attribute value. search_query
Investigation
Get All Objects Details Searches and retrieves all records from AD based on a specified search object, such as user, computer, or group. search_query
Investigation
Get Specific Object Details Searches and retrieves records from AD based on a specified search object, such as user, computer, or group. However, this search is limited to the records found for the object name you have specified.
For example, if you want to retrieve the records from AD for a specific user, you need to specify the name of the user.		 search_query
Investigation
Enable User Account Enables the account of a specific AD user based on the SamAccount Name or the Email of the user. enable_user
Containment
Disable User Account Disables the account of a specific AD user based on the SamAccount Name or the Email of the user. disable_user
Containment
Reset Password Resets the password for a specific AD user based on the SamAccount Name or the Email, or the Distinguished Name (DN) of the user. reset_password
Containment
Advanced Search Executes an advanced LDAP query that searches and retrieves AD records based on your custom query. search_query
Investigation
Add Object Add an object entry of User, Group, Computer or Organization Unit (OU) type in Active Directory based on the type of object and other input parameters you have specified. add_object
Investigation
Update Object Updates an existing object entry of User, Group, Computer or Organization Unit (OU) type in Active Directory based on the type of object and other input parameters you have specified. update_update
Investigation
Delete Object Deletes an existing object entry of User, Group, Computer or Organization Unit (OU) type from Active Directory based on the type of object and other input parameters you have specified. delete_object
Containment
Add Group Members Adds an Active Directory User or Computer as a member to an existing Group in Active Directory based on the Group DN and User or computer DN you have specified. add_group_members
Investigation
Remove Group Members Removes an Active Directory User or Computer as a member from an existing Group in Active Directory based on the Group DN and User or computer DN you have specified. remove_group_members
Remediation

Note: If the Active Directory connector does not find a record in AD, then the playbook displays the Record Not found in Active Directory message. This message is displayed if the search entity is not present in the AD Base DN configured in the Active Directory connector. You can use this message to formulate the condition in the playbook for the next playbook step.

operation: Global Search

Input parameters

Parameter Description
Object Type The object type, such as User, Computer, Group, or Person, based on which you want to search and retrieve records from AD.
Attribute Type The attribute type, such as SamAccount Name, DistinguishedName, Common Name, Display Name, or Email, based on which you want to search and retrieve records from AD.
Attribute Values The attribute value based on which you want to search and retrieve records from AD.
Page Size Number of record requests that should be included per page. By default, this is set as 0 i.e., no paging.
By default, Impact will ask only for one page from the LDAP server. If the LDAP server has a page size set to 1000, then only 1000 records will be returned.
Size Limit Number of records that should be returned in a single search. When you have enabled paging, i.e., set the Page Size parameter to some value, then this parameter has no effect. However, you must set the value of the Size Limit parameter to less than the value that you have set for Page Size.
For example, if you set page size to 100 and size limit to 90, the server will return 90 records.
By default, this is set as 0, i.e., none or no limit.
Paged Cookie (Optional) Value of an Opaque string, which if received in a paged search must be sent back while requesting subsequent entries of the search result.

Output

The JSON output contains the records based on the specified search object retrieved from AD. Each record contains its attributes such as user, group, computer, SamAccount Name, Distinguished Name, Display Name, and Given Name using which you can perform a global search in AD.

The output contains the following populated JSON schema:
{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
],
"cookie": ""
}

operation: Get All Objects Details

Input parameters

Parameter Description
Object Type The object type, such as User, Computer, Group, or Person, based on which you want to search and retrieve all records from AD.
Page Size Number of record requests that should be included per page. By default, this is set as 0 i.e., no paging.
By default, Impact will ask only for one page from the LDAP server. If the LDAP server has a page size set to 1000, then only 1000 records will be returned.
Size Limit Number of records that should be returned in a single search. When you have enabled paging, i.e., set the Page Size parameter to some value, then this parameter has no effect. However, you must set the value of the Size Limit parameter to less than the value that you have set for Page Size.
For example, if you set page size to 100 and size limit to 90, the server will return 90 records.
By default, this is set as 0, i.e., none or no limit.
Paged Cookie (Optional) Value of an Opaque string, which if received in a paged search must be sent back while requesting subsequent entries of the search result.

Output

The JSON output contains all existing records based on the specified search object retrieved from AD.

The output contains the following populated JSON schema:
{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
]
}

operation: Get Specific Object Details

Input parameters

Parameter Description
Object Type The object type, such as User, Computer, Group, or Person, based on which you want to search and retrieve records from AD.
If you select the Object Type as Person then you must also add the inputs for the CN and SN parameters.
SamAccount Name The SamAccountName of the object based on which you want to search and retrieve records from AD.
CN Common name of the Person you want to search and retrieve records from AD.
SN Surname of the Person you want to search and retrieve records from AD.

Output

The JSON output contains the records based on the name specified for the search object retrieved from AD.

The output contains the following populated JSON schema:
{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
]
}

operation: Enable User Account

Input parameters

Parameter Description
Attribute Type The attribute, either the SamAccount Name or the Email of the user, based on which you want to enable a user account in AD.
Attribute Value The value of the SamAccount Name or the Email of the user, based on which you want to enable a user account in AD.

Output

The JSON output contains a message stating whether or not the specified user account is enabled successfully

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Disable User Account

Input parameters

Parameter Description
Attribute Type The attribute, either the SamAccount Name or the Email of the user, based on which you want to disable a user account in AD.
Attribute Value The value of the SamAccount Name or the Email of the user, based on which you want to disable a user account in AD.

Output

The JSON output contains a message stating whether or not the specified user account is disabled successfully.

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Reset Password

Input parameters

Parameter Description
Attribute Type The attribute, either the SamAccount Name, Distinguished Name, or the Email of the user, whose password you want to reset in AD.
Attribute Value The value of the SamAccount Name, the Distinguished Name, or the Email of the user, whose password you want to reset in AD.
New Password The password that you want to set for the specific user.
The new password must meet the password policy requirements. For password policy requirements and the minimum password length, password complexity, and password history requirements, see https://www.grouppolicy.biz/2011/08/tutorial-how-to-setup-default-and-fine-grain-password-policy/.

Output

The JSON output contains a message stating whether or not the password is reset for the specified user account.

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Advanced Search

Input parameters

Parameter Description
LDAP Query The custom LDAP query based on which you want to retrieve records from AD.
Page Size Number of record requests that should be included per page. By default, this is set as 0 i.e., no paging.
By default, Impact will ask only for one page from the LDAP server. If the LDAP server has a page size set to 1000, then only 1000 records will be returned.
Size Limit Number of records that should be returned in a single search. When you have enabled paging, i.e., set the Page Size parameter to some value, then this parameter has no effect. However, you must set the value of the Size Limit parameter to less than the value that you have set for Page Size.
For example, if you set page size to 100 and size limit to 90, the server will return 90 records.
By default, this is set as 0, i.e., none or no limit.
Paged Cookie (Optional) Value of an Opaque string, which if received in a paged search must be sent back while requesting subsequent entries of the search result.

Output

The JSON output contains all the existing records based on the specified LDAP query retrieved from AD.

The output contains the following populated JSON schema:


{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
]
}

operation: Add Object

Input parameters

Parameter Description
Object Type Type of object whose entry you want to add in Active Directory. You can choose from the following options: User, Group, Computer or Organization Unit (OU).
If you choose User, then you must specify the following parameters:
  • User DN: Distinguished name of the user that you want to add in Active Directory.
  • SamAccount Name: sAMAccountName of the user object that you want to add in Active Directory.
  • Display Name: (Optional) Display name of the user object that you want to add in Active Directory.
  • Email Address: (Optional) Email address of the user object that you want to add in Active Directory.
  • Enable User: Select this checkbox, if you want to enable the user object in Active Directory. Clear this checkbox (default) if you want to disable the user object in Active directory.
  • User Principal Name: (Optional) Principal name of the user object that you want to add in Active Directory.
  • Title: (Optional) Title of the user object that you want to add in Active Directory.
  • Description: (Optional) Short description of the user object that you want to add in Active Directory.
If you choose Group, then you must specify the following parameters:
  • Group DN: Distinguished name of the group object that you want to add in Active Directory.
  • SamAccount Name: sAMAccountName of the group object that you want to add in Active Directory.
  • Group Type: (Optional) Type of group object you want to add in Active Directory. You can choose from the following options: Global Distribution Group, Domain Local Distribution Group, Universal Distribution Group, Global Security Group, Domain Local Security Group, or Universal Security Group.
If you choose Organization Unit, then you must specify the following parameters:
  • Organization DN: Distinguished name of the OU object that you want to add in Active Directory.
  • Description: (Optional) Short description of the OU object who you want to add in Active Directory.
If you choose Computer, then you must specify the following parameters:
  • Computer DN: Distinguished name of the computer object that you want to add in Active Directory.
  • SamAccount Name: sAMAccountName of the Compute object that you want to add in Active Directory.
  • Enable Computer: Select this checkbox, if you want to enable the computer object in Active Directory. Clear this checkbox (default) if you want to disable the computer object in Active directory.
  • Display Name: (Optional) Display name of the computer object that you want to add in Active Directory.
  • Description: (Optional) Short description of the computer object that you want to add in Active Directory.
Custom Attributes (Optional) Additional fields, in the JSON format, to add inthe object that you want to create Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Update Object

Input parameters

Parameter Description
Object Type Type of object whose entry you want to update in Active Directory. You can choose from the following options: User, Group, Computer or Organization Unit (OU).
If you choose User, then you must specify the following parameters:
  • User DN: Distinguished name of the user that you want to update in Active Directory.
  • SamAccount Name: (Optional) sAMAccountName of the user object that you want to update in Active Directory.
  • Display Name: (Optional) Display name of the user object that you want to update in Active Directory.
  • Email Address: (Optional) Email address of the user object that you want to update in Active Directory.
  • Enable User: Select this checkbox, if you want to enable the user object in Active Directory. Clear this checkbox (default) if you want to disable the user object in Active directory.
  • User Principal Name: (Optional) Principal name of the user object that you want to update in Active Directory.
  • Title: (Optional) Title of the user object that you want to update in Active Directory.
  • Description: (Optional) Short description of the user object that you want to update in Active Directory.
If you choose Group, then you must specify the following parameters:
  • Group DN: Distinguished name of the group object that you want to update in Active Directory.
  • SamAccount Name: sAMAccountName of the group object that you want to update in Active Directory.
  • Group Type: (Optional) Type of group object you want to update in Active Directory. You can choose from the following options: Global Distribution Group, Domain Local Distribution Group, Universal Distribution Group, Global Security Group, Domain Local Security Group, or Universal Security Group.
If you choose Organization Unit, then you must specify the following parameters:
  • Organization DN: Distinguished name of the OU object that you want to update in Active Directory.
  • Description: (Optional) Short description of the OU object who you want to update in Active Directory.
If you choose Computer, then you must specify the following parameters:
  • Computer DN: Distinguished name of the computer object that you want to update in Active Directory.
  • SamAccount Name: sAMAccountName of the Compute object that you want to update in Active Directory.
  • Enable Computer: Select this checkbox, if you want to enable the computer object in Active Directory. Clear this checkbox (default) if you want to disable the computer object in Active directory.
  • Display Name: (Optional) Display name of the computer object that you want to update in Active Directory.
  • Description: (Optional) Short description of the computer object that you want to update in Active Directory.
Custom Attributes (Optional) Additional fields, in the JSON format, to add or change in the object that you want to update Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Delete Object

Input parameters

Parameter Description
Object Type Type of object whose entry you want to delete from Active Directory. You can choose from the following options: User, Group, Computer or Organization Unit (OU).
Based on the type of object that you choose you must specify the following parameters:
  • Attributes Type:
    • If you choose User, then from the Attributes Type drop-down list, you can choose Distinguished Name, SamAccount Name or Email of the user object that you want to delete from Active Directory.
    • If you choose Group, then from the Attributes Type drop-down list, you can choose Distinguished Name or SamAccount Name of the computer object that you want to delete from Active Directory.
    • If you choose Computer, then from the Attributes Type drop-down list, you can choose Distinguished Name or SamAccount Name of the computer object that you want to delete from Active Directory.
    • If you choose Organization Unit, then you have to specify the Distinguished Name of the OU object that you want to delete from Active Directory.
  • Value: Value of the attribute type you have choosen.

Output

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Add Group Members

Input parameters

Parameter Description
Group DN List of Distinguished Names of the group in Active Directory to which you want to add members.
Note: You must enter DN values in the list format.
Object Type Type of object, User or Computer, that you want to add as members to the specified group in Active Directory.
If you choose Computer, then you must specify the following parameter:
  • Computer DN: List of Distinguished Name of the computer object that you want to add as a member to a group in Active Directory.
If you choose User, then you must specify the following parameter:
  • User DN: List of Distinguished Name of the user object that you want to add as a member to a group in Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"group_dn": [],
"type": "",
"referrals": null,
"dn": [],
"result": "",
"message": ""
}

operation: Remove Group Members

Input parameters

Parameter Description
Group DN List of Distinguished Names of the group in Active Directory from which you want to remove members.
Note: You must enter DN values in the list format.
Object Type Type of object, User or Computer, that you want to remove as members from the specified group in Active Directory.
If you choose Computer, then you must specify the following parameter:
  • Computer DN: List of Distinguished Name of the computer object that you want to remove as a member from a group in Active Directory.
If you choose User, then you must specify the following parameter:
  • User DN: List of Distinguished Name of the user object that you want to remove as a member from a group in Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"group_dn": [],
"type": "",
"referrals": null,
"dn": [],
"result": "",
"message": ""
}

Included playbooks

The Sample - ActiveDirectory - 2.1.0 playbook collection comes bundled with the Active Directory connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Active Directory connector.

  • Add Group Members
  • Add Object
  • Advanced Search
  • Delete Object
  • Disable User Account
  • Enable User Account
  • Get All Object Details
    • Get all Computers Details
    • Get all Groups Details
    • Get all Users Details
  • Get Specific Object Details
    • Get Specific Computer Details
    • Get Specific Group Details
    • Get Specific User Details
  • Remove Group Members
  • Reset Password
  • Global Search
    • Search by Common Name
    • Search by Distinguished Name
    • Search by Email
    • Search by SamAccount Name
  • Update Object

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Previous
Next

About the connector

Active Directory (AD) is a directory service that Microsoft developed for Windows domain networks. You can directly query AD to retrieve information about users, groups, and computers, in an organization, by using the Lightweight Directory Access Protocol (LDAP) to directly query the AD.

This document provides information about the Active Directory connector, which facilitates automated interactions with an Active Directory server using FortiSOAR™ playbooks. Add the Active Directory connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically retrieving all the information for users, groups, and computers in the AD and retrieving a list of search attributes that you can use to search AD.

Version information

Connector Version: 2.1.0

FortiSOAR™ Versions Tested on: 5.1.0-464

Authored By: Fortinet.

Certified: Yes

Release Notes for version 2.1.0

Following enhancements have been made to the Active Directory Connector in version 2.1.0:

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-activedirectory

For the detailed procedure to install a connector, click here

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Active Directory connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Hostname IP address or Hostname of the Active Directory (AD) server.
Port Port number used for connecting to the AD server.
Username Valid AD service account with a minimum of read access.
Password Password for your AD user.
Base DN The base, or node from where the LDAP search should start.
All connector operations are carried out using the Base DN as a root to the AD organization tree.
You can restrict the AD lookup by providing appropriate filters in this parameter. Some examples of the same are as follows:
DC=cspune,DC=com
OU=workstation,DC=cspune,DC=com
OU=Develop,OU=workstation,DC=cspune,DC=com
Bind DN The fully distinguished name that is used to bind to the LDAP server.
Use TLS Specifies whether SSL and TLS will be required to establish the connection between the Active Directory connector and the AD server.
By default, this option is set as false, and therefore, SSL is used by default.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Global Search Searches and retrieves records from AD using global search, based on the specified search object, such as user, computer, group, search attribute, or a search attribute value, such as SamAccount Name, Distinguished Name, Common Name, Display Name, or Email. When you search a record based on a search attribute value, the record from AD is retrieved based on the specified attribute value. search_query
Investigation
Get All Objects Details Searches and retrieves all records from AD based on a specified search object, such as user, computer, or group. search_query
Investigation
Get Specific Object Details Searches and retrieves records from AD based on a specified search object, such as user, computer, or group. However, this search is limited to the records found for the object name you have specified.
For example, if you want to retrieve the records from AD for a specific user, you need to specify the name of the user.		 search_query
Investigation
Enable User Account Enables the account of a specific AD user based on the SamAccount Name or the Email of the user. enable_user
Containment
Disable User Account Disables the account of a specific AD user based on the SamAccount Name or the Email of the user. disable_user
Containment
Reset Password Resets the password for a specific AD user based on the SamAccount Name or the Email, or the Distinguished Name (DN) of the user. reset_password
Containment
Advanced Search Executes an advanced LDAP query that searches and retrieves AD records based on your custom query. search_query
Investigation
Add Object Add an object entry of User, Group, Computer or Organization Unit (OU) type in Active Directory based on the type of object and other input parameters you have specified. add_object
Investigation
Update Object Updates an existing object entry of User, Group, Computer or Organization Unit (OU) type in Active Directory based on the type of object and other input parameters you have specified. update_update
Investigation
Delete Object Deletes an existing object entry of User, Group, Computer or Organization Unit (OU) type from Active Directory based on the type of object and other input parameters you have specified. delete_object
Containment
Add Group Members Adds an Active Directory User or Computer as a member to an existing Group in Active Directory based on the Group DN and User or computer DN you have specified. add_group_members
Investigation
Remove Group Members Removes an Active Directory User or Computer as a member from an existing Group in Active Directory based on the Group DN and User or computer DN you have specified. remove_group_members
Remediation

Note: If the Active Directory connector does not find a record in AD, then the playbook displays the Record Not found in Active Directory message. This message is displayed if the search entity is not present in the AD Base DN configured in the Active Directory connector. You can use this message to formulate the condition in the playbook for the next playbook step.

operation: Global Search

Input parameters

Parameter Description
Object Type The object type, such as User, Computer, Group, or Person, based on which you want to search and retrieve records from AD.
Attribute Type The attribute type, such as SamAccount Name, DistinguishedName, Common Name, Display Name, or Email, based on which you want to search and retrieve records from AD.
Attribute Values The attribute value based on which you want to search and retrieve records from AD.
Page Size Number of record requests that should be included per page. By default, this is set as 0 i.e., no paging.
By default, Impact will ask only for one page from the LDAP server. If the LDAP server has a page size set to 1000, then only 1000 records will be returned.
Size Limit Number of records that should be returned in a single search. When you have enabled paging, i.e., set the Page Size parameter to some value, then this parameter has no effect. However, you must set the value of the Size Limit parameter to less than the value that you have set for Page Size.
For example, if you set page size to 100 and size limit to 90, the server will return 90 records.
By default, this is set as 0, i.e., none or no limit.
Paged Cookie (Optional) Value of an Opaque string, which if received in a paged search must be sent back while requesting subsequent entries of the search result.

Output

The JSON output contains the records based on the specified search object retrieved from AD. Each record contains its attributes such as user, group, computer, SamAccount Name, Distinguished Name, Display Name, and Given Name using which you can perform a global search in AD.

The output contains the following populated JSON schema:
{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
],
"cookie": ""
}

operation: Get All Objects Details

Input parameters

Parameter Description
Object Type The object type, such as User, Computer, Group, or Person, based on which you want to search and retrieve all records from AD.
Page Size Number of record requests that should be included per page. By default, this is set as 0 i.e., no paging.
By default, Impact will ask only for one page from the LDAP server. If the LDAP server has a page size set to 1000, then only 1000 records will be returned.
Size Limit Number of records that should be returned in a single search. When you have enabled paging, i.e., set the Page Size parameter to some value, then this parameter has no effect. However, you must set the value of the Size Limit parameter to less than the value that you have set for Page Size.
For example, if you set page size to 100 and size limit to 90, the server will return 90 records.
By default, this is set as 0, i.e., none or no limit.
Paged Cookie (Optional) Value of an Opaque string, which if received in a paged search must be sent back while requesting subsequent entries of the search result.

Output

The JSON output contains all existing records based on the specified search object retrieved from AD.

The output contains the following populated JSON schema:
{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
]
}

operation: Get Specific Object Details

Input parameters

Parameter Description
Object Type The object type, such as User, Computer, Group, or Person, based on which you want to search and retrieve records from AD.
If you select the Object Type as Person then you must also add the inputs for the CN and SN parameters.
SamAccount Name The SamAccountName of the object based on which you want to search and retrieve records from AD.
CN Common name of the Person you want to search and retrieve records from AD.
SN Surname of the Person you want to search and retrieve records from AD.

Output

The JSON output contains the records based on the name specified for the search object retrieved from AD.

The output contains the following populated JSON schema:
{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
]
}

operation: Enable User Account

Input parameters

Parameter Description
Attribute Type The attribute, either the SamAccount Name or the Email of the user, based on which you want to enable a user account in AD.
Attribute Value The value of the SamAccount Name or the Email of the user, based on which you want to enable a user account in AD.

Output

The JSON output contains a message stating whether or not the specified user account is enabled successfully

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Disable User Account

Input parameters

Parameter Description
Attribute Type The attribute, either the SamAccount Name or the Email of the user, based on which you want to disable a user account in AD.
Attribute Value The value of the SamAccount Name or the Email of the user, based on which you want to disable a user account in AD.

Output

The JSON output contains a message stating whether or not the specified user account is disabled successfully.

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Reset Password

Input parameters

Parameter Description
Attribute Type The attribute, either the SamAccount Name, Distinguished Name, or the Email of the user, whose password you want to reset in AD.
Attribute Value The value of the SamAccount Name, the Distinguished Name, or the Email of the user, whose password you want to reset in AD.
New Password The password that you want to set for the specific user.
The new password must meet the password policy requirements. For password policy requirements and the minimum password length, password complexity, and password history requirements, see https://www.grouppolicy.biz/2011/08/tutorial-how-to-setup-default-and-fine-grain-password-policy/.

Output

The JSON output contains a message stating whether or not the password is reset for the specified user account.

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Advanced Search

Input parameters

Parameter Description
LDAP Query The custom LDAP query based on which you want to retrieve records from AD.
Page Size Number of record requests that should be included per page. By default, this is set as 0 i.e., no paging.
By default, Impact will ask only for one page from the LDAP server. If the LDAP server has a page size set to 1000, then only 1000 records will be returned.
Size Limit Number of records that should be returned in a single search. When you have enabled paging, i.e., set the Page Size parameter to some value, then this parameter has no effect. However, you must set the value of the Size Limit parameter to less than the value that you have set for Page Size.
For example, if you set page size to 100 and size limit to 90, the server will return 90 records.
By default, this is set as 0, i.e., none or no limit.
Paged Cookie (Optional) Value of an Opaque string, which if received in a paged search must be sent back while requesting subsequent entries of the search result.

Output

The JSON output contains all the existing records based on the specified LDAP query retrieved from AD.

The output contains the following populated JSON schema:


{
"entries": [
{
"dn": "",
"attributes": {
"lastLogoff": "",
"objectGUID": "",
"objectSid": "",
"distinguishedName": "",
"sAMAccountType": "",
"accountExpires": "",
"sAMAccountName": "",
"whenChanged": "",
"lastLogon": "",
"userAccountControl": "",
"pwdLastSet": "",
"cn": "",
"name": "",
"userPrincipalName": "",
"logonCount": ""
}
}
]
}

operation: Add Object

Input parameters

Parameter Description
Object Type Type of object whose entry you want to add in Active Directory. You can choose from the following options: User, Group, Computer or Organization Unit (OU).
If you choose User, then you must specify the following parameters:
  • User DN: Distinguished name of the user that you want to add in Active Directory.
  • SamAccount Name: sAMAccountName of the user object that you want to add in Active Directory.
  • Display Name: (Optional) Display name of the user object that you want to add in Active Directory.
  • Email Address: (Optional) Email address of the user object that you want to add in Active Directory.
  • Enable User: Select this checkbox, if you want to enable the user object in Active Directory. Clear this checkbox (default) if you want to disable the user object in Active directory.
  • User Principal Name: (Optional) Principal name of the user object that you want to add in Active Directory.
  • Title: (Optional) Title of the user object that you want to add in Active Directory.
  • Description: (Optional) Short description of the user object that you want to add in Active Directory.
If you choose Group, then you must specify the following parameters:
  • Group DN: Distinguished name of the group object that you want to add in Active Directory.
  • SamAccount Name: sAMAccountName of the group object that you want to add in Active Directory.
  • Group Type: (Optional) Type of group object you want to add in Active Directory. You can choose from the following options: Global Distribution Group, Domain Local Distribution Group, Universal Distribution Group, Global Security Group, Domain Local Security Group, or Universal Security Group.
If you choose Organization Unit, then you must specify the following parameters:
  • Organization DN: Distinguished name of the OU object that you want to add in Active Directory.
  • Description: (Optional) Short description of the OU object who you want to add in Active Directory.
If you choose Computer, then you must specify the following parameters:
  • Computer DN: Distinguished name of the computer object that you want to add in Active Directory.
  • SamAccount Name: sAMAccountName of the Compute object that you want to add in Active Directory.
  • Enable Computer: Select this checkbox, if you want to enable the computer object in Active Directory. Clear this checkbox (default) if you want to disable the computer object in Active directory.
  • Display Name: (Optional) Display name of the computer object that you want to add in Active Directory.
  • Description: (Optional) Short description of the computer object that you want to add in Active Directory.
Custom Attributes (Optional) Additional fields, in the JSON format, to add inthe object that you want to create Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Update Object

Input parameters

Parameter Description
Object Type Type of object whose entry you want to update in Active Directory. You can choose from the following options: User, Group, Computer or Organization Unit (OU).
If you choose User, then you must specify the following parameters:
  • User DN: Distinguished name of the user that you want to update in Active Directory.
  • SamAccount Name: (Optional) sAMAccountName of the user object that you want to update in Active Directory.
  • Display Name: (Optional) Display name of the user object that you want to update in Active Directory.
  • Email Address: (Optional) Email address of the user object that you want to update in Active Directory.
  • Enable User: Select this checkbox, if you want to enable the user object in Active Directory. Clear this checkbox (default) if you want to disable the user object in Active directory.
  • User Principal Name: (Optional) Principal name of the user object that you want to update in Active Directory.
  • Title: (Optional) Title of the user object that you want to update in Active Directory.
  • Description: (Optional) Short description of the user object that you want to update in Active Directory.
If you choose Group, then you must specify the following parameters:
  • Group DN: Distinguished name of the group object that you want to update in Active Directory.
  • SamAccount Name: sAMAccountName of the group object that you want to update in Active Directory.
  • Group Type: (Optional) Type of group object you want to update in Active Directory. You can choose from the following options: Global Distribution Group, Domain Local Distribution Group, Universal Distribution Group, Global Security Group, Domain Local Security Group, or Universal Security Group.
If you choose Organization Unit, then you must specify the following parameters:
  • Organization DN: Distinguished name of the OU object that you want to update in Active Directory.
  • Description: (Optional) Short description of the OU object who you want to update in Active Directory.
If you choose Computer, then you must specify the following parameters:
  • Computer DN: Distinguished name of the computer object that you want to update in Active Directory.
  • SamAccount Name: sAMAccountName of the Compute object that you want to update in Active Directory.
  • Enable Computer: Select this checkbox, if you want to enable the computer object in Active Directory. Clear this checkbox (default) if you want to disable the computer object in Active directory.
  • Display Name: (Optional) Display name of the computer object that you want to update in Active Directory.
  • Description: (Optional) Short description of the computer object that you want to update in Active Directory.
Custom Attributes (Optional) Additional fields, in the JSON format, to add or change in the object that you want to update Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Delete Object

Input parameters

Parameter Description
Object Type Type of object whose entry you want to delete from Active Directory. You can choose from the following options: User, Group, Computer or Organization Unit (OU).
Based on the type of object that you choose you must specify the following parameters:
  • Attributes Type:
    • If you choose User, then from the Attributes Type drop-down list, you can choose Distinguished Name, SamAccount Name or Email of the user object that you want to delete from Active Directory.
    • If you choose Group, then from the Attributes Type drop-down list, you can choose Distinguished Name or SamAccount Name of the computer object that you want to delete from Active Directory.
    • If you choose Computer, then from the Attributes Type drop-down list, you can choose Distinguished Name or SamAccount Name of the computer object that you want to delete from Active Directory.
    • If you choose Organization Unit, then you have to specify the Distinguished Name of the OU object that you want to delete from Active Directory.
  • Value: Value of the attribute type you have choosen.

Output

The output contains the following populated JSON schema:
{
"description": "",
"type": "",
"referrals": "",
"dn": "",
"result": "",
"message": ""
}

operation: Add Group Members

Input parameters

Parameter Description
Group DN List of Distinguished Names of the group in Active Directory to which you want to add members.
Note: You must enter DN values in the list format.
Object Type Type of object, User or Computer, that you want to add as members to the specified group in Active Directory.
If you choose Computer, then you must specify the following parameter:
  • Computer DN: List of Distinguished Name of the computer object that you want to add as a member to a group in Active Directory.
If you choose User, then you must specify the following parameter:
  • User DN: List of Distinguished Name of the user object that you want to add as a member to a group in Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"group_dn": [],
"type": "",
"referrals": null,
"dn": [],
"result": "",
"message": ""
}

operation: Remove Group Members

Input parameters

Parameter Description
Group DN List of Distinguished Names of the group in Active Directory from which you want to remove members.
Note: You must enter DN values in the list format.
Object Type Type of object, User or Computer, that you want to remove as members from the specified group in Active Directory.
If you choose Computer, then you must specify the following parameter:
  • Computer DN: List of Distinguished Name of the computer object that you want to remove as a member from a group in Active Directory.
If you choose User, then you must specify the following parameter:
  • User DN: List of Distinguished Name of the user object that you want to remove as a member from a group in Active Directory.

Output

The output contains the following populated JSON schema:
{
"description": "",
"group_dn": [],
"type": "",
"referrals": null,
"dn": [],
"result": "",
"message": ""
}

Included playbooks

The Sample - ActiveDirectory - 2.1.0 playbook collection comes bundled with the Active Directory connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Active Directory connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Previous
Next