Active Directory

Integration version: 34.0

Note: This integration uses one or more open source components. You can download a copy of the full source code of this integration from the storage bucket.

Configure Active Directory integration

Configure Active Directory integration with a CA certificate

You can verify your connection with a CA certificate file if needed.

Before you start, ensure you have the following:

• The CA certificate file
• The latest Active Directory integration version

To configure the integration with a CA certificate, complete the following steps:

1. Add the IP address of the Active Directory machine to the /etc/hosts file, with the hostname, in order for the Google Security Operations SOAR instance to successfully map between the hostname and IP address.

   Use the sudo vi /etc/hosts/ command to edit the file.

   Add the IP address of the Active Directory machine, and right after it the hostname, so that the integration configuration with the hostname can work. For example: 1172.30.202.195 ADCA01.exlab.local

2. Encode the root CA certificate file you have to Base64, including the Begin and End strings, like this:

   -----BEGIN CERTIFICATE-----
   <certificate string>
   -----END CERTIFICATE-----
   

3. Find the hostname of your Active Directory server in order to use it in the integration configuration page, instead of IP address.

4. Enter the obtained parameters on the integration configuration page as follows:

   • Server: hostname
   • CA Certificate File - parsed into Base64 String: encoded certificate

5. To test the setup, click Test.

Configure Active Directory integration in Google Security Operations SOAR

For detailed instructions about how to configure an integration in Google Security Operations SOAR, see Configure integrations.

Integration parameters

Use the following parameters to configure the integration:

Parameter name	Type	Default value	Is mandatory	Description
Instance Name	String	N/A	No	Name of the Instance you intend to configure integration for.
Description	String	N/A	No	Description of the Instance.
Server	String	x.x.x.x	Yes	IP address of the Active Directory server.
Username	String	[e-mail]	Yes	The email address of the user which should be used to connect to Active Directory.
Domain	String	example.com	Yes	Domain of the user. Example: If the email address of the user is [e-mail], the domain is example.com.
Password	Password	N/A	Yes	The password of the user account.
Custom Fields	String	customField1, customField2	No	Custom fields of the Active Directory integration.
CA Certificate File - parsed into Base64 String	String	N/A	No	When providing the CA certificate file string, pay attention to include only the public key there. The integration converts the string to a .pem file in order to use it.
Use SSL	Checkbox	Unchecked	No	Use this checkbox if your Active Directory connection requires an SSL verification.
Run Remotely	Checkbox	Unchecked	No	Check the field in order to run the configured integration remotely. After checked, the option appears to select the remote user (agent).

Note: You can make changes at a later stage if needed. Once configured, the Instances can be used in Playbooks. For detailed information on configuring and supporting multiple instances, see Supporting multiple instances.

Actions

Add User to Group

Description

Add user to groups.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Group Name	String	N/A	Yes	Specify a comma-separated list of groups to which the action should add users.

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Case wall

Case	Success	Fail	Message
Added to one group	true	false	Successfully added the following users to group "{Group Name}" in Active Directory: {entity identifier}
Already a part of one group	true	false	The following users were already a part of group "{Group Name}" in Active Directory: {entity identifier}
Not successful for one group	true	false	Action wasn't able to add the following users to group "{Group Name}" in Active Directory: {entity identifier}.
If all users not added for one group	True	False	No users were added to group "{Group Name}" in Active Directory.
If all users not added for all groups	false	false	No users were added to the provided groups in Active Directory.
If at least one group doesn't exist	false	true	Error executing action: {action name}. The following groups were not found: {group names}.

Change Host OU

Description

Change a Host's Organizational Unit (OU).

Parameters

Parameter name	Type	Default value	Is mandatory	Description
OU Name	String	N/A	Yes	The name of the new user's OU.

Run on

This action runs on the Hostname entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Change User OU

Description

Change a user's Organizational Unit (OU).

Parameters

Parameter name	Type	Default value	Is mandatory	Description
OU Name	String	N/A	Yes	The name of the new user's OU.

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Disable Account

Description

Disable the user account.

Parameters

N/A

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Disable computer

Description

Disable a computer account.

Parameters

N/A

Run on

This action runs on the Hostname entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Enable Account

Description

Enable the user account.

Parameters

N/A

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Enable Computer

Description

Enable a computer account.

Parameters

N/A

Run on

This action runs on the Hostname entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Enrich Entities

Description

Enrich Hostname or Username entities with Active Directory properties

Note: This action is running asynchronously. If necessary, adjust script timeout value in the Google Security Operations SOAR IDE for the action.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Mark entities as internal	Checkbox	Unchecked	Yes	Specify whether successfully enriched entities should be automatically marked as Internal Entity.

Run on

This action runs on the following entities:

• User
• Hostname

Action results

Entity enrichment

Enrichment field name	Logic - When to apply
AD_primaryGroupID	Returns if it exists in JSON result
AD_logonCount	Returns if it exists in JSON result
AD_cn	Returns if it exists in JSON result
AD_countryCode	Returns if it exists in JSON result
AD_objectClass	Returns if it exists in JSON result
AD_userPrincipalName	Returns if it exists in JSON result
AD_adminCount	Returns if it exists in JSON result
AD_lastLogonTimestamp	Returns if it exists in JSON result
AD_manager	Returns if it exists in JSON result
AD_instanceType	Returns if it exists in JSON result
AD_distinguishedName	Returns if it exists in JSON result
AD_dSCorePropagationData	Returns if it exists in JSON result
AD_msDS-SupportedEncryptionTypes	Returns if it exists in JSON result
AD_objectSid	Returns if it exists in JSON result
AD_whenCreated	Returns if it exists in JSON result
AD_uSNCreated	Returns if it exists in JSON result
AD_lockoutTime	Returns if it exists in JSON result
AD_badPasswordTime	Returns if it exists in JSON result
AD_pwdLastSet	Returns if it exists in JSON result
AD_sAMAccountName	Returns if it exists in JSON result
AD_objectCategory	Returns if it exists in JSON result
AD_lastLogon	Returns if it exists in JSON result
AD_objectGUID	Returns if it exists in JSON result
AD_whenChanged	Returns if it exists in JSON result
AD_badPwdCount	Returns if it exists in JSON result
AD_accountExpires	Returns if it exists in JSON result
AD_displayName	Returns if it exists in JSON result
AD_name	Returns if it exists in JSON result
AD_memberOf	Returns if it exists in JSON result
AD_codePage	Returns if it exists in JSON result
AD_userAccountControl	Returns if it exists in JSON result
AD_sAMAccountType	Returns if it exists in JSON result
AD_uSNChanged	Returns if it exists in JSON result
AD_sn	Returns if it exists in JSON result
AD_givenName	Returns if it exists in JSON result
AD_lastLogoff	Returns if it exists in JSON result

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

JSON result

[
    {
        "EntityResult": {
            "primaryGroupID": [513],
            "logonCount": [6505],
            "cn": ["user name"],
            "countryCode": [0],
            "objectClass": ["top", "person", "organizationalPerson"],
            "userPrincipalName": ["[e-mail]"],
            "adminCount": [1],
            "lastLogonTimestamp": ["2019-01-09 08:42:03.540783+00:00"],
            "manager": ["CN=user name,OU=R&D,OU=TLV,OU=host name,DC=domain,DC=LOCAL"],
            "instanceType": [4],
            "distinguishedName": ["CN=user name,OU=R&D,OU=TLV,OU=host,DC=domain,DC=LOCAL"],
            "dSCorePropagationData": ["2019-01-14 14:39:16+00:00"],
            "msDS-SupportedEncryptionTypes": [0],
            "objectSid": ["id"],
            "whenCreated": ["2011-11-07 08:00:44+00:00"],
            "uSNCreated": [7288202],
            "lockoutTime": ["1601-01-01 00:00:00+00:00"],
            "badPasswordTime": ["date"],
            "pwdLastSet": ["date"],
            "sAMAccountName": ["name"],
            "objectCategory": ["CN=Person,CN=Schema,CN=Configuration,DC=host,DC=LOCAL"],
            "lastLogon": ["2019-01-14 17:13:54.463070+00:00"],
            "objectGUID": ["{id}"],
            "whenChanged": ["2019-01-14 16:49:01+00:00"],
            "badPwdCount": [1],
            "accountExpires": ["9999-12-31 23:59:59.999999"],
            "displayName": ["user display name"],
            "name": ["user name"],
            "memberOf": ["CN=\\\\u05e7\\\\u05d1\\\\u05d5\\\\u05e6\\\\u05d4 \\\\u05d1\\\\u05e2\\\\u05d1\\\\u05e8\\\\u05d9\\\\u05ea,OU=TEST,OU=QA,OU=IT,OU=TLV,OU=host,DC=domain,DC=LOCAL", "CN=Organization Management,OU=Microsoft Exchange Security Groups,DC=domain,DC=LOCAL", "CN=Local Admin,OU=Groups,OU=IT,OU=TLV,OU=host,DC=domain,DC=LOCAL"],
            "codePage": [0],
            "userAccountControl": [111],
            "sAMAccountType": [805306368],
            "uSNChanged": [15301168],
            "sn": ["last name"],
            "givenName": ["name"],
            "lastLogoff": ["1601-01-01 00:00:00+00:00"
                          ]},
        "Entity": "[e-mail]"
    }
]

Force Password Update

Description

Force the user's password to update on the next logon.

Parameters

N/A

Run On

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Get Manager Contact Details

Description

Get manager's contact details from Active Directory.

Parameters

N/A

Run on

This action runs on the User entity.

Action results

Entity enrichment

Enrichment field name	Logic - When to apply
AD_Manager_Name	Returns if it exists in JSON result
AD_Manager_phone	Returns if it exists in JSON result
AD_primaryGroupID	Returns if it exists in JSON result
AD_logonCount	Returns if it exists in JSON result
AD_cn	Returns if it exists in JSON result
AD_countryCode	Returns if it exists in JSON result
AD_objectClass	Returns if it exists in JSON result
AD_userPrincipalName	Returns if it exists in JSON result
AD_adminCount	Returns if it exists in JSON result
AD_lastLogonTimestamp	Returns if it exists in JSON result
AD_manager	Returns if it exists in JSON result
AD_instanceType	Returns if it exists in JSON result
AD_distinguishedName	Returns if it exists in JSON result
AD_dSCorePropagationData	Returns if it exists in JSON result
AD_msDS-SupportedEncryptionTypes	Returns if it exists in JSON result
AD_objectSid	Returns if it exists in JSON result
AD_whenCreated	Returns if it exists in JSON result
AD_uSNCreated	Returns if it exists in JSON result
AD_lockoutTime	Returns if it exists in JSON result
AD_badPasswordTime	Returns if it exists in JSON result
AD_pwdLastSet	Returns if it exists in JSON result
AD_sAMAccountName	Returns if it exists in JSON result
AD_objectCategory	Returns if it exists in JSON result
AD_lastLogon	Returns if it exists in JSON result
AD_objectGUID	Returns if it exists in JSON result
AD_whenChanged	Returns if it exists in JSON result
AD_badPwdCount	Returns if it exists in JSON result
AD_accountExpires	Returns if it exists in JSON result
AD_displayName	Returns if it exists in JSON result
AD_name	Returns if it exists in JSON result
AD_memberOf	Returns if it exists in JSON result
AD_codePage	Returns if it exists in JSON result
AD_userAccountControl	Returns if it exists in JSON result
AD_sAMAccountType	Returns if it exists in JSON result
AD_uSNChanged	Returns if it exists in JSON result
AD_sn	Returns if it exists in JSON result
AD_givenName	Returns if it exists in JSON result
AD_lastLogoff	Returns if it exists in JSON result

Script result

Script result name	Value options	Example
ScriptResultName	N/A	N/A

JSON result

{
        "EntityResult":
        {
            "primaryGroupID": [513],
            "logonCount": [6505],
            "cn": ["user name"],
            "countryCode": [0],
            "objectClass": ["top", "person", "organizationalPerson"],
            "userPrincipalName": ["[e-mail]"],
            "adminCount": [1],
            "lastLogonTimestamp": ["2019-01-09 08:42:03.540783+00:00"],
            "manager": ["CN=user name,OU=R&D,OU=TLV,OU=host name,DC=domain,DC=LOCAL"],
            "instanceType": [4],
            "distinguishedName": ["CN=user name,OU=R&D,OU=TLV,OU=host,DC=domain,DC=LOCAL"],
            "dSCorePropagationData": ["2019-01-14 14:39:16+00:00"],
            "msDS-SupportedEncryptionTypes": [0],
            "objectSid": ["id"],
            "whenCreated": ["2011-11-07 08:00:44+00:00"],
            "uSNCreated": [7288202],
            "lockoutTime": ["1601-01-01 00:00:00+00:00"],
            "badPasswordTime": ["date"],
            "pwdLastSet": ["date"],
            "sAMAccountName": ["name"],
            "objectCategory": ["CN=Person,CN=Schema,CN=Configuration,DC=host,DC=LOCAL"],
            "lastLogon": ["2019-01-14 17:13:54.463070+00:00"],
            "objectGUID": ["{id}"],
            "whenChanged": ["2019-01-14 16:49:01+00:00"],
            "badPwdCount": [1],
            "accountExpires": ["9999-12-31 23:59:59.999999"],
            "displayName": ["user display name"],
            "name": ["user name"],
            "memberOf": ["CN= u05e7 u05d1 u05d5 u05e6 u05d4  u05d1 u05e2 u05d1 u05e8 u05d9 u05ea,OU=TEST,OU=QA,OU=IT,OU=TLV,OU=host,DC=domain,DC=LOCAL", "CN=Organization Management,OU=Microsoft Exchange Security Groups,DC=domain,DC=LOCAL", "CN=Local Admin,OU=Groups,OU=IT,OU=TLV,OU=host,DC=domain,DC=LOCAL"],
            "codePage": [0],
            "userAccountControl": [111],
            "sAMAccountType": [805306368],
            "uSNChanged": [15301168],
            "sn": ["last name"],
            "givenName": ["name"],
            "lastLogoff": ["1601-01-01 00:00:00+00:00"]
        },
        "Entity": "[e-mail]"
    }
]

Case wall

Result type	Description	Type
Output message*	If all entities ware enriched: "all entities were processed successfully" If some entities aren't enriched: "some entities were processed successfully and some weren't. Please check action's log for further information"(Note - please make sure to include the appropriate logs in the log file) If no entity is enriched: "No entities were processed"	General

Is User in Group

Description

Check if a user is a member of a specific group.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Group Name	String	N/A	Yes	Group name to be checked. Example: administrators

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

JSON result

[
    {
        "EntityResult": true,
        "Entity": "[e-mail]"
    }, {
        "EntityResult": false,
        "Entity": "[e-mail]"
    }, {
        "EntityResult": true,
        "Entity": "[e-mail]"
    }
]

List User Groups

Description

Get a list of all the user groups in Active Directory.

Parameters

N/A

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

JSON result

[
    {
        "EntityResult": ["Domain Users"],
        "Entity": "[e-mail]"
    }
]

Ping

Description

Test connectivity to Active Directory with parameters provided at the integration configuration page in the Google Security Operations Marketplace tab.

Parameters

N/A

Run on

This action runs on all entities.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Release Locked Account

Description

Release a locked account.

Parameters

N/A

Run On

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Remove User From Group

Description

Remove user from groups.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Group Name	String	N/A	Yes	Specify a comma-separated list of groups from which the action should remove users.

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Case wall

Case	Success	Fail	Message
Remove one from one group	true	false	Successfully removed the following users from group "{Group Name}" in Active Directory: {entity identifier}
Already not a part of one group	true	false	The following users were not a part of the group "{Group Name}" in Active Directory: {entity identifier}
Not successful for one group	true	false	Action wasn't able to remove the following users from group "{Group Name}" in Active Directory: {entity identifier}.
If all users not added for one group	True	False	No users were remove from group "{Group Name}" in Active Directory.
If all users not added for all groups	false	false	No users were removed from the provided groups in Active Directory.
If at least one group doesn't exist	false	true	Error executing action: {action name}. The following groups were not found: {group names}.

Search Active Directory

Description

Search Active Directory with Google Security Operations SOAR, using your personal query.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Query String	String	N/A	Yes	Specify the query string you would like to perform in Active Directory.

Run on

This action doesn't run on entities.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

JSON result

[
      {
        "primaryGroupID": [
          513
        ],
        "logonCount": [
          6505
        ],
        "cn": [
          "user name"
        ],
        "countryCode": [
          0
        ],
        "objectClass": [
          "top",
          "person",
          "organizationalPerson"
        ],
        "userPrincipalName": [
          "[e-mail]"
        ],
        "adminCount": [
          1
        ],
        "lastLogonTimestamp": [
          "2019-01-09 08:42:03.540783+00:00"
        ],
        "manager": [
          "CN=user name,OU=R&D,OU=TLV,OU=host name,DC=domain,DC=LOCAL"
        ],
        "instanceType": [
          4
        ],
        "distinguishedName": [
          "CN=user name,OU=R&D,OU=TLV,OU=host,DC=domain,DC=LOCAL"
        ],
        "dSCorePropagationData": [
          "2019-01-14 14:39:16+00:00"
        ],
        "msDS-SupportedEncryptionTypes": [
          0
        ],
        "objectSid": [
          "id"
        ],
        "whenCreated": [
          "2011-11-07 08:00:44+00:00"
        ],
        "uSNCreated": [
          7288202
        ],
        "lockoutTime": [
          "1601-01-01 00:00:00+00:00"
        ],
        "badPasswordTime": [
          "date"
        ],
        "pwdLastSet": [
          "date"
        ],
        "sAMAccountName": [
          "name"
        ],
        "objectCategory": [
          "CN=Person,CN=Schema,CN=Configuration,DC=host,DC=LOCAL"
        ],
        "lastLogon": [
          "2019-01-14 17:13:54.463070+00:00"
        ],
        "objectGUID": [
          "{id}"
        ],
        "whenChanged": [
          "2019-01-14 16:49:01+00:00"
        ],
        "badPwdCount": [
          1
        ],
        "accountExpires": [
          "9999-12-31 23:59:59.999999"
        ],
        "displayName": [
          "user display name"
        ],
        "name": [
          "user name"
        ],
        "memberOf": [
          "CN=\\\\u05e7\\\\u05d1\\\\u05d5\\\\u05e6\\\\u05d4 \\\\u05d1\\\\u05e2\\\\u05d1\\\\u05e8\\\\u05d9\\\\u05ea,OU=TEST,OU=QA,OU=IT,OU=TLV,OU=host,DC=domain,DC=LOCAL",
          "CN=Organization Management,OU=Microsoft Exchange Security Groups,DC=domain,DC=LOCAL",
          "CN=Local Admin,OU=Groups,OU=IT,OU=TLV,OU=host,DC=domain,DC=LOCAL"
        ],
        "codePage": [
          0
        ],
        "userAccountControl": [
          111
        ],
        "sAMAccountType": [
          805306368
        ],
        "uSNChanged": [
          15301168
        ],
        "sn": [
          "last name"
        ],
        "givenName": [
          "name"
        ],
        "lastLogoff": [
          "1601-01-01 00:00:00+00:00"
        ]
      }
    ]

Case wall

Result type	Description	Type
Output message*	The action should not fail nor stop a playbook execution: If successful:"Successfully performed query "+query_string+" in Active Directory" If not successful (query that resulted with an empty response): "No results to show following the query:"+query_string The action should fail and stop a playbook execution: If not successful (bad creds, connection error, data is not returned because of invalid query): "Error executing action "Search Active Directory". Reason: {0}''.format(error.Stacktrace)	General

Set User Password

Description

Set a user's password.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
New Password	String	N/A	Yes	N/A

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Update attributes of an AD User

Description

Updates attributes of an existing Active Directory Users.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Attribute Name	String	N/A	Yes	The name of the attribute to update. Example: Description
Attribute Value	String	N/A	Yes	Specify a new value for the attribute.

Run on

This action runs on the User entity.

Action results

Script result

Script result name	Value options	Example
is_success	True or False	is_success:False

Case wall

Result type	Description	Type
Output message*	If the action completed successfully for at least one of the entities: "Active Directory - Following entities were updated successfully: {entities identifiers} If there are no users to removed: "No suitable entities were found" If the action failed to run for at least one of the entities: "failed to update {attribute name} for the following entities: {}"	General

Update attributes of an AD Host

Description

Updates attributes of an existing Active Directory hosts.

Parameters

Parameter name	Type	Default value	Is mandatory	Description
Attribute Name	String	N/A	Yes	The name of the attribute to update. Example: Description
Attribute Value	String	N/A	Yes	Specify a new value for the attribute.

Run on

This action runs on the Hostname entity.

Action results

Script result

Script result name	Value Options	Example
is_success	True or False	is_success:False

Case wall

Result type	Description	Type
Output message*	If action completed successfully for at least one of the entities: "Active Directory - Following entities were updated successfully: {entities identifiers}." If there are no users to removed: "No suitable entities were found" If action failed to run for at least one of the entities: "Failed to update {attribute name} for the following entities: {};"	General