You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Packs/MicrosoftExchangeOnline/Integrations/EwsExtensionEXOPowershellV3/EwsExtensionEXOPowershellV3_description.md
+38-24Lines changed: 38 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,16 +4,18 @@
4
4
To use this integration, you need to connect an application with a certificate.
5
5
1. Create the application:
6
6
1. Access **portal.azure.com**.
7
-
2. Navigate to **Home** > **App registrations** > **EWS**
8
-
3. In the left menu, click **API permissions**.
9
-
4. Click **Add a permission**.
10
-
5. In the Request API permissions page, click **APIs my organization uses**.
11
-
6. Search for **Office 365 Exchange Online**.
12
-
7. Click **Application permissions**.
13
-
8. Under Exchange, click the **ExchangeManageAsApp** checkbox.
14
-
9. Click **Add permissions**.
15
-
10. Click **Grant admin consent for XSOAR**.
16
-
2. Create the certificate in Cortex XSOAR.
7
+
2. Navigate to **Home** > **App registrations**.
8
+
3. Click **New Registration**, give the application a name (for example: **EWS**) and click **Register**.
9
+
4. In the left menu of the newly created application, click **API permissions**.
10
+
5. Click **Add a permission**.
11
+
6. In the Request API permissions page, click **APIs my organization uses**.
12
+
7. Search for **Office 365 Exchange Online**.
13
+
8. Click **Application permissions**.
14
+
9. Under Exchange, click the **ExchangeManageAsApp** checkbox.
15
+
10. Click **Add permissions**.
16
+
11. Click **Grant admin consent**.
17
+
18
+
2. Create the certificate in Cortex XSOAR/XSIAM.
17
19
1. Run the **CreateCertificate** command in the Playground to acquire the certificate.
18
20
19
21
***!CreateCertificate days=<# of days> password=\<password>***
@@ -26,31 +28,43 @@ To use this integration, you need to connect an application with a certificate.
26
28
27
29
28
30
3. Attach the .cer file to your Azure app.
29
-
1. In the Cortex XSOAR Playground, download the publickey.cer file
31
+
1. In the Cortex XSOAR/XSIAM Playground, download the publickey.cer file
30
32
2. In the Azure application, in the left menu, click **Certificates & secrets**.
31
33
3. In the Certificates tab, upload the publickey.cer file.
32
34
33
35
34
36
4. Assign Azure AD roles to the application.
35
-
1. You have two options:
36
-
- Assign Azure AD roles to the application.
37
-
- Assign custom role groups to the application using service principals.
38
-
2. In the Azure AD portal at https://portal.azure.com/, start typing roles and administrators in the Search box at the
39
-
top of the page, and then select Azure AD roles and administrators from the results in the Services section.
40
-
3. On the Roles and administrators page that opens, find and select one of the supported roles by clicking on the
41
-
name of the role (not the checkbox) in the results.
42
-
4. On the Assignments page that opens, select **Add assignments**.
43
-
5. In the Add assignments flyout that opens, find and select the app that you created in Step 1.
44
-
37
+
1. You have two options:
38
+
- Assign Azure AD roles to the application.
39
+
- Assign custom role groups to the application using service principals.
40
+
2. In the [Azure AD portal](https://portal.azure.com/), search for **Microsoft Entra roles and administrators** in the Search box.
41
+
3. On the Roles and administrators page that opens, find and select one of the supported roles by clicking on the
42
+
name of the role (not the checkbox) in the results.
43
+
- The role **Security Administrator** is eligible for this integration.
44
+
4. On the Assignments page that opens, select **Add assignments**.
45
+
5. In the Add assignments flyout that opens, find and select the app that you created in Step 1.
45
46
46
47
Note: The information in the Playground is sensitive information. You should delete the information by running the following command:
47
48
48
49
***!DeleteContext all=yes***
49
50
50
-
5. In Cortex XSOAR, in the integration instance configuration, enter your saved password in the **Password** field.
51
+
5. In Cortex XSOAR/XSIAM, in the integration instance configuration, enter your saved password in the **Password** field.
51
52
6. In Azure, go to Entra ID (Overview blade) and copy the **Primary domain** field.
52
-
7. In Cortex XSOAR, in the integration instance configuration, paste the Domain name in **The organization used in app-only authentication** field.
53
+
7. In Cortex XSOAR/XSIAM, in the integration instance configuration, paste the Domain name in **The organization used in app-only authentication** field.
53
54
8. In the Azure app, navigate to **Home** > **App registration** > **\<application name>** and copy the Application (client) ID.
54
-
9. In Cortex XSOAR, in the integration instance configuration, paste the application ID in **The application ID from the Azure portal** field.
55
+
9. In Cortex XSOAR/XSIAM, in the integration instance configuration, paste the application ID in **The application ID from the Azure portal** field.
56
+
55
57
58
+
### Verify that the admin account has sufficient Exchange Online permissions
59
+
For the integration to work, the Azure AD application's service principal must have the correct permissions assigned in the Exchange Online role groups.
60
+
1. Open the Microsoft Purview Portal: https://purview.microsoft.com/
61
+
2. Log in using an admin account that can manage role assignments for the Azure AD application (for example, a Global Administrator or Privileged Role Administrator).
62
+
3. In the top bar, select: **Settings → Roles and scopes**
63
+
4. In the left sidebar, select: **Role Groups**
64
+
5. Search for the following role groups:
65
+
-**Organization Management** – the most privileged role and fully supported for this integration.
66
+
-**Security Administrator** – a highly privileged security role that also provides full access.
67
+
6. Open the role and verify that the **service principal of the Azure AD application used by the integration** is listed.
68
+
7. If not listed, click **Edit → Add Users** and assign the required roles.
56
69
70
+
* Note - for more information go to the official [Microsoft Documentation.](https://learn.microsoft.com/en-us/defender-office-365)
| Certificate | A txt certificate encoded in Base64. | True |
14
14
| The organization used in app-only authentication. || True |
15
15
| The application ID from the Azure portal || True |
16
16
17
+
### App authentication
18
+
19
+
To use this integration, you need to connect an application with a certificate.
20
+
21
+
1. Create the application:
22
+
1. Access [Azure AD portal](https://portal.azure.com/).
23
+
2. Navigate to **Home** > **App registrations**.
24
+
3. Click **New Registration**, give the application a name (for example: **EWS**) and click **Register**.
25
+
4. In the left menu of the newly created application, click **API permissions**.
26
+
5. Click **Add a permission**.
27
+
6. In the Request API permissions page, click **APIs my organization uses**.
28
+
7. Search for **Office 365 Exchange Online**.
29
+
8. Click **Application permissions**.
30
+
9. Under Exchange, click the **ExchangeManageAsApp** checkbox.
31
+
10. Click **Add permissions**.
32
+
11. Click **Grant admin consent**.
33
+
34
+
2. Create the certificate in Cortex XSOAR/XSIAM.
35
+
1. Run the **CreateCertificate** command in the Playground to acquire the certificate.
36
+
37
+
***!CreateCertificate days=<# of days> password=`password`***
38
+
39
+
*Note: Remember your password since you will need it to create your integration instance.*
40
+
41
+
2. Download the certificateBase34.txt file.
42
+
3. Open the downloaded txt file and copy the text.
43
+
4. In the integration instance configuration, paste the text in the **Certificate** field.
44
+
45
+
3. Attach the .cer file to your Azure app.
46
+
1. In the Cortex XSOAR/XSIAM Playground, download the publickey.cer file
47
+
2. In the Azure application, in the left menu, click **Certificates & secrets**.
48
+
3. In the Certificates tab, upload the publickey.cer file.
49
+
50
+
4. Assign Azure AD roles to the application.
51
+
1. You have two options:
52
+
- Assign Azure AD roles to the application.
53
+
- Assign custom role groups to the application using service principals.
54
+
2. In the [Azure AD portal](https://portal.azure.com/), search for **Microsoft Entra roles and administrators** in the Search box.
55
+
3. On the Roles and administrators page that opens, find and select one of the supported roles by clicking on the
56
+
name of the role (not the checkbox) in the results.
57
+
- The role **Security Administrator** is eligible for this integration.
58
+
4. On the Assignments page that opens, select **Add assignments**.
59
+
5. In the Add assignments flyout that opens, find and select the app that you created in Step 1.
60
+
61
+
Note: The information in the Playground is sensitive information. You should delete the information by running the following command:
62
+
63
+
***!DeleteContext all=yes***
64
+
65
+
5. In Cortex XSOAR/XSIAM, in the integration instance configuration, enter your saved password in the **Password** field.
66
+
6. In Azure, go to Entra ID (Overview blade) and copy the **Primary domain** field.
67
+
7. In Cortex XSOAR/XSIAM, in the integration instance configuration, paste the Domain name in **The organization used in app-only authentication** field.
68
+
8. In the Azure app, navigate to **Home** > **App registration** > **application name** and copy the Application (client) ID.
69
+
9. In Cortex XSOAR/XSIAM, in the integration instance configuration, paste the application ID in **The application ID from the Azure portal** field.
70
+
71
+
### Verify that the admin account has sufficient Exchange Online permissions
72
+
73
+
For the integration to work, the Azure AD application's service principal must have the correct permissions assigned in the Exchange Online role groups.
74
+
75
+
1. Open the Microsoft Purview Portal: <https://purview.microsoft.com/>
76
+
2. Log in using an admin account that can manage role assignments for the Azure AD application (for example, a Global Administrator or Privileged Role Administrator).
77
+
3. In the top bar, select: **Settings → Roles and scopes**
78
+
4. In the left sidebar, select: **Role Groups**
79
+
5. Search for the following role groups:
80
+
-**Organization Management** – the most privileged role and fully supported for this integration.
81
+
-**Security Administrator** – a highly privileged security role that also provides full access.
82
+
6. Open the role and verify that the **service principal of the Azure AD application used by the integration** is listed.
83
+
7. If not listed, click **Edit → Add Users** and assign the required roles.
84
+
85
+
- Note - for more information go to the official [Microsoft Documentation.](https://learn.microsoft.com/en-us/defender-office-365)
86
+
87
+
## Troubleshooting and Testing
88
+
89
+
### Common Issues and Solutions
90
+
91
+
#### **`The role assigned to application 'app-id' isn't supported in this scenario.`**
92
+
93
+
**Scenario:**
94
+
When running 'Test', you receive the error:
95
+
*“The role assigned to application `app-id` isn't supported in this scenario. Please check online documentation for assigning correct Directory Roles to Azure AD Application for EXO App-Only Authentication.”*
96
+
97
+
**Solution:**
98
+
Verify that the application has the correct directory role assigned in the **Entra ID portal**.
99
+
See the **“App authentication”** section above for detailed guidance.
100
+
101
+
---
102
+
103
+
#### **`The term 'cmdlet' is not recognized as a name of a cmdlet…`**
104
+
105
+
**Scenario:**
106
+
When running a command, you receive an error similar to:
107
+
*“The term `cmdlet` is not recognized as a name of a cmdlet, function, script file, or executable program…”*
108
+
109
+
**Solution:**
110
+
Make sure the **service principal of the Azure AD application used by the integration** has sufficient **Exchange Online permissions**.
111
+
Refer to the **“Exchange Online permissions”** section above to confirm the correct roles are assigned and detailed guidance.
112
+
17
113
## Commands
18
114
19
115
You can execute these commands from the CLI, as part of an automation, or in a playbook.
@@ -483,11 +579,11 @@ Official PowerShell cmdlet documentation [here](https://docs.microsoft.com/en-us
483
579
|**Argument Name**|**Description**|**Required**|
484
580
| --- | --- | --- |
485
581
| list_type | List type to retrieve items from. | Required |
486
-
| list_subtype | List subtype to retrieve items from. | Optional |
582
+
| list_subtype | List subtype to retrieve items from. | Optional |
| expiration_date | Enter a specific date and time to filter entries by using format "YYYY-MM-DD HH:MM:SSz" for UTC time. Alternately, a PowerShell **GetDate** statement can be used. | Optional |
489
585
| no_expiration | Filter list items that are set to never expire. | Optional |
490
-
| entry |Specif8ic entry value to retrieve. | Optional |
586
+
| entry |Specific entry value to retrieve. | Optional |
0 commit comments