Microsoft Exchange Online PowerShell 2.0.0
App Vendor: Microsoft
App Category: IT Services
Connector Version: 2.0.1
API Version: v1.0
Note
To use version 2.0.0 or later of this app, ensure that the Cyware Orchestrate platform is updated to version 3.5.9.0 or higher.
About App
The Microsoft Exchange Online PowerShell app offers a set of tools to help security teams manage and secure Exchange Online environments, enabling efficient administration of mailboxes, user permissions, and security settings.
The Microsoft Exchange Online PowerShell app is configured with Cyware Orchestrate to perform the following actions:
Action Name | Description |
---|---|
Add Items to Allow/Block List | This action adds IOCs to the Allow/Block List in the Microsoft Defender portal. |
Add Sender to Junk Mail Configuration | This action adds an email to the junk mail configuration for a given user. |
Get Allow/Block List Items | This action retrieves the IOC entries from the Allow/Block list in the Microsoft Defender portal. |
Remove Allow/Block List Items | This action removes IOC entries from the Allow/Block List in the Microsoft Defender portal. |
Remove Sender From Junk Mail Configuration | This action removes an email ID from the junk mail configuration. |
Configure Microsoft Exchange Online PowerShell Instance
Configure a Microsoft Exchange Online PowerShell instance in Cyware Orchestrate to communicate with the Microsoft Exchange Online PowerShell enterprise application.
Step 1: Generate Application Registration Certificate
To authenticate your application against Microsoft Entra ID while requesting an app-only access token, you need a certificate with its private key. This certificate allows your app to use the permissions granted to it.
Note
You can generate the certificate using either a Python script or a PowerShell script.
Before you Start
Ensure that you have OpenSSL installed. For more information about installing OpenSSL, see OpenSSL documentation.
For PowerShell, ensure that you have version 7.4.6 installed. For more information about installing PowerShell v7.4.6, see the Microsoft Exchange Online PowerShell documentation.
Steps
To generate the application registration certificate, follow these steps:
You can either use a Python script or a PowerShell script to generate the certificate. Before running the script, replace the following placeholder parameter values with actual values:
Parameter
Description
cert_pass
/$CertPass
Enter the password for the .cer file that will be created by the script. You will use this password while configuring the app instance.
days
/$Days
Enter the number of days after which the certificate will expire. By default, the certificate expires 180 days from the creation date. You can set the maximum expiry period to 730 days (2 years).
b64_path
/$b64_path
Enter the name of the .txt file to store the base64-encoded certificate content. You will use this file during the app configuration.
public_key_cert_path
/$public_key_cert_path
Enter the name of the .cer file, which you must upload to the Certificates & Secrets section.
Note
Python parameters are in lowercase (for example,
cert_pass
), while PowerShell uses $ for variables (for example,$CertPass
)To generate the certificate, use the following information:
Using Python Script: After replacing the placeholder values, run the following Python script either on Google Colab or locally to generate the certificate:
import os import base64 import datetime import json import subprocess # Replace the below parameters with a value cert_pass = "CERT_PASSWORD" days = 180 b64_path = "TEXT_FILE.txt" public_key_cert_path = "CER_FILE.cer" # Do not replace the values below pfx_path = "certificate.pfx" try: not_after = datetime.datetime.now() + datetime.timedelta(days=days) not_after_str = not_after.strftime("%Y-%m-%d %H:%M:%S") subprocess.run([ "openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", "key.pem", "-out", "cert.pem", "-days", str(days), "-subj", "/CN=localhost", ], check=True, capture_output=True) subprocess.run([ "openssl", "pkcs12", "-export", "-in", "cert.pem", "-inkey", "key.pem", "-out", pfx_path, "-passout", f"pass:{cert_pass}" ], check=True, capture_output=True) subprocess.run([ "openssl", "pkcs12", "-in", pfx_path, "-out", public_key_cert_path, "-nokeys", "-clcerts", "-password", f"pass:{cert_pass}" ], check=True, capture_output=True) with open(pfx_path, "rb") as f: file_content = f.read() base64_encoded = base64.b64encode(file_content).decode("utf-8") with open(b64_path, "w") as f: f.write(base64_encoded) success_text = {"message": "Certificate created"} print(json.dumps(success_text)) except subprocess.CalledProcessError as e: print(f"OpenSSL Error: {e}") print(f"Stdout: {e.stdout.decode()}") print(f"Stderr: {e.stderr.decode()}") print("An error occurred during certificate creation.") except Exception as e: print(f"An error occurred: {e}") finally: try: os.remove("key.pem") os.remove("cert.pem") except FileNotFoundError: pass
Using PowerShell Script: After replacing the placeholder values, run the following PowerShell script locally on your system:
# Replace the below parameters with a value $CertPass = "YOUR_CERTIFICATE_PASSWORD" $Days = 180 $b64_path = "NAME_OF_THE_TEXT_FILE_TO_BE_SAVED"+".txt" $public_key_cert_path = "NAME_OF_THE_CERTIFICATE"+".cer" # Do not replace the values below Install-Module -Name SelfSignedCertificate -Force $pfx_path = "certificate.pfx" Import-Module SelfSignedCertificate *> $null 2>&1 $Password = ConvertTo-SecureString $CertPass -AsPlainText -Force $cmd_args = @{ "OutCertPath" = $pfx_path "NotAfter" = (Get-Date).AddDays($Days) "Password" = $Password } try { New-SelfSignedCertificate @cmd_args -WarningAction:SilentlyContinue *> $null 2>&1 openssl pkcs12 -in $pfx_path -out $public_key_cert_path -nokeys -clcerts -password pass:$CertPass *> $null 2>&1 $File = [System.IO.File]::ReadAllBytes($pfx_path); $base_64_encoded = [System.Convert]::ToBase64String($File); [System.IO.File]::WriteAllText($b64_path, $base_64_encoded) *> $null 2>&1 $success_text = "Certificate created" | ConvertTo-Json Write-Output($success_text) } catch { Write-Error "An error occurred: $_" }
The script generates the following files:
.cer: Public key
.pfx: Private key
.txt: Certificate content
Step 2: Configure Microsoft Exchange Online Powershell
To enable authentication and role-based access, you must upload the certificate to Azure, configure API permissions, and assign the necessary roles.
Before you Start
Ensure that you have generated the application registration certificate.
Steps
To configure the application, follow these steps:
Go to the Azure portal and either select an existing app or create a new one. To create a new app, follow the first step in Microsoft Exchange Online Powershell documentation.
To upload the certificate, go to All applications under the Apps registration page. Select your application and go to Manage > Certificates & Secrets > Certificates, click Upload certificate, and upload the .cer file generated in step 1.
Go to Manage > API permissions and grant the required API permissions. For more information, see Microsoft Exchange Online Powershell documentation.
To modify the manifest file, select Manifest from the Manage section. In the app code, replace the key
requiredResourceAccess
and its associated value with the following code snippet:"requiredResourceAccess": [ { "resourceAppId": "00000002-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "dc50a0fb-09a3-484d-be87-e023b12c6440", "type": "Role" } ] }, { "resourceAppId": "00000003-0000-0000-c000-000000000000", "resourceAccess": [ { "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d", "type": "Scope" } ] } ],
Click Save to save your changes.
To verify if the permissions are correctly granted, go to Manage > API permissions. On the API permissions page, ensure that Office 365 Exchange Online is listed. Under it, confirm that Exchange.ManageAsApp is included with the following details:
Type: Application
Admin consent required: Yes
Status: Granted for <Your Organization>
The application needs the appropriate roles for proper access and functionality. To assign Microsoft Entra roles, go to the home page of the Azure portal, search roles and administrators, select Microsoft Entra roles and administrators, and then click the required option from the following roles:
Compliance Administrator
Exchange Administrator
Exchange Recipient Administrator
Global Administrator
Global Reader
Helpdesk Administrator
Security Administrator
Security Reader
For more information about the access levels of the Microsoft Entra roles, see Microsoft Exchange Online Powershell documentation.
To add an assignment, go to Manage > Assignments > Add assignments. Search for and select the app you created or selected, then click Add. Refresh the page to confirm if the app has been successfully added.
To communicate with the app, you must create an instance in Cyware Orchestrate.
Sign in to Orchestrate, go to Main Menu > Apps > Appstore, and search for Microsoft Exchange Online PowerShell.
Click on the app and install the latest version. Go to Instances, click the plus icon to create an instance for the selected version, and use the following information:
Cert Password: Enter the password of the certificate file.
Organization: Enter your organization's primary domain to connect using certificate-based authentication (CBA) or managed identity. For example, orgname.com
App ID: Enter the application ID of the service principal you are using for certificate-based authentication (CBA). For example, 36ee4c6c-0812-40a2-b820-b22ebd02bce3
Certificate Content: Enter the content of the .txt file generated after running the certificate creation script.
Click Create. To test the app instance and verify the connection, hover over the instance, and click Test Instance.
Action: Add Items to Allow/Block List
This action adds IOCs to the Allow/Block List in the Microsoft Defender portal.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
---|---|---|---|---|
Entries | Enter the comma-separated values to add to the Allow/Block list. Example: a1040d1548a3c2f5614272f9c0c3b2adb6822d94836d47e7e073e4090cfca37b | Text | Required | Allowed entry types: FileHash (SHA256), Sender (domain/email), Url, and IP (IPv6) |
List Type | Enter the type of IOC value to add to the list. | Text | Required | Allowed values: FileHash, Sender, Url, and IP |
Action | Enter whether the entry should be added to the Allow list or the Block list. | Text | Required | Allowed values: Allow, Block |
List Subtype | Enter the value to specify the subtype of the entry. | Text | Optional | Allowed values: AdvancedDelivery, Tenant Default value: Tenant |
Notes | Enter additional information about the object. | Text | Optional | |
No Expiration | Choose true to ensure the entry never expires. If you choose false, the entry will expire based on the date specified in the Expiration Date parameter. If no date is set, the entry expires after 30 days. | Boolean | Optional | Default value: false |
Expiration Date | Specify the expiration date of the entries in UTC format. Example: 2021-05-06 14:30:00z | Text | Optional | If no date is set, the entry expires after 30 days. |
Example Request
[ { "notes": "This is a sample note.", "action": "Allow", "entries": "26da:5885:bbca:a0e2:ec68:a2ed:d782:7018, 2004:1011:cd2e:05a7:dc61:b2b1:0737:a148", "list_type": "IP", "no_expiration": true } ]
Action: Add Sender to Junk Mail Configuration
This action adds an email to the junk mail configuration for a given user.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
---|---|---|---|---|
User ID | Enter the user ID. Example: user@test.onmicrosoft.com | Text | Required | |
Email to Block | Enter the email ID to add to the junk email configuration. Example: john.doe@orgname.com | Text | Required |
Example Request
[ { "user_id": "user@test.onmicrosoft.com", "email_to_block": "john.doe@orgname.com" } ]
Action: Get Allow/Block List Items
This action retrieves the IOC entries from the Allow/Block list.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
---|---|---|---|---|
Entries | Enter the exact value to filter by FileHash (SHA256), Sender (domain/email), Url, or IP (IPv6 address or CIDR range). Example: a1040d1548a3c2f5614272f9c0c3b2adb6822d94836d47e7e073e4090cfca37b | Text | Optional | |
List Type | Enter the type of IOC value to filter the response. | Text | Required | Allowed values: FileHash, Sender, Url, IP |
List Subtype | Enter the subtype of the entry to filter the response. | Text | Optional | Allowed values: AdvancedDelivery, Tenant. Default value: Tenant |
Action | Enter whether to retrieve the entry from the Allow or Block list. | Text | Optional | Allowed values: Allow, Block |
No Expiration | Choose true to retrieve entries that are set to never expire. | Boolean | Required | Default value: true |
Expiration Date | Enter the expiration date in UTC to filter the response. Example: 2021-05-06 14:30:00Z | Text | Optional |
Example Request
[ { "action": "Block", "list_type": "Sender", "no_expiration": false, "expiration_date": "2028-05-06 14:30:00z" } ]
Action: Remove Allow/Block List Items
This action removes IOC entries from the Allow/Block List.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
---|---|---|---|---|
Entries | Enter the comma-separated values that you want to remove from the Allow/Block list. | Text | Optional | You can enter either Entries or IDs, but not both simultaneously. |
IDs | Enter the IDs of the IOC entries that you want to remove. Example: RgAAAAAI8gSyI_NmQqzeh-HXJBywBwCqfQNJY8hBTbdlKFkv6BcUAAAl_QCZAACqfQNJY8hBTbdlKFkv6BcUAAAl_oSPAAAA0 | Text | Optional | You can enter either Entries or IDs, but not both simultaneously. You can retrieve the IDs using the action Get Allow/Block List Items. |
List Type | Enter the type of IOC value to remove from the list. | Text | Required | Allowed values: FileHash, Sender, Url, IP |
List Subtype | Enter the value to specify the subtype of the entry. | Text | Optional | Allowed values: AdvancedDelivery, Tenant. Default value: Tenant |
Example Request
[ { "entries": "4119:e323:3d7d:6cf0:f96c:01d9:5fe5:42c2 , f1f8:94d3:f346:d413:0ea3:f67a:6388:fe92", "list_type": "IP" } ]
Action: Remove Sender From Junk Mail Configuration
This action removes an email ID from the junk mail configuration.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
---|---|---|---|---|
User ID | Enter the user ID. Example: user@test.onmicrosoft.com | Text | Required | |
Email to Remove | Enter the email ID to remove it from the junk email configuration. Example: john.doe@orgname.com | Text | Required |
Example Request
[ { "user_id": "user@test.onmicrosoft.com", "email_to_remove": "john.doe@orgname.com" } ]