Configuring Outbound Email

SL1 uses outbound email in a number of scenarios. Some examples of when SL1 sends outgoing email messages include: 

• Automatically, in response to Tickets from Email policies
• Automatically, in response to changes in a ticket (such as when the ticket is assigned, edited, or resolved)
• Automatically, based on Ticket Escalation policies
• Automatically, when executing Email Round-Trip Monitoring policies
• Automatically, when executing Run Book policies that include email actions
• Automatically, based on Report Jobs policies
• Manually, when a user selects the Send Message page from the ticket panel pages

This section describes how to configure the following encryption and authentication options for outbound email in SL1:

• Encryption using SMTP with TLS or SMTPS
• SMTP authentication using PLAIN/LOGIN/CRAM MD5
• SMTP authentication using OAuth2 (for Office 365 or Gmail)

While it is possible to configure SMTP encryption settings without implementing SMTP authentication for outbound email and vice versa, ScienceLogic recommends that you configure SMTP encryption if you are going to implement SMTP email authentication.

Use the following menu options to navigate the SL1 user interface:

• To view a pop-out list of menu options, click the menu icon ().
• To view a page containing all the menu options, click the Advanced menu icon ().

This section includes the following topics:

Configuring SMTP Encryption for Outbound Email

To ensure the security of outbound emails, ScienceLogic recommends implementing Simple Mail Transfer Protocol (SMTP) encryption. To configure SMTP encryption for outbound email in SL1, you must first know which encryption method your mail transfer agent (MTA) supports: 

• SMTP with Transport Layer Security (TLS), which is widely accepted as the preferred method for SMTP encryption
• Secure SMTP (SMTPS), which is supported for MTAs that require it but otherwise is not considered a preferred option

Using SMTP with TLS Encryption for Outbound Email

To configure SL1 to use SMTP with TLS encryption:

1. Either use SSH to access the primary Database Server or All-In-One Appliance and log in as an administrator, or log in to the classic SL1 user interface as an administrator and go to the Database Tool page (System > Tools > DB Tool.
2. Run the following SQL query:

UPDATE master.system_settings_com SET secure = 2 WHERE comm_method = 0;

Using SMTPS Encryption for Outbound Email

To configure SL1 to use SMTPS encryption: 

1. Either use SSH to access the primary Database Server or All-In-One Appliance and log in as an administrator, or log in to the classic SL1 user interface as an administrator and go to the Database Tool page (System > Tools > DB Tool.
2. Run the following SQL query:

UPDATE master.system_settings_com SET secure = 1 WHERE comm_method = 0;

Configuring SMTP Authentication for Outbound Email

To configure SMTP outbound email authentication in SL1, you must do the following: 

1. Create a credential for SMTP authentication.
2. Link the credential to the outbound email settings.

The type of authentication you use is determined by your mail server:

• If you are using Google/Gmail or Office 365 for outbound email, then you should use OAuth2 SMTP authentication.
• Otherwise, you should use PLAIN, LOGIN, or CRAM-MD5 SMTP authentication.

Configuring SMTP Authentication Using PLAIN, LOGIN, or CRAM-MD5 for Outbound Email

To configure SMTP authentication for mail servers that support PLAIN, LOGIN, or CRAM-MD5 authentication methods: 

1. Go to the Credentials page (Manage > Credentials).
2. Click the Create New button and then select Create Basic/Snippet Credential. The Create Credential modal appears.

3. Supply values in the following fields:

• Name. Type a unique name for the credential.
• Username. Type the username to be used for SMTP authentication.
• Password. Type the password to be used for SMTP authentication.
• Hostname/IP. Type "%D".

• Port. Type "25".

You must have values in the Hostname/IP and Port fields in order to save and use the credential, but these field values are not actually used for authentication.

4. Click Save & Close.
5. On the Credentials page, make a note the ID number of the credential you just created.
6. Either use SSH to access the primary Database Server or All-In-One Appliance and log in as an administrator, or log in to the classic SL1 user interface as an administrator and go to the Database Tool page (System > Tools > DB Tool.
7. Run the following SQL query, replacing <id> with the credential ID that you noted in the step 5:

UPDATE master.system_settings_com SET auth_cred = <id> WHERE comm_method = 0;

Configuring SMTP Authentication Using OAuth2 for Outbound Email

OAuth2—the Open Authorization 2.0 standard—uses a request/challenge exchange mechanism to retrieve authorization and refresh tokens.

• The authorization token is typically short-lived and is used for the SMTP authentication.
• The refresh token is used when the authorization token has expired and a new one is required.

ScienceLogic has created a helper script (smtp_auth_helper) that can help you perform the initial request/challenge exchange. After that exchange completes, the refresh token is cached and used to get authorization tokens as needed.

Refresh tokens might expire after a set period of time or might be manually expired. The OAuth2 provider controls this expiry; SL1 does not.

Configuring OAuth2 SMTP Authentication for Google/Gmail

To configure OAuth2 SMTP authentication for Google and Gmail: 

1. Ensure that your Google or Gmail account is properly configured for OAuth2, and that the correct SMTP relay permissions are set.

For information about configuring OAuth2 and setting the correct SMTP relay permissions for Google and Gmail, refer to Google's documentation.

2. In SL1, go to the Credentials page (Manage > Credentials).
3. Click the Create New button and then select Create SOAP/XML Credential. The Create Credential modal appears.
4. Supply values in the following fields:

• Name. Type a unique name for the credential.
• URL. Type "https://accounts.google.com/".
• HTTP Auth User. Type the email address or username of the account used to send email.
• HTTP Auth Password. Type the Client Secret from your OAuth2 provider.
• Embedded Password. Type the Client ID from your OAuth2 provider.
• Embed Value [%1]. Type "o/oauth2/auth".
• Embed Value [%2]. Type "o/oauth2/token".
• Embed Value [%3]. Leave this field is empty.
• Embed Value [%4]. Type "https://mail.google.com/".
• Curl Options. Select Referrer from the drop-down menu.
• Referrer. Type "urn:ietf:wg:oauth:2.0:oob".

5. Click Save & Close.
6. On the Credentials page, make a note the ID number of the credential you just created.
7. Now, you must authorize the system to use OAuth2 tokens. To do so, use SSH to access the primary Database Server or All-In-One Appliance as an administrator, and then run the following command:

sudo smtp_auth_helper

 

8. Select option 1.
9. Follow the prompts by first entering the credential ID you noted in step 6 and then press Enter.
10. When the question, "Are you using gmail?" appears, type "y" and then press Enter.
11. Verify the credential ID, and then type "y" and press Enter.

This will run the SQL query to enable SMTP encryption with TLS, and it will set the Email Gateway to smtp.googlemail.com:587 automatically.

12. The script will run a basic check of the credential to see if it contains the required information.

• If information is missing, it will print an error and the script will exit. In this scenario, you should correct the errors and then rerun the script. Continue doing this until all errors are fixed.
• If no information is missing, you can proceed to the next step.

13. A URL will appear. Open a web browser, copy and paste the full URL into the address bar, and then press Enter. Visiting this URL will grant you access to the system.
14. If your OAuth2 provider is configured correctly, you will prompted to log in to your Google account and authorize your OAuth2 provider application for email permissions. When you do so, you will receive a code.
15. Copy and paste the code into the Auth Code prompt, and then press Enter. The system will attempt to retrieve an OAuth2 token.
16. A message confirms whether the Oauth2 token retrieval was successful.

Configuring OAuth 2 SMTP Authentication for Office 365

To configure OAuth2 SMTP authentication for Office 365: 

1. Ensure that your Office 365 account is properly configured for OAuth2, and that the correct SMTP relay permissions are set.

For information about configuring OAuth2 and setting the correct SMTP relay permissions for Office 365, refer to Microsoft's documentation.

2. In SL1, go to the Credentials page (Manage > Credentials).
3. Click the Create New button and then select Create SOAP/XML Credential. The Create Credential modal appears.
4. Supply values in the following fields:

• Name. Type a unique name for the credential.
• URL. Type "https://login.microsoftonline.com/".
• HTTP Auth User. Type the email address or username of the account used to send email.
• Embedded Password. Type the Client ID from your OAuth2 provider.
• Embed Value [%1]. Type "oauth2/v2.0/devicecode".
• Embed Value [%2]. Type "oauth2/v2.0/token".
• Embed Value [%3]. Type your Tenant ID.
• Embed Value [%4]. Type "offline_access https://outlook.office.com/SMTP.Send".

5. Click Save & Close.
6. On the Credentials page, make a note the ID number of the credential you just created.
7. Now, you must authorize the system to use OAuth2 tokens. To do so, use SSH to access the primary Database Server or All-In-One Appliance as an administrator, and then run the following command:

sudo smtp_auth_helper

 

8. Select option 2.
9. Follow the prompts by first entering the credential ID you noted in step 6 and then press Enter.
10. When the question, "Are you using o365?" appears, type "y" and then press Enter.
11. Verify the credential ID is correct, and then type "y" and press Enter.

This will run the SQL query to enable SMTP encryption with TLS, and it will set the Email Gateway to outlook.office365.com:587 automatically.

12. The script will run a basic check of the credential to see if it contains the required information.

• If information is missing, it will print an error and the script will exit. In this scenario, you should correct the errors and then rerun the script. Continue doing this until all errors are fixed.
• If no information is missing, you can proceed to the next step.

13. A verification URL and verification code will appear. Open a web browser, copy and paste the full verification URL into the address bar, and then press Enter.
14. When prompted, copy and paste the verification code. You will then have 15 minutes to complete the remainder of the setup.
15. If your OAuth2 provider is configured correctly, you will prompted to log in to your Microsoft account and authorize your OAuth2 provider application for email permissions.
16. A message confirms whether the Oauth2 token retrieval was successful.

Testing SMTP Authentication

To verify that SMTP authentication is working as expected:

1. Use SSH to access the primary Database Server or All-In-One Appliance as an administrator, and then run the following command:

sudo smtp_auth_helper

 

2. Choose option 3. The system will perform a test of your mail server connection and authentication. No mail is sent during this test.
3. In the test output, confirm that the connection and authentication were successful.

The test output might be quite long. To determine if the test was successful, look in the last few lines for a message similar to "Authentication successful" to confirm that the authentication worked.