Changed in 51.0.9.0 Configuring an inbound email connection

Inbound email connections enable email messages to be received by the SOAR Platform, for example, messages from a phishing report service. Playbook designers can configure the SOAR Platform to automatically generate incidents from the messages, or add messages to existing incidents.

Before you begin

You must know which protocol is used by your email service and the account to use. Also, connections to mail servers with untrusted certificates fail by default. If you want to connect to an email server with an untrusted certificate, you must have a copy of that certificate available when prompted to upload it when the Test connection fails.

If your organization uses Exchange email servers, it is recommended that you use the Exchange (EWS) protocol when configuring your email connection in the following procedure. Otherwise, your system might have problems processing emails that are larger than 25 MB.

New in 51.0.9.0 Because Microsoft is planning to deprecate the Microsoft Exchange Web Services library, IBM Security® QRadar® SOAR now supports inbound email connections using Microsoft Graph. You can set up new OAuth connections for Microsoft Graph as described in this procedure about setting up new connections. To migrate existing EWS connections to use Microsoft Graph, follow the instructions described in New in 51.0.9.0 Migrating an OAuth EWS connection to MS graph.

About this task

You can configure one or more email connections from the Organization tab. An email connection applies only to the organization in which you configure it. Any existing email connections are shown from Email Connections on the Organization tab.

Procedure

Click Administrator Settings > Organization.
Select Inbound Email Connections and click Add Connection +.
In the Mailbox section, enter a name, API name, and a description for the email connection.
From the Connection Details section, determine the protocol that you want to use.
If you choose Exchange, complete the following fields.
- In the Endpoint field, enter the URL to connect to the email server in the format, https://<hostname>/<endpoint>, as shown in the following example.
```
https://outlook.office365.com/EWS/Exchange.asmx
```
- In the Email Address field, enter the email address of the target mailbox. If you are using a shared mailbox, enter it using the format primary_email\shared_email, where the shared email section must be in the format user@domain.com, similar to the following examples.
  Example 1.
```
primary_email@mail.com\shared_email@mail.com
```
  where primary_email@mail.com has access to the shared mailbox.
  Example 2.
```
myemailserver.com\info\sharedemail@myemailserver.com
```
- In the Password field, enter the password for the email address that you entered in the previous step. If you use a shared mailbox, enter the password for the primary email account that is used to access the shared email. If you are using a shared email account, enter that password if it has a password set.
- In the Source Folder field, you can also specify the mailbox folder from which unread email messages are retrieved. If the source folder is not specified, messages are retrieved from the Inbox folder.
- If using a proxy server, click Proxy to display the proxy connection fields, then enter the proxy information and authentication credentials.
  - For Protocol, determine whether the SOAR Platform is to connect to the proxy server over HTTP or HTTPS. If the protocol is HTTPS, you must have a proxy server certificate. If you are not using server certificates from a trusted certificate authority, you must upload your own certificate when you test the connection. If the specified protocol is HTTP, you do not need a server certificate.
  - In the Host Name field, enter the hostname or IP address of the proxy server.
  - In the Port field, determine which proxy server port to use for the inbound connection then enter the port number.
  - If authentication is needed to access the proxy server, enter the credentials in the User name and Password fields. You must enter the username, but the requirement to provide a password depends on the associated user account.
Changed in 51.0.9.0 If you choose IMAP, complete the following fields.
- In the Host Name field, enter the hostname or IP address of the email server.
- In the Port field, enter the port number to connect to the email server.
- In the Email Address field, enter the email address to connect to the target mailbox.
- In the Password field, enter the password for the email address that you entered in the previous step.
- Select an encryption method. The encryption method must be supported by the email service. Both the SSL/TLS and STARTTLS encryption methods require server certificates. If you are not using server certificates from a trusted certificate authority, you can select the SSL/TLS or STARTTLS encryption method and proceed to the following steps. After you test the connection, you can then upload your own certificate. If you select None for no encryption method, you do not require any certificate.
- If you are using encrypted email, enable the Enable Decryption option to display the Import email decryption key uploader and Password fields:
  - You can drag and drop a .pfx file or click to upload it. The .pfx file must contain one private key, one public certificate, and the complete certificate chain required for decryption. The maximum allowed file size is 1MB.
  - The password field is required to access the decryption key inside the uploaded file.
Changed in 51.0.9.0 If you choose the OAuth protocol, which is used for Office 365, complete the following fields:
- Leave the API Type at the default value, which is MS Graph.
- For the Endpoint drop-down, you can leave the default Graph endpoint, unless you want to use one of the other available Graph endpoints.
- In the Application (Client) ID field, enter your Microsoft Application client ID.
- If your Microsoft Entra app is single-tenant, enter the ID in the Directory (Tenant) ID field. If it is multi-tenant, leave this field blank.
- You can choose between a client secret or certificate validation. Click Client secret or Certificate, depending on whether you want to use a secret or certificate for validation with the Microsoft Entra application:
  - If you are using a client secret, enter the client secret for the Microsoft Entra ID in the Client Secret field.
  - If you are using a certificate, drag and drop or upload your private key in the upload component and enter the certificate thumbprint for the Microsoft Entra ID application.
    Note: For information about how to configure a certificate for Microsoft Entra ID, refer to the Microsoft documentation.
- In the Email Address field, enter the email address of the target mailbox. If you are using a shared mailbox, enter it using the format primary_email\shared_email, where the shared email section must be in the format user@domain.com, similar to the following examples.
  Example 1.
```
primary_email@mail.com\shared_email@mail.com
```
  where primary_email@mail.com has access to the shared mailbox.
  Example 2.
```
myemailserver.com\info\sharedemail@myemailserver.com
```
- You can also specify the mailbox folder in the Source Folder field, from which unread email messages are retrieved. If the source folder is not specified, messages are retrieved from the Inbox folder.
- In Microsoft Entra, grant the Mail.ReadWrite, Mail.ReadWrite.Shared and User.Read permissions as delegated permissions to your Microsoft Entra ID application. Grant admin consent for these permissions.
- In the Office 365 Access field, click Grant Access, and then log in to your Office 365 account.
- If you are using a proxy server, click Proxy to display the proxy connection fields then enter the proxy information and authentication credentials.
  - For Protocol, determine whether the SOAR Platform is to connect to the proxy server over HTTP or HTTPS. If the protocol is HTTPS, a proxy server certificate is needed. If you are not using server certificates from a trusted certificate authority, you must upload your own certificate when you test the connection. If the specified protocol is HTTP, a server certificate is not needed.
  - In the Host Name field, enter the hostname or IP address of the proxy server.
  - In the Port field, determine which proxy server port to use for the inbound connection then enter the port number.
  - If authentication is needed to access the proxy server, enter the credentials in the User name and Password fields. You must enter a username, but the requirement to provide a password depends on the associated user account.
  If you are using the Azure platform, you need to enter the SOAR Platform URL with /email-oauth appended at the end when you register the application and enter the redirect URI.
- If you are using encrypted email, enable the Enable Decryption option to display the Import email decryption key uploader and Password fields:
  - You can drag and drop a .pfx file or click to upload it. The .pfx file must contain one private key, one public certificate, and the complete certificate chain required for decryption. The maximum allowed file size is 1MB.
  - The password field is required to access the decryption key inside the uploaded file.
Click Save and Test Connection to validate that the connection works. If the connection is not successful, a message is displayed. Correct any problems and try again.

Note: If necessary, check the resilient-email.log file, which is located in the /var/log/resilient-email directory, and the client.log file, which is located in the /usr/share/co3/logs/ directory, for information to help troubleshoot any errors.

Results

The email connection is configured and the SOAR Platform can receive email messages. To delete the connection later, select Administrator Settings > Organization > Email Connections > Inbound. Then select the connection that you want to remove and click Delete.

If you used the OAuth protocol, Grant Access becomes Switch Account, which you use to change the Office 365 account used for the inbound email connection.

Note: Send a test email to your configured inbound email address to verify that the connection is working properly. The email should appear in the inbox.