Mail Alerts Test

How often should the test be executed.

The host for which the test is to be configured.

Certificate-based authentication (CBA) enables customers to allow or require users to authenticate with X.509 certificates against their Azure Entra ID for applications and browser sign-in. When monitoring highly secure Office 365 environments, you should configure the eG agent to identify itself to a tenant using a valid X.509 certificate, so that it is allowed secure access to the tenant and its resources.

To achieve this, you should do the following:

1. Enable Azure Entra ID Certificate-based authentication for the target O365 tenant; this can be achieved manually, via the Office 365 portal, or automatically, using Powershell scripts we provide. For the manual procedure, refer to Manually Enabling Certificate-based Authentication For an Office 365 Tenant. For the automatic procedure, refer to Automatically Fulfilling Pre-requisites For Monitoring Microsoft Office 365 Environments.

   When enabling certificate-based authentication, an X.509 certificate will be generated for the target tenant.

2. Configure the Tenant Name parameter with the name of the tenant for which certificate-based authentication is enabled. Using the tenant name, the eG agent will be able to read the details of the X.509 certificate that is generated for that tenant, and use that certificate to access that tenant's resources. To determine the tenant name, do the following:

   • Log in to the Microsoft 365 Admin Center as an administrator.

   • Under Setup, click on Domains.

   • Find a domain that ends with .onmicrosoft.com - this is your Microsoft O365 tenant name.

This test pulls metrics by accessing the Microsoft Graph API. Therefore, for this test to run, the Microsoft Graph App should first be registered on Microsoft Entra ID, with a specific set of permissions. To know what these permissions are and which tests require these permissions, refer to eG Tests Requiring Microsoft Graph App Permissions.

This App can be created manually or using the proprietary PowerShell script that eG Enterprise provides. For the manual procedure, refer to Registering the Microsoft Graph App On Microsoft Entra ID. To use the PowerShell script, refer to Automatically Fulfilling Pre-requisites For Monitoring Microsoft Office 365 Environments.

To allow this test access to Microsoft Graph App, you need to configure the test with the Graph Client ID and Graph Client Secret of the registered application. The Client ID is a unique identifier for your application, while the Client Secret is a confidential string used to verify your application's identity to access protected resources. If you have manually registered the app in Microsoft Entra ID, then steps 5 and 6 of the procedure detailed in the Registering the Microsoft Graph App On Microsoft Entra ID topic will lead you to the Client ID and Client Secret of the app. Make a note of these details and use them to configure the Graph Client ID and Graph Client Secret parameters, respectively. On the other hand, if you have used eG's proprietary pre-requisites script to automatically create the Microsoft Graph app, then, step 13 of the procedure detailed in the Automatically Fulfilling Pre-requisites For Monitoring Microsoft Office 365 Environments topic will provide you with the Client ID and Client Secret of the graph app. Make a note and configure the Graph Client ID and Graph Client Secret parameters accordingly.

This test pulls metrics by accessing the Microsoft Graph API. Therefore, for this test to run, a Microsoft Graph App should first be registered on Microsoft Entra ID, with a specific set of permissions. To know what these permissions are and which tests require these permissions, refer to eG Tests Requiring Microsoft Graph App Permissions.

This App can be created manually or using the proprietary PowerShell script that eG Enterprise provides. For the manual procedure, refer to Registering the Microsoft Graph App On Microsoft Entra ID. To use the PowerShell script, refer to Automatically Fulfilling Pre-requisites For Monitoring Microsoft Office 365 Environments.

To interact with the Graph API and gather the required performance statistics, the eG agent running this test requires an access token. The SCOPE and AUTHORITY parameters within the access token are crucial for defining the scope of access and the authentication context, respectively. SCOPE specifies what resources the eG agent running this test can access, while AUTHORITY identifies the authentication provider. The Graph Scope and Graph Authority parameters of this test capture the SCOPE and AUTHORITY definitions (respectively) in the eG agent's access token.

By default, the Graph Scope parameter is set to https://graph.microsoft.com/.default. This is a common SCOPE for Microsoft Graph, allowing the eG agent to access all permissions that have been granted to the registered Microsoft Graph app within the Microsoft Entra ID. You can change this to match the SCOPE defined for the eG agent in your organization.

Similarly, the Graph Authority is set to https://login.microsoftonline.com/ by default. In this case, the tenant name or ID you specify against the Tenant Name parameter will be automatically appended to https://login.microsoftonline.com to complete the URL and set the default Graph Authority - i.e., https://login.microsoftonline.com/<Tenant_Name/ID>. This default setting indicates that Microsoft Entra ID will handle the authentication and authorization process.

Indicates the domain/IP address from which the test receives mails. Typically, this would be the domain/IP address of a POP3 or IMAP server.

Indicates the port number of the host, which receives the mails. The default port for POP3 is 110 and that of IMAP is 143.

The protocol to be used for receiving the mails (could be POP3 or IMAP).

Set this flag to Yes, if the target Mail Alert Receiver is SSL-enabled. Set this flag to No, if he target Mail Alert Receiver is not SSL-enabled.

Indicates the email account/user name available within the domain specified in the ReceiveHost from which the test receives mails. 

Indicates the password corresponding to the above user.

Confirm the Password by retyping it in this text box.

Specify a folder within the email account that is to be monitored. By default, inbox is specified against this text box.

Specify the time duration beyond which the POP3/IMAP server connection should timeout. The default value is 60000 ms.

Indicates the type of email content that is to be read from the mail. The default value for this parameter is plain/text. Alternately, you can provide text/html.

Enter a comma-separated list of specific patterns of mail subjects that need to be downloaded. The pattern should be in the format: <PatternName>:<Pattern> where <PatternName> is the pattern name that will be displayed in the monitor interface and <Pattern> is an expression of the form - *expr* or expr or *expr or expr*, etc. A leading '*' signifies any number of leading characters, while a trailing '*' signifies any number of trailing characters.

For example, specifying Critical_Alerts:*Critical* in this text box indicates that the test would download emails with the subject containing the word "Critical". By default, All is specified in this text box.

Multiple search patterns can be specified as a comma-separated list. For example, in case of alerts from SCOM, to categorize alerts separately for different alert priorities, configure the value as shown below:

Critical:*Severity*2*New*,Warning:*Severity*1*New*

The default value for this parameter is “All:*” which enables the test to download all mails.

Specify whether the test should delete mails after downloading from the server. By default, this value is set to false since the emails are downloaded from the same host. If you set this flag to true, then this test reads the emails based on the Subject Pattern specified and deletes the emails from the mailbox thereafter. Note that if this flag is set to true, you need to specify a dedicated email id in the ReceiveUser text box. Also, the test will attempt to download all the emails during every test execution for the specified email id.

These parameters are applicable only if the eG agent needs to communicate with the Office 365 portal via a Proxy server.

In this case, provide the IP/host name and port number of the Proxy server that the eG agent should use in the Proxy Host and Proxy Port parameters, respectively.

If the Proxy server requires authentication, then specify the credentials of a valid Proxy user against the Proxy User Name and Proxy Password text boxes. If the Proxy server does not require authentication, then specify none against the Proxy User Name, and Proxy Password text boxes.

On the other hand, if the eG agent is not behind a Proxy server, then you need not disturb the default setting of any of the Proxy-related parameters. By default, these parameters are set to none.

By default, this parameter is set to 50. This means that the detailed diagnosis of this test will by default display the first 50 email messages with a subject that matches the configured subject pattern. If you want, you can have more or fewer messages to be displayed as part of detailed diagnostics. For that, change the value of this parameter to a number of your choice.