Skip to main content

Cyware Orchestrate

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

Steps

To generate the application registration certificate, follow these steps:

  1. 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)

  2. 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:

  1. 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.

  2. 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.

  3. Go to Manage > API permissions and grant the required API permissions. For more information, see Microsoft Exchange Online Powershell documentation.

  4. 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.

  5. 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>

  6. 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.

  7. 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.

  8. To communicate with the app, you must create an instance in Cyware Orchestrate

  9. Sign in to Orchestrate, go to Main Menu > Apps > Appstore, and search for Microsoft Exchange Online PowerShell

  10. 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"
  }
]