Skip to content

Commit 7acf01f

Browse files
phantom-jacobphantom-jacob
authored
Merge pull request #44 from ianwills-splunk/certificate-based-authentication
msgraphforoffice365: Feature - Certificate based authentication
2 parents 86faa8b + 21eec09 commit 7acf01f

13 files changed

+488
-282
lines changed

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,4 +198,4 @@
198198
distributed under the License is distributed on an "AS IS" BASIS,
199199
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200200
See the License for the specific language governing permissions and
201-
limitations under the License.
201+
limitations under the License.

‎NOTICE‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,6 @@ Copyright (c) 2017-2024 Splunk Inc.
33

44
Third-party Software Attributions:
55

6-
Library: beautifulsoup4
7-
Version: 4.9.1
8-
License: MIT
9-
Copyright 2004-2017 Leonard Richardson
10-
Copyright 2004-2019 Leonard Richardson
11-
Copyright 2018 Isaac Muse
12-
136
Library: python-magic
147
Version: 0.4.18
158
License: MIT

‎README.md‎

Lines changed: 43 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
# MS Graph for Office 365
33

44
Publisher: Splunk
5-
Connector Version: 3.1.1
5+
Connector Version: 4.0.0
66
Product Vendor: Microsoft
77
Product Name: Office 365 (MS Graph)
88
Product Version Supported (regex): ".\*"
@@ -49,9 +49,21 @@ On the next page, select **New registration** and give your app a name.
4949

5050
Once the app is created, follow the below-mentioned steps:
5151

52-
- Under **Certificates & secrets** select **New client secret** . Enter the **Description** and
53-
select the desired duration in **Expires** . Click on **Add** . Note down this **value**
54-
somewhere secure, as it cannot be retrieved after closing the window.
52+
- For authentication using a client secret (OAuth):
53+
54+
- Under **Certificates & secrets** select **New client secret** . Enter the **Description** and
55+
select the desired duration in **Expires** . Click on **Add** . Note down this **value**
56+
somewhere secure, as it cannot be retrieved after closing the window.
57+
58+
- For authentication using certificate based authentication (CBA):
59+
60+
- Under **Certificates & secrets** select **Certificates** then **Upload Certificate** .
61+
Select the certifitcate file to upload (.crt/.pem) and enter the **Description** . Note down
62+
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))
63+
- Generate private key:
64+
- `openssl genpkey -algorithm RSA -out private_key.pem` / `openssl genrsa -out private_key.pem 2048`
65+
- Generate certifitcate from the private key (Valid for 365 days):
66+
- `openssl req -new -x509 -key private_key.pem -out certificate.pem -days 365`
5567

5668
- Under **Authentication** , select **Add a platform** . In the **Add a platform** window, select
5769
**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:
7183

7284
- User.Read.All (https://graph.microsoft.com/User.Read.All)
7385

74-
75-
7686
- For non-admin access, use User.Read (Delegated permission) instead
7787
(https://graph.microsoft.com/User.Read)
7888

@@ -91,6 +101,7 @@ Once the app is created, follow the below-mentioned steps:
91101

92102
- MailboxSettings.Read (https://graph.microsoft.com/MailboxSettings.Read) - It is required
93103
only if you want to run the **oof status** , **list rules** and **get rule** actions.
104+
- 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.
94105

95106
After making these changes, click **Add permissions** , then select **Grant admin consent for
96107
\<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:
137148

138149
### Test connectivity
139150

140-
#### Admin User Workflow
151+
#### Admin User Workflow (OAuth)
141152

142153
- Configure the asset with required details while keeping the **Admin Access Required** as
143154
checked.
@@ -160,7 +171,7 @@ the window. To give this user permission to view assets, follow these steps:
160171
config parameter as checked. This will skip the interactive flow and use the client credentials
161172
for generating tokens.
162173

163-
#### Non-Admin User Workflow
174+
#### Non-Admin User Workflow (OAuth)
164175

165176
- Configure the asset with required details while keeping the **Admin Access Required** as
166177
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:
181192
- Now go back and check the message on the Test Connectivity dialog box, it should say **Test
182193
Connectivity Passed** .
183194

184-
185-
195+
#### Certificate Based Authentication Workflow (CBA)
196+
197+
- Configure the asset with **Tenant ID**, **Application ID**, **Certificate Thumbprint** and
198+
the **Certificate private key (.PEM)**
199+
- Ensure **Admin Consent Already Provided** is checked.
200+
- After setting up the asset and user, click the **TEST CONNECTIVITY** button.
201+
- Check the message in the Test Connectivity dialog box. it should say **Test
202+
Connectivity Passed** .
203+
204+
#### Automatic Authentication Workflow
205+
206+
- Configure the asset with the required details, including either the **Application Secret** or a combination of **Certificate Thumbprint** and **Location of the certificate private key (.PEM) on the filesystem**.
207+
- If **Application Secret** exists, it will take priority and follow the OAuth workflow. Otherwise, it will continue with the CBA workflow.
208+
- 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.
209+
186210
The app should now be ready to be used.
187211

188212
### On-Poll
@@ -306,10 +330,14 @@ VARIABLE | REQUIRED | TYPE | DESCRIPTION
306330
-------- | -------- | ---- | -----------
307331
**tenant** | required | string | Tenant ID (e.g. 1e309abf-db6c-XXXX-a1d2-XXXXXXXXXXXX)
308332
**client_id** | required | string | Application ID
309-
**client_secret** | required | password | Application Secret
333+
**auth_type** | optional | string | Authentication type to use for connectivity
334+
**client_secret** | optional | password | Application Secret(required for OAuth)
335+
**ph_4** | optional | ph |
336+
**certificate_thumbprint** | optional | password | Certificate Thumbprint(required for CBA)
337+
**private_key_location** | optional | string | Location of the certificate private key (.PEM) on the filesystem(required for CBA)
310338
**admin_access** | optional | boolean | Admin Access Required
311-
**admin_consent** | optional | boolean | Admin Consent Already Provided
312-
**scope** | optional | string | Access Scope (for use with non-admin access; space-separated)
339+
**admin_consent** | optional | boolean | Admin Consent Already Provided(Required checked for CBA)
340+
**scope** | optional | string | Access Scope (for use with OAuth non-admin access; space-separated)
313341
**ph_2** | optional | ph |
314342
**email_address** | optional | string | Email Address of the User (On Poll)
315343
**folder** | optional | string | Mailbox folder name/folder path or the internal office365 folder ID to ingest (On Poll)
@@ -1613,7 +1641,7 @@ DATA PATH | TYPE | CONTAINS | EXAMPLE VALUES
16131641
action_result.parameter.message_id | string | |
16141642
action_result.parameter.move_to_junk_folder | boolean | |
16151643
action_result.parameter.user_id | boolean | |
1616-
action_result.status | string | |
1644+
action_result.status | string | | success failed
16171645
action_result.summary | string | |
16181646
action_result.status | string | | success failed
16191647
action_result.message | string | |
@@ -1641,7 +1669,7 @@ DATA PATH | TYPE | CONTAINS | EXAMPLE VALUES
16411669
action_result.parameter.message_id | string | |
16421670
action_result.parameter.move_to_inbox | boolean | |
16431671
action_result.parameter.user_id | boolean | |
1644-
action_result.status | string | |
1672+
action_result.status | string | | success failed
16451673
action_result.summary | string | |
16461674
action_result.status | string | | success failed
16471675
action_result.message | string | |

‎manual_readme_content.md‎

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,21 @@ On the next page, select **New registration** and give your app a name.
3737

3838
Once the app is created, follow the below-mentioned steps:
3939

40-
- Under **Certificates & secrets** select **New client secret** . Enter the **Description** and
41-
select the desired duration in **Expires** . Click on **Add** . Note down this **value**
42-
somewhere secure, as it cannot be retrieved after closing the window.
40+
- For authentication using a client secret(OAuth):
41+
42+
- Under **Certificates & secrets** select **New client secret** . Enter the **Description** and
43+
select the desired duration in **Expires** . Click on **Add** . Note down this **value**
44+
somewhere secure, as it cannot be retrieved after closing the window.
45+
46+
- For authentication using certificate based authentication(CBA):
47+
48+
- Under **Certificates & secrets** select **Certificates** then **Upload Certificate** .
49+
Select the certifitcate file to upload (.crt/.pem) and enter the **Description** . Note down
50+
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))
51+
- Generate private key:
52+
- `openssl genpkey -algorithm RSA -out private_key.pem` / `openssl genrsa -out private_key.pem 2048`
53+
- Generate certificate from the private key (Valid for 365 days):
54+
- `openssl req -new -x509 -key private_key.pem -out certificate.pem -days 365`
4355

4456
- Under **Authentication** , select **Add a platform** . In the **Add a platform** window, select
4557
**Web** . The **Redirect URLs** should be filled right here. We will get **Redirect URLs** from
@@ -59,8 +71,6 @@ Once the app is created, follow the below-mentioned steps:
5971

6072
- User.Read.All (https://graph.microsoft.com/User.Read.All)
6173

62-
63-
6474
- For non-admin access, use User.Read (Delegated permission) instead
6575
(https://graph.microsoft.com/User.Read)
6676

@@ -79,6 +89,7 @@ Once the app is created, follow the below-mentioned steps:
7989

8090
- MailboxSettings.Read (https://graph.microsoft.com/MailboxSettings.Read) - It is required
8191
only if you want to run the **oof status** , **list rules** and **get rule** actions.
92+
- 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.
8293

8394
After making these changes, click **Add permissions** , then select **Grant admin consent for
8495
\<your_organization_name_as_on_azure_portal>** at the bottom of the screen.
@@ -125,7 +136,7 @@ the window. To give this user permission to view assets, follow these steps:
125136

126137
### Test connectivity
127138

128-
#### Admin User Workflow
139+
#### Admin User Workflow (OAuth)
129140

130141
- Configure the asset with required details while keeping the **Admin Access Required** as
131142
checked.
@@ -148,7 +159,7 @@ the window. To give this user permission to view assets, follow these steps:
148159
config parameter as checked. This will skip the interactive flow and use the client credentials
149160
for generating tokens.
150161

151-
#### Non-Admin User Workflow
162+
#### Non-Admin User Workflow (OAuth)
152163

153164
- Configure the asset with required details while keeping the **Admin Access Required** as
154165
unchecked. **Admin Consent Already Provided** config parameter will be ignored in the non-admin
@@ -169,8 +180,21 @@ the window. To give this user permission to view assets, follow these steps:
169180
- Now go back and check the message on the Test Connectivity dialog box, it should say **Test
170181
Connectivity Passed** .
171182

172-
173-
183+
#### Certificate Based Authentication Workflow (CBA)
184+
185+
- Configure the asset with **Tenant ID**, **Application ID**, **Certificate Thumbprint** and
186+
the **Certificate Private Key (.PEM).**
187+
- Ensure **Admin Consent Already Provided** is checked.
188+
- After setting up the asset and user, click the **TEST CONNECTIVITY** button.
189+
- Check the message in the Test Connectivity dialog box. it should say **Test
190+
Connectivity Passed** .
191+
192+
#### Automatic Authentication Workflow
193+
194+
- Configure the asset with the required details, including either the **Application Secret** or a combination of **Certificate Thumbprint** and **Certificate Private Key (.PEM)**.
195+
- If **Application Secret** exists, it will take priority and follow the OAuth workflow. Otherwise, it will continue with the CBA workflow.
196+
- 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.
197+
174198
The app should now be ready to be used.
175199

176200
### On-Poll

0 commit comments

Comments
 (0)