Microsoft Graph Mail

This document provides guidance on how to integrate Microsoft Graph Mail with Google Security Operations SOAR.

Integration version: 17.0

Use cases

Integrating Microsoft Graph Mail with Google SecOps can help you solve the following use cases:

• Phishing email investigation and remediation: use the Google SecOps capabilities to identify malicious emails, automatically investigate the email headers, sender reputation, and attachments in phishing emails, and automate the threat remediation actions.

• Compromised account response: use the Google SecOps capabilities to analyze recent emails sent from the suspicious account, looking for potentially malicious activities like bulk forwarding or unusual login locations. The compromised account response can help you identify compromised accounts and facilitate response actions, such as password resets and email scanning for data exfiltration attempts.

Before you begin

Before configuring the integration in the Google SecOps platform, complete the following steps:

1. Create the Microsoft Entra app.

2. Configure the API permissions for your app.

3. Create a client secret.

Create Microsoft Entra app

To create the Microsoft Entra app, complete the following steps:

1. Sign in to the Azure portal as a user administrator or a password administrator.

2. Select Microsoft Entra ID.

3. Go to App registrations > New registration.

4. Enter the name of the app.

5. Click Register.

   This document provides an example using a single-tenant setup. The OAuth flow (client credentials) supported by the integration does not require the redirect URL.

6. Save the Application (client) ID and Directory (tenant) ID values to use them later when configuring the integration parameters.

Configure API permissions

To configure the API permissions for the integration, complete the following steps:

1. In Azure portal, go to API Permissions > Add a permission.

2. Select Microsoft Graph > Application permissions.

3. In the Select Permissions section, select the following required permissions:

   • Mail.Read
   • Mail.ReadWrite
   • Mail.Send
   • MailboxSettings.Read
   • MailboxSettings.ReadWrite
   • User.Read
   • Directory.Read.All

4. Click Add permissions.

5. Click Grant admin consent for YOUR_ORGANIZATION_NAME.

   When the Grant admin consent confirmation dialog appears, click Yes.

Create client secret

To create a client secret, complete the following steps:

1. Navigate to Certificates and secrets > New client secret.

2. Provide a description for a client secret and set its expiration deadline.

3. Click Add.

4. Save the value of the client secret (not the secret ID) to use it as the Secret ID parameter value when configuring the integration. The client secret value is only displayed once.

Integrate Microsoft Graph Mail with Google SecOps

The integration requires the following parameters:

For detailed instructions about configuring an integration in Google SecOps, see Configure integrations.

You can make changes at a later stage if needed. After you configure an integration instance, you can use it in playbooks. For more information about configuring and supporting multiple instances, see Supporting multiple instances.

Actions

Before you configure actions, provide the required permissions for the integration. For more detail, see the Configure API permissions section of this document.

Get Mailbox Account Out Of Facility Settings

Use the Get Mailbox Account Out Of Facility Settings action to retrieve the mailbox account out of facility (OOF) settings for the Google SecOps User entity provided.

The Get Mailbox Account Out Of Facility Settings action uses the beta version of Microsoft Graph API.

This action runs on the Google SecOps User entity.

Action inputs

None.

Action outputs

The Get Mailbox Account Out Of Facility Settings action provides the following outputs:

JSON result

The following example shows the JSON result output received when using the Get Mailbox Account Out Of Facility Settings action:

{
   "@odata.context": "https://graph.microsoft.com/beta/$metadata#communications/presences/$entity",
   "id": "ID",
   "availability": "Offline",
   "activity": "Offline",
   "statusMessage": null,
   "outOfOfficeSettings": {
       "message": "\n\nOut Of Facility111\n",
       "isOutOfOffice": true
   }
}

Output messages

The Get Mailbox Account Out Of Facility Settings action can return the following output messages:

Script result

The following table lists the value for the script result output when using the Get Mailbox Account Out Of Facility Settings action:

Delete Email

You can use the Delete Email action to delete one or more emails from a mailbox. This action deletes emails based on your search criteria. With the appropriate permissions, the Delete Email action can move emails into different mailboxes.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Delete Email action requires the following parameters:

Action outputs

The following table describes the output types associated with the Delete Email action:

Output messages

The Delete Email action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Delete Email action:

Download Attachments From Email

Use the Download Attachments From Email action to download attachments from emails based on the criteria provided.

This action isn't running on entities.

This action is asynchronous. If necessary, adjust the script timeout value in the Google SecOps IDE.

The action replaces the forward slash (\\) or backslash (/) characters in the names of the downloaded attachments with the underscore (_) character.

Action inputs

The Download Attachments From Email action requires the following parameters:

Action outputs

The Download Attachments From Email action provides the following outputs:

JSON result

The following example describes the JSON result output received when using the Download Attachments From Email action:

[
    {
        "attachment_name": "name1.png",
        "downloaded_path": "file_path/name1.png"
    },
    {
        "attachment_name": "name2.png",
        "downloaded_path": "file_path/name2.png"
    }
]

Output messages

The Download Attachments From Email action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Download Attachments From Email action:

Extract Data From Attached EML

Use the Extract Data From Attached EML action to retrieve data from the email EML attachments and return it in the action results. This action supports the .eml, .msg, and .ics file formats.

This action doesn't run on entities.

Action inputs

The Extract Data From Attached EML action requires the following parameters:

Action outputs

The Extract Data From Attached EML action provides the following outputs:

JSON result

The following example describes the JSON result output received when using the Extract Data From Attached EML action:

[
    {
        "type": "EML",
        "subject": "examplesubject",
        "from": "sender@example.com",
        "to": "user1@example.com,user2@example.com",
        "date": "Thu,4Jul202412:11:29+0530",
        "text": "text",
        "html": "<p>example-html</p>",
        "regex": {},
        "regex_from_text_part": {},
        "id": "ID",
        "name": "example.eml"
    },
    {
        "type": "MSG",
        "subject": "examplesubject",
        "from": "user@example.com",
        "to": "user1@example.com,user2@example.com",
        "date": "Thu,4Jul202412:11:29+0530",
        "text": "text",
        "html": "<p>examplehtml</p>",
        "regex": {},
        "regex_from_text_part": {},
        "id": "ID",
        "name": "example.msg"
    },
    {
        "type": "ICS",
        "subject": "examplesubject",
        "from": "sender@example.com",
        "to": "user1@example.com,user2@example.com",
        "date": "Thu,4Jul202412:11:29+0530",
        "text": "text",
        "html": "<p>example-html</p>",
        "regex": {},
        "regex_from_text_part": {},
        "id": "ID",
        "name": "example.ics"
    }
]

Output messages

The Extract Data From Attached EML action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Extract Data From Attached EML action:

Forward Email

Use the Forward Email action to forward emails that include previous threads. With the appropriate permissions, this action can send emails from a mailbox different than the one specified in the integration configuration.

This action doesn't run on entities.

Action inputs

The Forward Email action requires the following parameters:

Action outputs

The following table describes the output types associated with the Forward Email action:

Output messages

The Forward Email action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Forward Email action:

Mark Email as Junk

Use the Mark Email as Junk action to mark emails as junk in a specified mailbox. This action adds the email sender to the list of blocked senders and moves the message to the Junk Email folder.

The Mark Email as Junk action uses the beta version of Microsoft Graph API.

This action doesn't run on Google SecOps entities.

Action inputs

The Mark Email as Junk action requires the following parameters:

Action outputs

The Mark Email as Junk action provides the following outputs:

Output messages

The Mark Email as Junk action can return the following output messages:

Script result

The following table lists the value for the script result output when using the Mark Email as Junk action:

Mark Email as Not Junk

Use the Mark Email as Not Junk action to mark emails as not junk in a specific mailbox. This action removes the sender from the list of blocked senders and moves the message to the Inbox folder.

The Mark Email as Not Junk action uses the beta version of Microsoft Graph API.

This action doesn't run on Google SecOps entities.

Action inputs

The Mark Email as Not Junk action requires the following parameters:

Action outputs

The Mark Email as Not Junk action provides the following outputs:

Output messages

The Mark Email as Not Junk action can return the following output messages:

Script result

The following table lists the value for the script result output when using the Mark Email as Not Junk action:

Move Email To Folder

Use the Move Email To Folder action to move one or multiple emails from the source email folder to the other folder in the mailbox. With the appropriate permissions, this action can move emails to other mailboxes different from the one that is provided in the integration configuration.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run entities.

Action inputs

To configure the Move Email To Folder action, use the following parameters:

Action outputs

The following table describes the output types associated with the Move Email To Folder action:

Output messages

The Move Email To Folder action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Move Email To Folder action:

Ping

Use the Ping action to test connectivity to the Microsoft Graph mail service.

This action doesn't run on entities.

Action inputs

None.

Action outputs

The following table describes the output types associated with the Ping action:

Output messages

The Ping action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Ping action:

Save Email To The Case

Use the Save Email To The Case action to save emails or email attachments to the Google SecOps Case Wall. With the appropriate permissions, this action can save emails from mailboxes other than the one provided in the integration configuration.

This action doesn't run on entities.

Action inputs

The Save Email To The Case action requires the following parameters:

Action outputs

The following table describes the output types associated with the Save Email To The Case action:

Case wall attachment

The following attachments are associated with the Save Email To The Case action:

• EMAIL_SUBJECT.eml, if the action saves the email.

• If the action saves the attachment, the attachment name contains a file extension, if any.

JSON result

The following example describes the JSON result output received when using the Save Email To The Case action:

{
    "id": "ID",
    "createdDateTime": "2024-02-16T14:10:34Z",
    "eml_info": "example_info",
    "lastModifiedDateTime": "2024-02-16T14:10:41Z",
    "changeKey": "cxsdjjh",
    "categories": [],
    "receivedDateTime": "2024-02-16T14:10:35Z",
    "sentDateTime": "2024-02-16T14:09:36Z",
    "hasAttachments": true,
    "internetMessageId": "INTERNET_MESSAGE_ID",
    "subject": "all attachments",
    "bodyPreview": "all the attachments",
    "importance": "normal",
    "parentFolderId": "PARENT_FOLDER_ID",
    "conversationId": "CONVERSATION_ID",
    "conversationIndex": "example-index",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": false,
    "webLink": "https://example.com/",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "<html><head>example-html</head></html>"
    },
    "sender": {
        "emailAddress": {
            "name": "NAME",
            "address": "sender@example.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "NAME",
            "address": "user@example.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "NAME",
                "address": "recipient@example.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
        "flagStatus": "notFlagged"
    }
}

Output messages

On a Case Wall, the Save Email To The Case action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Save Email To The Case action:

Search Emails

Use the Search Emails action to execute email search in the default mailbox based on the provided search criteria. With appropriate permissions, this action can run a search in other mailboxes.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Search Emails action requires the following parameters:

Action outputs

The following table describes the output types associated with the Search Emails action:

Case wall table

On a Case Wall, the Search Emails action provides the following table:

Table title: Matching Mails

Columns:

• Mail ID
• Subject
• Sender
• Receivers
• Received Date

Output messages

The Search Emails action provides the following output messages:

Action was not able to find any emails based on the specified search criteria.

Script result

The following table describes the values for the script result output when using the Search Emails action:

Send Email

Use the Send Email action to send emails from a specific mailbox to an arbitrary list of recipients.

This action can send either plain text or HTML-formatted emails. With appropriate permissions, the action can send emails from a mailbox different than the one specified in the integration configuration.

This action doesn't run on entities.

Action inputs

The Send Email action requires the following parameters:

Action outputs

The following table describes the output types associated with the Send Email action:

Output messages

The Send Email action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Send Email action:

Send Email HTML

Use the Send Email HTML action to send emails using the Google SecOps HTML template from a specific mailbox to an arbitrary list of recipients. With appropriate permissions, the action can send emails from a mailbox other than the default one.

This action doesn't run on entities.

Action inputs

The Send Email HTML action requires the following parameters:

Action outputs

The Send Email HTML action provides the following outputs:

JSON result

The following example describes the JSON result output received when using the Send Email HTML action:

{
    "createdDateTime": "2024-01-30T16:50:27Z",
    "lastModifiedDateTime": "2024-01-30T16:50:27Z",
    "changeKey": "example-key",
    "categories": [],
    "receivedDateTime": "2024-01-30T16:50:27Z",
    "sentDateTime": "2024-01-30T16:50:27Z",
    "hasAttachments": false,
    "internetMessageId": "outlook.com",
    "subject": "Testing",
    "bodyPreview": "example",
    "importance": "normal",
    "parentFolderId": "ID",
    "conversationId": "ID",
    "conversationIndex": "INDEX",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": false,
    "webLink": "https://example.com",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "content"
    },
    "sender": {
        "emailAddress": {
            "name": "NAME",
            "address": "sender@example.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "NAME",
            "address": "user@example.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "NAME",
                "address": "recipient@example.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "uniqueBody": {
        "contentType": "html",
        "content": "content"
    },
    "flag": {
        "flagStatus": "notFlagged"
    },
    "id": "ID"
}

Output messages

On a Case Wall, the Send Email HTML action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Send Email HTML action:

Send Thread Reply

Use the Send Thread Reply action to send a message as a reply to the email thread. With appropriate permissions, the action can send emails from a mailbox other than the one specified in the integration configuration.

This action doesn't run on entities.

Action inputs

The Send Thread Reply action requires the following parameters:

Action outputs

The following table describes the output types associated with the Send Thread Reply action:

Output messages

The Send Thread Reply action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Send Thread Reply action:

Send Vote Email

Use the Send Vote Email action to send emails with the predefined answering options. This action uses Google SecOps HTML templates to format the email. With appropriate permissions, the Send Vote Email action can send emails from a mailbox other than the default one.

This action doesn't run on entities.

Action inputs

The Send Vote Email action requires the following parameters:

Action outputs

The Send Vote Email action provides the following outputs:

JSON result

The following example describes the JSON result output received when using the Send Vote Email action:

{
    "createdDateTime": "2024-01-30T16:50:27Z",
    "lastModifiedDateTime": "2024-01-30T16:50:27Z",
    "changeKey": "KEY",
    "categories": [],
    "receivedDateTime": "2024-01-30T16:50:27Z",
    "sentDateTime": "2024-01-30T16:50:27Z",
    "hasAttachments": false,
    "internetMessageId": "<example-message-ID>",
    "subject": "Testing",
    "bodyPreview": "example",
    "importance": "normal",
    "parentFolderId": "FOLDER_ID",
    "conversationId": "CONVERSATION_ID",
    "conversationIndex": "CONVERSATION_INDEX",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": false,
    "webLink": "https://www.example.com/about",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "content"
    },
    "sender": {
        "emailAddress": {
            "name": "NAME",
            "address": "sender@example.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "NAME",
            "address": "user@example.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "NAME",
                "address": "recipient@example.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "uniqueBody": {
        "contentType": "html",
        "content": "content"
    },
    "flag": {
        "flagStatus": "notFlagged"
    },
    "id": "ID"
}

Output messages

On a Case Wall, the Send Vote Email action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Send Vote Email action:

Wait For Email From User

Use the Wait For Email From User action to wait for the user's response based on an email sent using the Send Email action.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Wait For Email From User action requires the following parameters:

Action outputs

The following table describes the output types associated with the Wait For Email From User action:

Case wall attachment

The following Case Wall attachment is associated with the Wait For Mail From User action:

Type: Entity

Attachment content: Title, Filename (extensions included, if any), fileContent.

• Title: RECIPIENT_EMAIL reply attachment.
• Filename: ATTACHMENT_FILENAME + FILE_EXTENSION
• fileContent: CONTENT_OF_THE_ATTACHED_FILE

Case wall table

On a Case Wall, the Wait For Mail From User action generates the following table:

Table title: Matching Mails

Columns:

• Mail ID
• Received Date
• Sender
• Recipients
• Subject

Output messages

The Wait For Mail From User action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Wait For Email From User action:

Wait For Vote Email Results

Use the Wait For Vote Email Results action to wait for the user response based on the vote email sent using the Send Vote Email action.

This action is asynchronous. Adjust the action timeout in the IDE accordingly.

This action doesn't run on entities.

Action inputs

The Wait For Vote Email Results action requires the following parameters:

Action outputs

The Wait For Vote Email Results action provides the following outputs:

Case wall attachment

The following Case Wall attachment is associated with the Wait For Vote Email Results action:

Type: Entity

Attachment content: Title, Filename (extensions included, if any), fileContent.

• Title: RECIPIENT_EMAIL reply attachment.
• Filename: ATTACHMENT_FILENAME + FILE_EXTENSION
• fileContent: CONTENT_OF_THE_ATTACHED_FILE

Case wall table

On a Case Wall, the Wait For Email Results action generates the following table:

Table title: Matching Mails

Columns:

• Mail ID
• Received Date
• Sender
• Recipients
• Subject

JSON result

The following example describes the JSON result output received when using the Wait For Vote Email Results action:

{
    "Responses": [
        {
            "recipient": "user@example.com",
            "vote": "Approve"
        }
    ]
}

Output messages

The Wait For Vote Email Results action provides the following output messages:

Script result

The following table describes the values for the script result output when using the Wait For Vote Email Results action:

Connectors

For detailed instructions on how to configure a connector in Google SecOps, see Ingest your data (connectors).

Microsoft Graph Mail Connector

Use the Microsoft Graph Mail Connector to fetch emails from the Microsoft Graph mail service.

Use the dynamic list to filter specific values from the email body and subject parts using regular expressions. By default, the connector uses a regular expression to filter out the URLs from the email.

Connector parameters

The connector requires the following parameters:

Connector rules

The connector supports proxies.