Configure the Office 365 Email LAM
The Office 365 Email LAM allows you to retrieve emails using the Microsoft Graph API to connect to Office 365 accounts and send them to Moogsoft Enterprise as events.
You can install a basic Office 365 Email integration in the UI. See Office 365 Email for integration steps.
Configure the Office 365 Email LAM if you want to configure custom properties, set up high availability or configure advanced options that are not available in the UI integration.
Before you begin
Before you configure the Office 365 Email LAM, ensure you have met the following requirements:
You have registered an App in Azure Active Directory with the following permissions:
Mail.ReadWrite (Application): This enables the integration to read email messages and mark as read/delete on retrieval. Note that an Application permission enables access to all Mailboxes within the organization.
See the Microsoft Azure documentation for instructions on restricting the application to a particular Mailbox.
User.Read (Delegated): This enables the integration to acquire the necessary user information for configuration.
See the Microsoft Graph Permissions Reference for more information on permissions.
You have enabled Access Token Implicit grant flow (located under the Authentication section) for the registered App. See the Microsoft Azure documentation for more information.
You have noted the following details from the registered App:
Application (Client) ID
Client Secret
Directory (Tenant) ID
Email address
Configure the LAM
Edit the configuration file to control the behavior of the Office 365 Email LAM. You can find the file at $MOOGSOFT_HOME/config/office365_email_lam.conf.
See the Office 365 Email LAM Reference and LAM and Integration Reference for a full description of all properties. Some properties in the file are commented out by default; remove the '#' character to enable them.
Configure the connection properties for each Office 365 account:
auth_url: Authentication URL to get the access token from Office 365.
resource_url: Resource URL to access Office 365 email.
folder_path: Name of the folder containing the email messages, for example INBOX.
client_id: The ID of the account registered on Microsoft Azure.
client_secret or encrypted_client_secret: Password or encrypted password of the account used to connect to Office 365.
tenant_id: The tenant ID of the application registered on Microsoft Azure.
user_email: The user email address.
Determine how to treat messages for each target:
retrieve: Whether to receive all email messages or only unread messages.
retrieve_filter: One or more filters to limit the email messages to retrieve.
mark_as_read: Marks unread emails as read.
delete_on_retrieve: Whether to delete email messages on retrieval.
remove_html_tags: Whether to remove HTML tags from email messages.
treat_body_as_json: Decodes the email body into a JSON object and makes it available for mapping.
Configure the LAM behavior for each target:
num_threads: Number of worker threads to use when processing events.
event_ack_mode: Determines whether Moogfarmd acknowledges events from the LAM when they are added to the Moolet queue, or when a Moolet processes them.
request_interval: Length of time to wait between requests, in seconds.
max_retries: Number of times the LAM attempts to reconnect after connection failure.
retry_interval: Length of time to wait between reconnection attempts, in seconds.
recovery_interval: Length of time to wait between requests, in seconds, when the LAM re-establishes a connection after a failure.
max_lookback: Period of time for which to recover missed events, in seconds, when the LAM re-establishes a connection after a failure.
timeout: Length of time to wait before halting a connection or read attempt, in seconds.
Configure the SSL properties for each target using IMAPS or POP3S protocol:
disable_certification_validation: Whether to disable SSL certificate validation.
path_to_ssl_files: Path to the directory that contains the SSL certificates.
server_cert_filename: Name of the SSL root CA file.
client_key_filename: Name of the SSL client key file.
client_cert_filename: Name of the SSL client certificate.
If you want to connect through a proxy server, configure the host, port, user, and password or encrypted password properties in the proxy section for the target.
Optionally configure the LAM identification and capture logging details:
name: Maps to
$Laminstancename, so that theagentfield indicates events Moogsoft Enterprise ingests from this LAM.capture_log: Name and location of the LAM's capture log file, which it writes to for debugging purposes.
Optionally configure severity conversions. See Severity Reference for further information and "Conversion Rules" in Tokenize Source Event Data for details on conversions in general.
Optionally configure the process logging details:
configuration_file: Name and location of the LAM's process log configuration file. See Configure Logging for more information.
Example
You can configure the Office 365 Email LAM to retrieve messages from one or more accounts. If you use more than one Office 365 email server or multiple email folders on a single server, configure multiple targets according to the example.
The following example demonstrates a scenario in which you configure the Office 365 LAM to use two email addresses as event sources. For a single account, comment out the target2 section. If you want to configure more than two accounts, add a target section for each one and uncomment properties to enable them.
monitor:
{
name : "Office 365 Email Monitor",
class : "COffice365EmailMonitor",
request_interval : 60,
max_retries : -1,
retry_interval : 60,
targets:
{
target1:
{
auth_url : "https://login.microsoftonline.com","
resource_url : "https://graph.microsoft.com",
folder_path : "INBOX",
client_id : "client_id",
client_secret : "password",
tenant_id : "tenant_id",
user_email : "johndoe@example.com",
retrieve : "UNREAD",
retrieve_filter:
{
to : [ "joebloggs@example.com", "fredbloggs@example.com" ],
from : [ "jeandupont@example.com", "m.durand@example.com" ],
#recipient : [ ],
subject : [ "Alert", "Event" ],
#body : ""
},
mark_as_read : false,
delete_on_retrieve : false,
remove_html_tags : true,
treat_body_as_json : false;
disable_certificate_validation : true,
#path_to_ssl_files : "config",
#server_cert_filename : "server.crt",
#client_key_filename : "client.key",
#client_cert_filename : "client.crt",
#ssl_protocols : [ "TLSv1.2" ],
num_threads : 5
event_ack_mode : "queued_for_processing",
request_interval : 60,
max_retries : -1,
retry_interval : 60,
timeout : 120,
retry_recovery:
{
recovery_interval : 20,
max_lookback : -1
}
},
target2:
{
auth_url : "https://login.microsoftonline.comlocalhost",
resource_url : "https://graph.microsoft.comlocalhost",
folder_path : "INBOX",
client_id : "client_id",
encrypted_client_secret : "qJAFVXpNDTk6ANq65pEfVGNCu2vFdcoj70AF5BIebEc=",
user_email : "janedoe@example.com",
tenant_id : "tenant_id",
retrieve : "UNREAD",
retrieve_filter:
{
to : [ "bobsmith@example.com", "sallysmith@example.com" ],
from : [ "johnblack@example.com", chriswong@example.com" ],
#recipient : [ ],
subject : [ "Alert", "Event" ],
#body : ""
},
proxy:
{
host: "localhost",
port: 80
user: "John.Doe",
password: ""
#encrypted_password: "ieytOFRUdLpZx53nijEw0rOh07VEr8w9lBxdCc7229o="
},
mark_as_read : true,
delete_on_retrieve : false,
remove_html_tags : true,
treat_body_as_json : false;
disable_certificate_validation : false,
path_to_ssl_files : "config",
server_cert_filename : "server.crt",
client_key_filename : "client.key",
client_cert_filename : "client.crt",
ssl_protocols : [ "TLSv1.1, TLSv1.2" ],
num_threads : 5
event_ack_mode : "event_processed",
request_interval : 60,
max_retries : 20,
retry_interval : 120,
timeout : 180,
proxy:
{
host : "localhost",
port : 8080
},
retry_recovery:
{
recovery_interval : 20,
max_lookback : -1
}
}
}
},
agent:
{
name : "Office365Email",
capture_log : "$MOOGSOFT_HOME/log/data-capture/office365_email_lam.log"
},
log_config:
{
configuration_file : "$MOOGSOFT_HOME/config/logging/office365_Eemail_lam_log.json"
},Configure for High Availability
Configure the Office 365 Email LAM for high availability if required. See High Availability Overview for details.
Configure LAMbot Processing
The Office 365 Email LAMbot processes and filters events before sending them to the Message Bus. You can customize or bypass this processing if required. You can also load JavaScript files into the LAMbot and execute them.
See LAMbot Configuration for more information. An example Office 365 Email LAM filter configuration is shown below.
filter:
{
presend: "Office365EmailLam.js"
}Map LAM Properties
Office 365 Email header properties are mapped by default to the following Moogsoft Enterprise Office 365 Email LAM properties. The overflow properties are mapped to "custom info" and appear under Overflow in Moogsoft Enterprise alerts. You can configure custom mappings in the Office 365 Email LAMbot.
Office 365 Email Header Property | Office 365 Email LAM Event Property |
|---|---|
Agent |
|
Agent Location |
|
Agent Time |
|
Description |
|
External ID |
|
Manager |
|
Severity |
|
Signature |
|
Source ID |
|
Type |
|
For a list of the overflow properties, refer to the JSON payloads here.
Start and Stop the LAM
Restart the Office 365 Email LAM to activate any changes you make to the configuration file or LAMbot.
The LAM service name is office365emaillamd.
See Control Moogsoft Enterprise Processes for further details.