-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #50 from splunk-soar-connectors/next
Merging next to main for release 4.0.0
- Loading branch information
Showing
12 changed files
with
492 additions
and
289 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,11 +2,11 @@ | |
# MS Graph for Office 365 | ||
|
||
Publisher: Splunk | ||
Connector Version: 3.1.1 | ||
Connector Version: 4.0.0 | ||
Product Vendor: Microsoft | ||
Product Name: Office 365 (MS Graph) | ||
Product Version Supported (regex): ".\*" | ||
Minimum Product Version: 6.2.2 | ||
Minimum Product Version: 6.3.0 | ||
|
||
This app connects to Office 365 using the MS Graph API to support investigate and generic actions related to the email messages and calendar events | ||
|
||
|
@@ -49,9 +49,21 @@ On the next page, select **New registration** and give your app a name. | |
|
||
Once the app is created, follow the below-mentioned steps: | ||
|
||
- Under **Certificates & secrets** select **New client secret** . Enter the **Description** and | ||
select the desired duration in **Expires** . Click on **Add** . Note down this **value** | ||
somewhere secure, as it cannot be retrieved after closing the window. | ||
- For authentication using a client secret(OAuth): | ||
|
||
- Under **Certificates & secrets** select **New client secret** . Enter the **Description** and | ||
select the desired duration in **Expires** . Click on **Add** . Note down this **value** | ||
somewhere secure, as it cannot be retrieved after closing the window. | ||
|
||
- For authentication using certificate based authentication(CBA): | ||
|
||
- Under **Certificates & secrets** select **Certificates** then **Upload Certificate** . | ||
Select the certifitcate file to upload (.crt/.pem) and enter the **Description** . Note down | ||
the **thumbprint** as this will be used to configure the asset. ([Certificate Requirements](https://learn.microsoft.com/en-us/azure/databox-online/azure-stack-edge-gpu-certificate-requirements)) | ||
- Generate private key: | ||
- `openssl genpkey -algorithm RSA -out private_key.pem` / `openssl genrsa -out private_key.pem 2048` | ||
- Generate certificate from the private key (Valid for 365 days): | ||
- `openssl req -new -x509 -key private_key.pem -out certificate.pem -days 365` | ||
|
||
- Under **Authentication** , select **Add a platform** . In the **Add a platform** window, select | ||
**Web** . The **Redirect URLs** should be filled right here. We will get **Redirect URLs** from | ||
|
@@ -71,8 +83,6 @@ Once the app is created, follow the below-mentioned steps: | |
|
||
- User.Read.All (https://graph.microsoft.com/User.Read.All) | ||
|
||
|
||
- For non-admin access, use User.Read (Delegated permission) instead | ||
(https://graph.microsoft.com/User.Read) | ||
|
||
|
@@ -91,6 +101,7 @@ Once the app is created, follow the below-mentioned steps: | |
|
||
- MailboxSettings.Read (https://graph.microsoft.com/MailboxSettings.Read) - It is required | ||
only if you want to run the **oof status** , **list rules** and **get rule** actions. | ||
- For CBA Authentication, [Application-only access](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes) permissions are required. | ||
|
||
After making these changes, click **Add permissions** , then select **Grant admin consent for | ||
\<your_organization_name_as_on_azure_portal>** at the bottom of the screen. | ||
|
@@ -137,7 +148,7 @@ the window. To give this user permission to view assets, follow these steps: | |
|
||
### Test connectivity | ||
|
||
#### Admin User Workflow | ||
#### Admin User Workflow (OAuth) | ||
|
||
- Configure the asset with required details while keeping the **Admin Access Required** as | ||
checked. | ||
|
@@ -160,7 +171,7 @@ the window. To give this user permission to view assets, follow these steps: | |
config parameter as checked. This will skip the interactive flow and use the client credentials | ||
for generating tokens. | ||
|
||
#### Non-Admin User Workflow | ||
#### Non-Admin User Workflow (OAuth) | ||
|
||
- Configure the asset with required details while keeping the **Admin Access Required** as | ||
unchecked. **Admin Consent Already Provided** config parameter will be ignored in the non-admin | ||
|
@@ -181,8 +192,21 @@ the window. To give this user permission to view assets, follow these steps: | |
- Now go back and check the message on the Test Connectivity dialog box, it should say **Test | ||
Connectivity Passed** . | ||
|
||
|
||
|
||
#### Certificate Based Authentication Workflow (CBA) | ||
|
||
- Configure the asset with **Tenant ID**, **Application ID**, **Certificate Thumbprint** and | ||
the **Certificate Private Key (.PEM).** | ||
- Ensure **Admin Consent Already Provided** is checked. | ||
- After setting up the asset and user, click the **TEST CONNECTIVITY** button. | ||
- Check the message in the Test Connectivity dialog box. it should say **Test | ||
Connectivity Passed** . | ||
|
||
#### Automatic Authentication Workflow | ||
|
||
- Configure the asset with the required details, including either the **Application Secret** or a combination of **Certificate Thumbprint** and **Certificate Private Key (.PEM)**. | ||
- If **Application Secret** exists, it will take priority and follow the OAuth workflow. Otherwise, it will continue with the CBA workflow. | ||
- The system doesn’t automatically switch from OAuth to CBA when the **Application Secret** expires. However, if **Admin Access Required** is disabled, **Access Scope** is not specified, and **Admin Consent Already Provided** is enabled, it will switch to CBA upon **Application Secret** expiration. | ||
|
||
The app should now be ready to be used. | ||
|
||
### On-Poll | ||
|
@@ -299,22 +323,23 @@ ports used by the Splunk SOAR Connector. | |
| https | tcp | 443 | | ||
|
||
|
||
### Configuration Variables | ||
The below configuration variables are required for this Connector to operate. These variables are specified when configuring a Office 365 (MS Graph) asset in SOAR. | ||
### Configuration variables | ||
This table lists the configuration variables required to operate MS Graph for Office 365. These variables are specified when configuring a Office 365 (MS Graph) asset in Splunk SOAR. | ||
|
||
VARIABLE | REQUIRED | TYPE | DESCRIPTION | ||
-------- | -------- | ---- | ----------- | ||
**tenant** | required | string | Tenant ID (e.g. 1e309abf-db6c-XXXX-a1d2-XXXXXXXXXXXX) | ||
**client_id** | required | string | Application ID | ||
**client_secret** | required | password | Application Secret | ||
**auth_type** | optional | string | Authentication type to use for connectivity | ||
**client_secret** | optional | password | Application Secret(required for OAuth) | ||
**certificate_thumbprint** | optional | password | Certificate Thumbprint (required for CBA) | ||
**certificate_private_key** | optional | password | Certificate Private Key (.PEM) | ||
**admin_access** | optional | boolean | Admin Access Required | ||
**admin_consent** | optional | boolean | Admin Consent Already Provided | ||
**scope** | optional | string | Access Scope (for use with non-admin access; space-separated) | ||
**ph_2** | optional | ph | | ||
**admin_consent** | optional | boolean | Admin Consent Already Provided (Required checked for CBA) | ||
**scope** | optional | string | Access Scope (for use with OAuth non-admin access; space-separated) | ||
**email_address** | optional | string | Email Address of the User (On Poll) | ||
**folder** | optional | string | Mailbox folder name/folder path or the internal office365 folder ID to ingest (On Poll) | ||
**get_folder_id** | optional | boolean | Retrieve the folder ID for the provided folder name/folder path automatically and replace the folder parameter value (On Poll) | ||
**ph_3** | optional | ph | | ||
**first_run_max_emails** | optional | numeric | Maximum Containers for scheduled polling first time | ||
**max_containers** | optional | numeric | Maximum Containers for scheduled polling | ||
**extract_attachments** | optional | boolean | Extract Attachments | ||
|
@@ -653,7 +678,7 @@ action_result.data.\*.expirationDateTime | string | | | |
action_result.data.\*.groupTypes | string | | Unified | ||
action_result.data.\*.id | string | `msgoffice365 group id` | 2a201c95-101b-42d9-a7af-9a2fdf8193f1 | ||
action_result.data.\*.isAssignableToRole | string | | | ||
action_result.data.\*.mail | string | `email` `msgoffice365 group e-mail address` | [email protected] | ||
action_result.data.\*.mail | string | `email` `msgoffice365 group e-mail address` `msgoffice365 group email address` | [email protected] | ||
action_result.data.\*.mailEnabled | boolean | | True False | ||
action_result.data.\*.mailNickname | string | | Test-test-site | ||
action_result.data.\*.membershipRule | string | | | ||
|
@@ -689,7 +714,7 @@ Read only: **True** | |
PARAMETER | REQUIRED | DESCRIPTION | TYPE | CONTAINS | ||
--------- | -------- | ----------- | ---- | -------- | ||
**method** | required | Method to use to list group members | string | | ||
**identificator** | required | Group ID or group e-mail address, based on the selected method | string | `msgoffice365 group id` `msgoffice365 group e-mail address` | ||
**identificator** | required | Group ID or group e-mail address, based on the selected method | string | `msgoffice365 group id` `msgoffice365 group email address` `msgoffice365 group e-mail address` | ||
**get_transitive_members** | optional | Get a list of the group's members. A group can have users, devices, organizational contacts, and other groups as members. This operation is transitive and returns a flat list of all nested members | boolean | | ||
**filter** | optional | Search for specific results | string | | ||
**limit** | optional | Maximum number of members to return | numeric | | ||
|
@@ -701,7 +726,7 @@ action_result.status | string | | success failed | |
action_result.parameter.filter | string | | displayName eq 'Group Name' | ||
action_result.parameter.get_transitive_members | boolean | | True False | ||
action_result.parameter.method | string | | Group ID Group e-mail | ||
action_result.parameter.identificator | string | `msgoffice365 group id` `msgoffice365 group e-mail address` | TEST7d21-7631-4ea7-97b2-1328d1c5b901 [email protected] | ||
action_result.parameter.identificator | string | `msgoffice365 group id` `msgoffice365 group email address` `msgoffice365 group e-mail address` | TEST7d21-7631-4ea7-97b2-1328d1c5b901 [email protected] | ||
action_result.parameter.limit | numeric | | 20 | ||
action_result.data.\*[email protected] | string | | #test.abc.user | ||
action_result.data.\*.businessPhones | string | | 2056120271 | ||
|
@@ -1613,7 +1638,7 @@ DATA PATH | TYPE | CONTAINS | EXAMPLE VALUES | |
action_result.parameter.message_id | string | | | ||
action_result.parameter.move_to_junk_folder | boolean | | | ||
action_result.parameter.user_id | boolean | | | ||
action_result.status | string | | | ||
action_result.status | string | | success failed | ||
action_result.summary | string | | | ||
action_result.status | string | | success failed | ||
action_result.message | string | | | ||
|
@@ -1641,7 +1666,7 @@ DATA PATH | TYPE | CONTAINS | EXAMPLE VALUES | |
action_result.parameter.message_id | string | | | ||
action_result.parameter.move_to_inbox | boolean | | | ||
action_result.parameter.user_id | boolean | | | ||
action_result.status | string | | | ||
action_result.status | string | | success failed | ||
action_result.summary | string | | | ||
action_result.status | string | | success failed | ||
action_result.message | string | | | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.