Microsoft 365 Exchange Admin Center

Overview

Microsoft 365 Exchange Admin Center plugin provides the ability to manage mail flow rules (transport rules) shown within the MS365 Exchange Admin Center and manage a mailbox’s inbox rules.

Functionality

This plugin supports operations to:

Retrieve a mail flow rule.
Enable a mail flow rule.
Disable a mail flow rule.
Update the configuration of a mail flow rule.
Retrieve all inbox rules for a mailbox.
Retrieve an inbox rule for a mailbox.
Enable an inbox rule for a mailbox.
Disable an inbox rule for a mailbox.
Create a new inbox rule for a mailbox.
Modify an inbox rule for a mailbox.
Delete an inbox rule from a mailbox.
Retrieve all permissions for a mailbox.
Retrieve a user’s or security group’s permissions for a mailbox.
Add permissions for a user or security group to a mailbox.
Remove permissions for a user or security group from a mailbox.
Reset permissions for a mailbox.

Instance Configuration Parameters

Property

Description

Instance Name

Name of the Microsoft 365 Exchange Admin Center instance.

Unique ID

A system-wide unique identifier for this plugin instance used to locate the service.

Authentication Mechanism

The authentication mechanism to use for accessing the Exchange Admin Center. Certificate Based Authentication (CBA) is the preferred mechanism. Basic Authentication, using a username and password, is another option. Basic authentication is set to expire in the second half of 2021 as described here.

Application ID

Application ID within Azure AD. The application should have the Exchange.ManageAsApp permission, the Exchange Administrator role added via a security group, and the public certificate of the Certificate File associated within Certificates Secrets section of the application. Read through the Learn More section below for configuration details.

This field is shown when the Authentication Mechanism is set to Certificate Based Authentication (CBA).

Certificate File

Certificate file in PFX format (PKCS#12). The PFX file format contains the public certificate, the private key, and, if necessary, the intermediate authority certificate(s). The public certificate must be associated with the Application within the Azure AD admin center.

This field is shown when the Authentication Mechanism is set to Certificate Based Authentication (CBA).

Certificate Password

If encrypted, the password required to decrypt the private key in the Certificate File.

This field is shown when the Authentication Mechanism is set to Certificate Based Authentication (CBA).

Domain Name

The tenant’s domain name. It it strongly recommended that the .onmicrosoft.com domain name is used to prevent cryptic errors. The onmicrosoft domain information may be found at Microsoft 365 admin center: Domains page.

This field is shown when the Authentication Mechanism is set to Certificate Based Authentication (CBA).

Username

The Microsoft 365 Exchange administrator username.

This field is shown when the Authentication Mechanism is set to Basic Authentication.

Password

The Microsoft 365 Exchange administrator password and confirmation field.

This field is shown when the Authentication Mechanism is set to Basic Authentication.

Verbose Logging

Enables verbose debug logging for this plugin in the system logs.

Flow Node

Node to retrieve, enable, disable, or modify an existing Microsoft 365 Mail Flow Rule (Transport Rule).

Property

Description

Name

The display name of the node within the flows.

Unique ID

System-wide unique ID of the plugin instance.

Action

Configuration option determining the type of operation to perform:

Get Mail Flow Rule: Retrieves the mail flow rule configuration.
Enable Mail Flow Rule: Enables the mail flow rule.
Disable Mail Flow Rule: Disables the mail flow rule.
Modify Mail Flow Rule: Modifies the mail flow rule.

Successful results for an action are placed in msg.payload.ms365exchange.[uniqueId].response. The mail flow rule is accessible within rule.

Rule Name

The name of the mail flow rule to act upon.

Updates

Modifies the mail flow rule designated by Rule Name. The Updates define the set of operations to perform on the mail flow rule. Multiple updates may be performed and will be processed in the order specified by the Updates list. Multiple updates may be performed on the same Parameter.

The Parameter is the name of the property to update. The full list of parameters is defined on the Set-TransportRule page. Note, the properties being operated on are expected to be string like or boolean. The Parameter includes a few sample parameters for selection, but is not a comprehensive list. The Operation defines the change to the Parameter. If the Parameter is an array, use the Add Entry to List or the Remove Entry from List operations. Otherwise, use the Set Entry or the Clear Entry operations. Do not use Clear Entry for boolean parameters, but, instead, set the value to false.

The Value should evaluate to a string, boolean, or an array. However, if the Value can not be determined, there will be no attempt to change the Parameter. If the Value evaluates to an array, the Operation should either be Add Entry to List or Remove Entry from List.

When operating on a list using the Add Entry to List operation, duplicates will not be added. If the item to be removed is not in the list when using the Remove Entry from List operation, no change to the list is made. If the list becomes empty after removal, the parameter’s value will be set to null.

In addition to the standard response data, the array of changes to the mail flow rule are placed within changes.

Node to retrieve, enable, disable, create, modify, or delete Microsoft 365 Outlook Inbox Rules.

Property

Description

Name

The display name of the node within the flows.

Unique ID

System-wide unique ID of the plugin instance.

Action

Configuration option determining the type of operation to perform:

Get All Inbox Rules: Retrieves the configurations of all the inbox rules for a mailbox.
Get Inbox Rule: Retrieves an inbox rule configuration for a mailbox.
Enable Inbox Rule: Enables an inbox rule for a mailbox.
Disable Inbox Rule: Disables an inbox rule for a mailbox.
Create Inbox Rule: Creates an inbox rule for a mailbox.
Modify Inbox Rule: Modifies an inbox rule for a mailbox.
Delete Inbox Rule: Deletes an inbox rule from a mailbox.

Successful results for an action are placed in msg.payload.ms365exchange.[uniqueId].response. The inbox rule is accessible within rule for all actions except Get All Inbox Rules. For Get All Inbox Rules, an array of inbox rules is available within rules.

Mailbox

The Mailbox may be any value which uniquely identifies the malbox, such as name, alias, distinguished name, canonical DN, domain\username, email address, GUID, sAMAccountName, user ID, or UPN.

Inbox Rule

The inbox rule’s name or the rule identity number.

Settings

Create an inbox rule whose name is Inbox Rule within the Mailbox. The Settings define the set of values to provide as the initial settings for the inbox rule. The inbox rule must have at least one condition and one action. Multiple sets may be performed and will be processed in the order specified by the Settings list. Multiple settings may be performed on the same Parameter.

The Parameter is the name of the property to set. The full list of parameters is defined on the New-InboxRule page. Note, the properties being operated on are expected to be string like or boolean. The Parameter includes a few sample parameters for selection, but is not a comprehensive list. If the Parameter is an array, all the elements of the array are used to initialize an array value. If the Parameter is a string like or boolean value, the value of the parameter is directly set.

The Value should evaluate to a string, boolean, or an array. However, if the Value can not be determined, there will be no attempt to set the Parameter.

In addition to the standard response data, the array of settings to the inbox rule are placed within settings.

Updates

Modifies the inbox rule designated by Inbox Rule. The Updates define the set of operations to perform on the inbox rule. Multiple updates may be performed and will be processed in the order specified by the Updates list. Multiple updates may be performed on the same Parameter.

The Parameter is the name of the property to update. The full list of parameters is defined on the Set-InboxRule page. Note, the properties being operated on are expected to be string like or boolean. The Parameter includes a few sample parameters for selection, but is not a comprehensive list. The Operation defines the change to the Parameter. If the Parameter is an array, use the Add Entry to List or the Remove Entry from List operations. Otherwise, use the Set Entry or the Clear Entry operations. Do not use Clear Entry for boolean parameters, but, instead, set the value to false.

In addition to the standard response data, the array of changes to the inbox rule are placed within changes.

Node to manage a Mailbox's permissions and a mailbox folder's permissions within Outlook Online.

Property

Description

Name

The display name of the node within the flows.

Unique ID

System-wide unique ID of the plugin instance.

Action

Configuration option determining the type of operation to perform:

Get All Mailbox Permissions: Retrieves permission information for any user granted access to the Mailbox.
Get Mailbox Permissions for User: Retrieves permission information for the Permitted User if they were granted access to the Mailbox.
Add Mailbox Permission for User: Adds a permission to grant or deny Access Rights to the Permitted User within the Mailbox.
Remove Mailbox Permission for User: Removes a permission which granted or denied the Access Rights to the Permitted User within the Mailbox.
Reset Default Mailbox Permissions: Resets a Mailbox so only the mailbox owner has FullAccess permission to the mailbox.

Successful results for an action are placed in msg.payload.ms365exchange.[uniqueId].response. Retrieved mailbox permissions are placed in an array in mailboxPermissions. Addition of permissions and removal of permissions summary information is placed in mailboxPermissionUpdate. Removals return a Success flag within mailboxPermissionUpdate instead of the latest permissions since there are propagation delays within the cloud services.

Mailbox

Any value which uniquely identifies the malbox, such as name, alias, distinguished name, canonical DN, domain\username, email address, GUID, sAMAccountName, user ID, or UPN.

Permitted User

Any value which uniquely identifies a user or security group, such as name, distinguished name, canonical DN, or GUID.

Size Limit

The maximum number of results to return when performing a Get All Mailbox Permissions or Get All Mailbox Permissions for User operation.

Access Rights

If Access Rights is an array of access rights to allow or deny for the permission being added. If Access Rights is set to Manually Select Access Rights, the full set of available access rights are listed in a multi-select drop down list. Refer to the Add-MailboxPermission page for more details. If the access rights are generated dynamically from the selected context, the evaluated value may be either an array access right strings or a single access right string.

Deny Rights

The Deny Rights flag is parsed into a boolean value and if it evaluates to true, the selected Access Rights are denied instead of allowed. If the Deny Rights flag value can not be parsed, false is used.

Inheritance

The Inheritance options are All, Children, Descendents, and SelfAndChildren. There are convenience context options for selecting those predefined values.

Auto Mapping

The Auto Mappping flag determines if the Permitted User will automatically have the mailbox mounted within their Microsoft Outlook session. This value may only be set to true when the access right selected is FullAccess. If the Auto Mappping flag value can not be parsed, true is used.

Learn More

Plugin Behavior

Service Starts
PowerShell Started
If the PowerShell fails to start, the plugin remains active. A PowerShell connection will be attempted on any use of the Microsoft 365 Exchange nodes.

Microsoft 365 Exchange Node Behavior

The node uses a remote PowerShell connection to the Exchange Admin Center to perform its operations. The following steps describe the behavior of the plugin instance when a message is received at a node.

Node receives a message
If PowerShell is not running:
1. Start PowerShell
2. Wait for PowerShell to start
3. On failure, log failure and break out
  The failure will be logged to the Incident Timeline.
Perform the requested operation
Return results of operation

Permissions

Certificate Based Authentication (CBA) Permissions

The application associated with the Certificate Based Authentication must have the ability to manage mail flow rules in the Exchange Admin Center. Read through the following section for details on configuring an application with Azure AD to grant it access to manage mail flow rules. The same permissions give the application the ability to manage a mailbox’s inbox rules.

Azure AD Application Configuration for Certificate Based Authentication

The following steps can be used to configure an application within Azure AD with the appropriate permissions and role to manage the Exchange Admin Center.

Navigate to the Azure Active Directory admin center. Login using your existing admin account.
Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.
Select New registration. On the Register an application page, set the values as follows.
- Set Name to something meaningful, such as Nevelex Labs Security Flow EAC.
- By default, Supported account types is set to Accounts in this organizational directory only. Set Supported account types to Accounts in any organizational directory, if multi-tenant support is desired.
- Redirect URI (optional) may be left blank.
- Click the Register button.
Select API permissions. Follow the following sequence of steps to assign the Exchange.ManageAsApp permission to the newly registered application.
- Click the Add a permission button.
- In the newly opened Request API permissions pane, select the APIs my organization uses tab.
- Search for Office 365 Exchange Online and click it when found.
- Click the Application permissions button.
- Search for Exchange.ManageAsApp and select the associated checkbox when found.
- Click the Add permissions button. This will close the Request API permissions pane and add the permission to the application.
- Click the Grant admin consent for <tenant> button to enable the Exchange.ManageAsApp permission. Click the Yes button to confirm granting admin consent for the permission.

Create a self-signed certificate or obtain a certificate utilizing the standard IT procedures of your organization to associate a public certificate with the application. PowerShell or OpenSSL may be used to create a self-signed x.509 certificate in PFX format. The following example illustrates the processing for creating a self-signed certificate on Windows using PowerShell.


# Create a certificate which is valid for one year.
$SelfSignedCert = New-SelfSignedCertificate -DnsName "yourdomain.com" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange

# Export certificate to MS365_SelfSigned.pfx file with a password. 
$SelfSignedCert | Export-PfxCertificate -FilePath MS365_SelfSigned.pfx -Password $(ConvertTo-SecureString -String "the password" -Force -AsPlainText)

# Export the public certificate to MS365_SelfSigned.cer file for importing into the application in Azure AD.
$SelfSignedCert | Export-Certificate -FilePath MS365_SelfSigned.cer

Import the public certificate file, MS365_SelfSigned.cer from the example above, by performing the following steps.
- Click the Certificates & Secrets button within the application’s Azure AD page.
- Click the Upload certificate button and Add the MS365_SelfSigned.cer file.
Assign the application to a security group with a role, such as Exchange administrator to allow access to the Exchange Admin Center. The following steps describe creating a new security group and assigning the application to it.
- From the main Azure Active Directory blade, select Groups.
- Click the New Group button.
- Select a Group type of Security.
- Enter a meaningful name, such as Security Flow Exchange Admin, for the Group name.
- Ensure the Azure AD roles can be assigned to the group (Preview) is set to Yes.
- Click the No members selected link and add the application. It may be found by name or application ID. Once selected, click the Select button.
- Click the No roles selected link and add, for example, the Exchange administrator role. Assign a role which meets the lowest necessary level of access. Once selected, click the Select button.
- Click the Create button to create the new security group. Click the Yes button to confirm creating a group to which Azure AD roles can be assigned.

For additional information, read through the Microsoft App-only authentication for unattended scripts in the EXO V2 module page.

Basic Authentication Permissions

The user must have the ability to manage mail flow rules in the Exchange Admin Center. There are a number of existing roles which support this, but Exchange administrator is a reasonable choice. Assign a role which meets the lowest necessary level of access.

Nevelex Labs, Main Office

Metro Office Park
2950 Metro Drive, Suite 104
Bloomington, MN 55425
Phone: +1 952-500-8921

Contact Us

EULA