Email connector and action

edit

Email connector and action

edit

The email connector uses the SMTP protocol to send mail messages. Email message text is sent as both plain text and html text.

  • For emails to have a footer with a link back to Kibana, set the server.publicBaseUrl configuration setting.
  • When the xpack.actions.email.domain_allowlist configuration setting is used, the email addresses used for all of the Sender (from), To, CC, and BCC properties must have email domains specified in the configuration setting.

Create connectors in Kibana

edit

You can create connectors in Stack Management > Connectors or as needed when you’re creating a rule. For example:

Email connector
Connector configuration
edit

Email connectors have the following configuration properties:

Name
The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
Sender
The from address for all emails sent with this connector. This must be specified in user@host-name format. See the Nodemailer address documentation for more information.
Service
The name of the email service. If service is one of Nodemailer’s well-known email service providers, the host, port, and secure properties are defined with the default values and disabled for modification. If service is MS Exchange Server, the host, port, and secure properties are ignored and tenantId, clientId, clientSecret are required instead. If service is other, the host and port properties must be defined.
Host
Host name of the service provider. If you are using the xpack.actions.allowedHosts setting, make sure this hostname is added to the allowed hosts.
Port
The port to connect to on the service provider.
Secure
If true, the connection will use TLS when connecting to the service provider. Refer to the Nodemailer TLS documentation for more information. If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command.
Tenant ID
The directory tenant that the application plans to operate against, in GUID format.
Client ID
The application ID that is assigned to your app, in GUID format. You can find this information in the portal where you registered your app.
Client Secret
The client secret that you generated for your app in the app registration portal. The client secret must be URL-encoded before being sent. The Basic auth pattern of providing credentials in the Authorization header, per RFC 6749, is also supported.
Require authentication
If true, a username and password for login type authentication must be provided.
Username
Username for login type authentication.
Password
Password for login type authentication.

Create preconfigured connectors

edit

If you are running Kibana on-prem, you can define connectors by adding xpack.actions.preconfigured settings to your kibana.yml file. For example:

xpack.actions.preconfigured:
  my-email:
    name: preconfigured-email-connector-type
    actionTypeId: .email
    config:
      service: other
      from: testsender@test.com
      host: validhostname
      port: 8080
      secure: false
    secrets:
      user: testuser
      password: passwordkeystorevalue

Config defines information for the connector type.

service
The name of the email service. If service is elastic_cloud (for Elastic Cloud notifications) or one of Nodemailer’s well-known email service providers, the host, port, and secure properties are ignored. If service is other, the host and port properties must be defined. For more information on the gmail service value, refer to Nodemailer Gmail documentation. If service is exchange_server, the tenantId, clientId, clientSecret properties are required instead of host and port.
from
An email address that corresponds to Sender.
host
A string that corresponds to Host.
port
A number that corresponds to Port.
secure
A boolean that corresponds to Secure.
hasAuth
A boolean that corresponds to Requires authentication. If true, this connector will require values for user and password inside the secrets configuration. Defaults to true.
tenantId
A GUID format value that corresponds to Tenant ID, which is a part of OAuth 2.0 Client Credentials Authentication.
clientId
A GUID format value that corresponds to Client ID, which is a part of OAuth 2.0 Client Credentials Authentication.

Secrets defines sensitive information for the connector type.

user
A string that corresponds to Username. Required if hasAuth is set to true.
password
A string that corresponds to Password. Should be stored in the Kibana keystore. Required if hasAuth is set to true.
clientSecret
A string that corresponds to Client Secret. Should be stored in the Kibana keystore. Required if service is set to exchange_server, which uses OAuth 2.0 Client Credentials Authentication.

Test connectors

edit

You can test connectors with the run connector API or as you’re creating or editing the connector in Kibana. For example:

Email params test

Email actions have the following configuration properties.

To, CC, BCC
Each item is a list of addresses. Addresses can be specified in user@host-name format, or in name <user@host-name> format. One of To, CC, or BCC must contain an entry.
Subject
The subject line of the email.
Message
The message text of the email. Markdown format is supported.

Connector networking configuration

edit

Use the Action configuration settings to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use xpack.actions.customHostSettings to set per-host configurations.

Configure email accounts for well-known services

edit

The email connector uses an integration of Nodemailer to send email from many popular SMTP email services. For Microsoft Exchange email, it uses the Microsoft Graph API.

To configure the email connector to work with common email systems, refer to:

For other email servers, you can check the list of well-known services that Nodemailer supports in the JSON file well-known/services.json. The properties of the objects in those files — host, port, and secure — correspond to the same email connector configuration properties. A missing secure property in the "well-known/services.json" file is considered false. Typically, port: 465 uses secure: true, and port: 25 and port: 587 use secure: false.

Sending email from Elastic Cloud
edit

Use the preconfigured email connector (Elastic-Cloud-SMTP) to send emails from Elastic Cloud.

For more information on the preconfigured email connector, see Elastic Cloud email service limits.

Sending email from Gmail
edit

Use the following email connector configuration to send email from the Gmail SMTP service:

  config:
    service: gmail
    // `host`, `port` and `secure` have the following default values and do not need to set:
    // host: smtp.gmail.com
    // port: 465
    // secure: true
  secrets:
    user: <username>
    password: <password>

If you get an authentication error that indicates that you need to continue the sign-in process from a web browser when the action attempts to send email, you need to configure Gmail to allow less secure apps to access your account.

If two-step verification is enabled for your account, you must generate and use a unique App Password to send email from Kibana. See Sign in using App Passwords for more information.

Sending email from Outlook.com
edit

Use the following email connector configuration to send email from the Outlook.com SMTP service:

config:
    service: outlook365
    // `host`, `port` and `secure` have the following default values and do not need to set:
    // host: smtp.office365.com
    // port: 587
    // secure: false
secrets:
    user: <email.address>
    password: <password>

When sending emails, you must provide a from address, either as the default in your connector configuration or as part of the email action in the rule.

You must use a unique App Password if two-step verification is enabled. See App passwords and two-step verification for more information.

Sending email from Amazon SES (Simple Email Service)
edit

Use the following email connector configuration to send email from the Amazon Simple Email Service (SES) SMTP service:

config:
    service: ses
    // `host`, `port` and `secure` have the following default values and do not need to set:
    // host: email-smtp.us-east-1.amazonaws.com 
    // port: 465
    // secure: true
secrets:
    user: <username>
    password: <password>

config.host varies depending on the region

You must use your Amazon SES SMTP credentials to send email through Amazon SES. For more information, see Obtaining Your Amazon SES SMTP Credentials. You might also need to verify your email address or your whole domain at AWS.

Sending email from Microsoft Exchange with Basic Authentication
edit

[7.16.0] Deprecated in 7.16.0. This Microsoft Exchange configuration is deprecated and will be removed later because Microsoft is deprecating basic authentication.

config:
    service: other
    host: <your exchange server>
    port: 465
    secure: true
    from: <email address of service account> 
secrets:
    user: <email address of service account> 
    password: <password>

Some organizations configure Exchange to validate that the from field is a valid local email account.

Many organizations support use of your email address as your username. Check with your system administrator if you receive authentication-related failures.

To prepare for the removal of Basic Auth, you must update all existing Microsoft Exchange connectors with the new configuration based on the OAuth 2.0 Client Credentials Authentication.

Sending email from Microsoft Exchange with OAuth 2.0
edit

The email connector uses Microsoft Graph REST API v1.0, in particular the sendMail endpoint. It supports only the Microsoft Graph global service root endpoint (https://graph.microsoft.com).

Before you create an email connector for Microsoft Exchange, you must create and register the client integration application on the Azure portal:

Register client application for MS Exchange

Next, open Manage > API permissions, and then define the permissions for the registered application to send emails. Refer to the documentation for the Microsoft Graph API.

MS Exchange API permissions

Add the "Mail.Send" permission for Microsoft Graph. The permission appears in the list with the status "Not granted for <your Azure active directory>":

MS Exchange "Mail.Send" not granted

Click Grant admin consent for <your Azure active directory>.

MS Exchange grant confirmation

Confirm that the status for the "Mail.Send" permission is now granted.

MS Exchange grant confirmation
Configure Microsoft Exchange Client secret
edit

To configure the Client secret , open Manage > Certificates & secrets.

MS Exchange secrets configuration

Add a new client secret, then copy the value and put it to the proper field in the Microsoft Exchange email connector.

Configure Microsoft Exchange Client ID and Tenant ID
edit

To find the application Client ID, open the Overview page.

MS Exchange Client ID and Tenant ID configuration

Copy and paste this values to the proper fields in the Microsoft Exchange email connector.

Use the following email connector configuration to send email from Microsoft Exchange:

config:
    service: exchange_server
    clientId: <The Application (client) ID> 
    tenantId: <The directory tenant ID, in GUID format.>
    from: <email address of service account> 
secrets:
    clientSecret: <URL-encoded string>

This application information is on the Azure portal – App registrations.

Some organizations configure Exchange to validate that the from field is a valid local email account.