Skip to content

Commit

Permalink
Merge pull request #50 from splunk-soar-connectors/next
Browse files Browse the repository at this point in the history
Merging next to main for release 4.0.0
  • Loading branch information
phantom-jacob authored Jan 7, 2025
2 parents 6be4b2a + 93c52e2 commit 43b4297
Show file tree
Hide file tree
Showing 12 changed files with 492 additions and 289 deletions.
7 changes: 0 additions & 7 deletions NOTICE
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,6 @@ Copyright (c) 2017-2024 Splunk Inc.

Third-party Software Attributions:

Library: beautifulsoup4
Version: 4.9.1
License: MIT
Copyright 2004-2017 Leonard Richardson
Copyright 2004-2019 Leonard Richardson
Copyright 2018 Isaac Muse

Library: python-magic
Version: 0.4.18
License: MIT
Expand Down
71 changes: 48 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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)

Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 | |
Expand Down Expand Up @@ -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 |
Expand All @@ -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
Expand Down Expand Up @@ -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 | |
Expand Down Expand Up @@ -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 | |
Expand Down
42 changes: 33 additions & 9 deletions manual_readme_content.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,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
Expand All @@ -59,8 +71,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)

Expand All @@ -79,6 +89,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.
Expand Down Expand Up @@ -125,7 +136,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.
Expand All @@ -148,7 +159,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
Expand All @@ -169,8 +180,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
Expand Down
Loading

0 comments on commit 43b4297

Please sign in to comment.