IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« xMatters connector and action License Management »

› › ›

Preconfigured connectors

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Preconfigured connectors

edit

If you are running Kibana on-prem, you can preconfigure a connector to have all the information it needs prior to startup by adding it to the kibana.yml file.

Elasticsearch Service provides a preconfigured email connector but you cannot create additional preconfigured connectors.

Preconfigured connectors offer the following benefits:

Require no setup. Configuration and credentials needed to run an action are predefined, including the connector name and ID.
Appear in all spaces because they are not saved objects.
Cannot be edited or deleted.

Create preconfigured connectors

edit

Add xpack.actions.preconfigured settings to your kibana.yml file. The settings vary depending on which type of connector you’re adding. Refer to Preconfigured connector settings.

This example shows a valid configuration for a Slack connector and a Webhook connector:

  xpack.actions.preconfigured:
    my-slack1:                  
      actionTypeId: .slack      
      name: 'Slack #xyz'        
      secrets:
        webhookUrl: '<WEBHOOK_URL>' 
    webhook-service:
      actionTypeId: .webhook
      name: 'Email service'
      config:                   
        url: '<SERVICE_URL>' 
        method: post
        headers:
          header1: value1
          header2: value2
      secrets:                  
        user: elastic
        password: changeme

	The key is the connector identifier, `my-slack1` in this example.
	`actionTypeId` is the action type identifier.
	`name` is the name of the preconfigured connector.
	`config` is the configuration specific to the connector type.
	`secrets` is the sensitive configuration, such as username, password, and keys, specific to the connector type.

Sensitive properties, such as passwords, can also be stored in the Kibana keystore.

View preconfigured connectors

edit

When you open the main menu, click Stack Management > Connectors. Preconfigured connectors appear regardless of which space you are in. They are tagged as “preconfigured”, and you cannot delete them.

Connectors managing tab with pre-configured

Clicking a preconfigured connector shows the description, but not the configuration.

Built-in preconfigured connectors

edit

Kibana provides the following built-in preconfigured connectors:

Preconfigured alert history Elasticsearch index connector

edit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Kibana offers a preconfigured index connector to facilitate indexing active alert data into Elasticsearch. To use this connector, set xpack.actions.preconfiguredAlertHistoryEsIndex to true.

When you subsequently create rules, you can use the Alert history Elasticsearch index (preconfigured) connector.

Creating a rule action that uses the pre-configured alert history connector

Documents are indexed using a preconfigured schema that captures the action variables available for the rule. By default, these documents are indexed into the kibana-alert-history-default index, but you can specify a different index. Index names must start with kibana-alert-history- to take advantage of the preconfigured alert history index template.

To write documents to the preconfigured index, you must have all or write privileges to the kibana-alert-history-* indices.
The kibana-alert-history-* indices are not configured to use ILM so they must be maintained manually. If the index size grows large, consider using the delete by query API to clean up older documents in the index.

Examples

edit

Amazon Bedrock connectors

edit

The following example creates an Amazon Bedrock connector:

xpack.actions.preconfigured:
  my-bedrock:
    name: preconfigured-bedrock-connector-type
    actionTypeId: .bedrock
    config:
      apiUrl: <REQUEST_URL> 
      defaultModel: anthropic.claude-v2 
    secrets:
      accessKey: key-value 
      secret: secret-value

	The Amazon Bedrock request URL.
	The default model to use for requests. Current support is for the Anthropic Claude models, defaulting to Claude 2.
	The AWS access key for authentication.
	The AWS secret for authentication.

D3 Security connectors

edit

The following example creates a D3 Security connector:

xpack.actions.preconfigured:
  my-d3security:
    name: preconfigured-d3security-connector-type
    actionTypeId: .d3security
    config:
      url: <URL> 
    secrets:
      token: <TOKEN>

	The D3 Security API request URL.
	The D3 Security token.

Email connectors

edit

The following example creates an email connector:

xpack.actions.preconfigured:
  my-email:
    name: preconfigured-email-connector-type
    actionTypeId: .email
    config:
      service: other 
      from: [email protected] 
      host: validhostname 
      port: 8080 
      secure: false 
      hasAuth: true 
    secrets:
      user: testuser 
      password: passwordkeystorevalue

	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`.
	The email address for all emails sent with this connector. It must be specified in `user@host-name` format.
	The host name of the service provider.
	The port to connect to on the service provider.
	If true, the connection will use TLS when connecting to the service provider.
	If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
	A user name for authentication. Required if `hasAuth` is set to `true`.
	A password for authentication. Should be stored in the Kibana keystore. Required if `hasAuth` is set to `true`.

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

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>

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.

Microsoft Exchange with OAuth 2.0

edit

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.

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>

OpenAI connectors

edit

The following example creates a OpenAI connector:

xpack.actions.preconfigured:
  my-open-ai:
    name: preconfigured-openai-connector-type
    actionTypeId: .gen-ai
    config:
      apiUrl: <REQUEST_URL> 
      apiProvider: 'OpenAI' 
      defaultModel: gpt-4 
    secrets:
      apiKey: superlongapikey

	The OpenAI request URL.
	The OpenAI API provider, either `OpenAI` or `Azure OpenAI`.
	The default model to use for requests. This setting is optional and applicable only when `apiProvider` is `OpenAI`.
	The OpenAI or Azure OpenAI API key for authentication.

IBM Resilient connectors

edit

The following example creates a IBM Resilient connector:

xpack.actions.preconfigured:
 my-resilient:
    name: preconfigured-resilient-connector-type
    actionTypeId: .resilient
    config:
      apiUrl: <API_URL> 
      orgId: ES 
    secrets:
      apiKeyId: testuser 
      apiKeySecret: tokenkeystorevalue

	The IBM Resilient instance URL.
	The IBM Resilient organization identifier.
	The authentication key ID for HTTP basic authentication.
	The authentication key secret for HTTP basic authentication. NOTE: This value should be stored in the Kibana keystore.

Index connectors

edit

The following example creates a index connector:

xpack.actions.preconfigured:
  my-index:
    name: preconfigured-index-connector-type
    actionTypeId: .index
    config:
      index: .kibana 
      executionTimeField: my-field

	The Elasticsearch index to be written to.
	A field that indicates when the document was indexed.

Jira connectors

edit

The following example creates a Jira connector:

xpack.actions.preconfigured:
  my-jira:
    name: preconfigured-jira-connector-type
    actionTypeId: .jira
    config:
      apiUrl: <JIRA_INSTANCE_URL> 
      projectKey: ES 
    secrets:
      email: testuser 
      apiToken: tokenkeystorevalue

	The Jira instance URL.
	The Jira project key.
	The account email for HTTP basic authentication.
	The API authentication token for HTTP basic authentication. NOTE: This value should be stored in the Kibana keystore.

Microsoft Teams connectors

edit

The following example creates a Microsoft Teams connector:

xpack.actions.preconfigured:
  my-teams:
    name: preconfigured-teams-connector-type
    actionTypeId: .teams
    secrets:
      webhookUrl: '<WEBHOOK_URL>'

The URL of the incoming webhook.

Opsgenie connectors

edit

The following example creates an Opsgenie connector:

xpack.actions.preconfigured:
  my-opsgenie:
    name: preconfigured-opsgenie-connector-type
    actionTypeId: .opsgenie
    config:
      apiUrl: <OPSGENIE_URL> 
    secrets:
      apiKey: apikey

	The Opsgenie URL.
	The Opsgenie API authentication key for HTTP basic authentication.

PagerDuty connectors

edit

The following example creates a PagerDuty connector:

xpack.actions.preconfigured:
  my-pagerduty:
    name: preconfigured-pagerduty-connector-type
    actionTypeId: .pagerduty
    config:
      apiUrl: <API_URL> 
    secrets:
      routingKey: testroutingkey

	The PagerDuty event URL.
	A 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key.

Server log connectors

edit

The following example creates a server log connector:

xpack.actions.preconfigured:
  my-server-log:
    name: preconfigured-server-log-connector-type
    actionTypeId: .server-log

ServiceNow ITOM connectors

edit

The following example creates a ServiceNow ITOM connector with basic authentication:

xpack.actions.preconfigured:
  my-servicenow-itom:
    name: preconfigured-servicenow-connector-type
    actionTypeId: .servicenow-itom
    config:
      apiUrl: https://example.service-now.com/ 
    secrets:
      username: testuser 
      password: passwordkeystorevalue

	The ServiceNow instance URL.
	A user name.
	A password. NOTE: This value should be stored in the Kibana keystore.

The following example creates a ServiceNow ITOM connector with OAuth authentication:

xpack.actions.preconfigured:
  my-servicenow:
    name: preconfigured-oauth-servicenow-connector-type
    actionTypeId: .servicenow-itom
    config:
      apiUrl: https://example.service-now.com/
      isOAuth: true 
      userIdentifierValue: [email protected] 
      clientId: abcdefghijklmnopqrstuvwxyzabcdef 
      jwtKeyId: fedcbazyxwvutsrqponmlkjihgfedcba 
    secrets:
      clientSecret: secretsecret 
      privateKey: -----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY---

	Specifies whether the connector uses basic or OAuth authentication.
	The user identifier.
	The client identifier assigned to your OAuth application.
	The key identifier assigned to the JWT verifier map of your OAuth application.
	The client secret assigned to your OAuth application.
	The RSA private key. If it has a password, you must also provide `privateKeyPassword`.

ServiceNow ITSM connectors

edit

The following example creates a ServiceNow ITSM connector with basic authentication:

xpack.actions.preconfigured:
  my-servicenow:
    name: preconfigured-servicenow-connector-type
    actionTypeId: .servicenow
    config:
      apiUrl: https://example.service-now.com/ 
      usesTableApi: false 
    secrets:
      username: testuser 
      password: passwordkeystorevalue

	The ServiceNow instance URL.
	Specifies whether the connector uses the Table API or the Import Set API. If `usesTableApi` is `false`, the Elastic application should be installed in ServiceNow.
	The user name.
	The password. NOTE: This value should be stored in the Kibana keystore.

The following example creates a ServiceNow ITSM connector with OAuth authentication:

xpack.actions.preconfigured:
  my-servicenow:
    name: preconfigured-oauth-servicenow-connector-type
    actionTypeId: .servicenow
    config:
      apiUrl: https://example.service-now.com/
      usesTableApi: false
      isOAuth: true 
      userIdentifierValue: [email protected] 
      clientId: abcdefghijklmnopqrstuvwxyzabcdef 
      jwtKeyId: fedcbazyxwvutsrqponmlkjihgfedcba 
    secrets:
      clientSecret: secretsecret 
      privateKey: -----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY---

	Specifies whether the connector uses basic or OAuth authentication.
	The user identifier.
	The client identifier assigned to your OAuth application.
	The key ID assigned to the JWT verifier map of your OAuth application.
	The client secret assigned to the OAuth application.
	The RSA private key. If it has a password, you must also provide `privateKeyPassword`.

ServiceNow SecOps connectors

edit

The following example creates a ServiceNow SecOps connector with basic authentication:

xpack.actions.preconfigured:
  my-servicenow-sir:
    name: preconfigured-servicenow-connector-type
    actionTypeId: .servicenow-sir
    config:
      apiUrl: https://example.service-now.com/ 
      usesTableApi: false 
    secrets:
      username: testuser 
      password: passwordkeystorevalue

	The ServiceNow instance URL.
	Specifies whether the connector uses the Table API or the Import Set API. If `usesTableApi` is false, the Elastic application should be installed in ServiceNow.
	The user name.
	The password. NOTE: This value should be stored in the Kibana keystore.

The following example creates a ServiceNow SecOps connector with OAuth authentication:

xpack.actions.preconfigured:
  my-servicenow:
    name: preconfigured-oauth-servicenow-connector-type
    actionTypeId: .servicenow-sir
    config:
      apiUrl: https://example.service-now.com/
      usesTableApi: false
      isOAuth: true 
      userIdentifierValue: [email protected] 
      clientId: abcdefghijklmnopqrstuvwxyzabcdef 
      jwtKeyId: fedcbazyxwvutsrqponmlkjihgfedcba 
    secrets:
      clientSecret: secretsecret 
      privateKey: -----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY---

	Specifies whether the connector uses basic or OAuth authentication.
	The user identifier.
	The client identifier assigned to the OAuth application.
	The key ID assigned to the JWT verifier map of your OAuth application.
	The client secret assigned to the OAuth application.
	The RSA private key. If it has a password, you must also specify `privateKeyPassword`.

Slack connectors

edit

The following example creates a Slack connector with webhook:

xpack.actions.preconfigured:
  my-slack:
    name: preconfigured-slack-webhook-connector-type
    actionTypeId: .slack
    secrets:
      webhookUrl: '<SLACK_WEBHOOK_URL>'

The Slack webhook URL.

The following example creates a Slack connector with web API:

xpack.actions.preconfigured:
  my-slack:
    name: preconfigured-slack-api-connector-type
    actionTypeId: .slack_api
    secrets:
      token: 'xoxb-xxxx-xxxx-xxxx'

The Slack bot user OAuth token.

Swimlane connectors

edit

The following example creates a Swimlane connector:

xpack.actions.preconfigured:
  my-swimlane:
    name: preconfigured-swimlane-connector-type
    actionTypeId: .swimlane
    config:
      apiUrl: <SWIMLANE_INSTANCE_URL> 
      appId: app-id 
      mappings: 
        alertIdConfig:
          fieldType: text
          id: agp4s
          key: alert-id
          name: Alert ID
        caseIdConfig:
          fieldType: text
          id: ae1mi
          key: case-id
          name: Case ID
        caseNameConfig:
          fieldType: text
          id: anxnr
          key: case-name
          name: Case Name
        commentsConfig:
          fieldType: comments
          id: au18d
          key: comments
          name: Comments
        descriptionConfig:
          fieldType: text
          id: ae1gd
          key: description
          name: Description
        ruleNameConfig:
          fieldType: text
          id: avfsl
          key: rule-name
          name: Rule Name
        severityConfig:
          fieldType: text
          id: a71ik
          key: severity
          name: severity
    secrets:
      apiToken: tokenkeystorevalue

	The Swimlane instance URL.
	The Swimlane application identifier.
	Field mappings for properties such as the alert identifer, severity, and rule name.
	The API authentication token for HTTP basic authentication. NOTE: This value should be stored in the Kibana keystore.

Tines connectors

edit

The following example creates a Tines connector:

xpack.actions.preconfigured:
my-tines:
    name: preconfigured-tines-connector-type
    actionTypeId: .tines
    config:
      url: <TENANT_URL> 
    secrets:
      email: [email protected] 
      token: ausergeneratedapitoken

	The Tines tenant URL.
	The email used to sign in to Tines.
	The Tines API token.

Torq connectors

edit

The following example creates a Torq connector:

xpack.actions.preconfigured:
  my-torq:
    name: preconfigured-torq-connector-type
    actionTypeId: .torq
    config:
      webhookIntegrationUrl: <WEBHOOK_URL> 
    secrets:
      token: mytorqtoken

	The endpoint URL of the Elastic Security integration in Torq.
	The secret of the webhook authentication header.

Webhook connectors

edit

The following example creates a webhook connector with basic authentication:

xpack.actions.preconfigured:
  my-webhook:
    name: preconfigured-webhook-connector-type
    actionTypeId: .webhook
    config:
      url: <WEB_SERVICE_URL> 
      method: post 
      headers: 
        testheader: testvalue
      hasAuth: true 
    secrets:
      user: testuser 
      password: passwordkeystorevalue

	The web service request URL. If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname is added to the allowed hosts.
	The HTTP request method, either `post`(default) or `put`.
	A set of key-value pairs sent as headers with the request.
	If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
	A valid user name. Required if `hasAuth` is set to `true`.
	A valid password. Required if `hasAuth` is set to `true`. NOTE: This value should be stored in the Kibana keystore.

SSL authentication is not supported in preconfigured webhook connectors.

Webhook - Case Management connectors

edit

The following example creates a Webhook - Case Management connector:

xpack.actions.preconfigured:
  my-case-management-webhook:
    name: Case Management Webhook Connector
    actionTypeId: .cases-webhook
    config:
      hasAuth: true 
      headers: 
        'content-type': 'application/json'
      createIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue' 
      createIncidentMethod: 'post' 
      createIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}' 
      getIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}' 
      getIncidentResponseExternalTitleKey: 'key' 
      viewIncidentUrl: 'https://testing-jira.atlassian.net/browse/{{{external.system.title}}}' 
      updateIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}' 
      updateIncidentMethod: 'put' 
      updateIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}' 
      createCommentMethod: 'post', 
      createCommentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment', 
      createCommentJson: '{"body": {{{case.comment}}}}', 
    secrets:
      user: testuser 
      password: passwordvalue

	If `true`, this connector will require values for `user` and `password` inside the secrets configuration.
	A set of key-value pairs sent as headers with the request.
	A REST API URL string to create a case in the third-party system.
	The REST API HTTP request method to create a case in the third-party system.
	A stringified JSON payload with Mustache variables that is sent to the create case URL to create a case.
	A REST API URL string with an external service ID Mustache variable to get the case from the third-party system.
	A string from the response body of the get case method that corresponds to the external service title.
	A URL string with either the external service ID or external service title Mustache variable to view a case in the external system.
	The REST API URL to update the case by ID in the third-party system.
	The REST API HTTP request method to update the case in the third-party system.
	A stringified JSON payload with Mustache variables that is sent to the update case URL to update a case.
	The REST API HTTP request method to create a case comment in the third-party system.
	A REST API URL string to create a case comment by ID in the third-party system.
	A stringified JSON payload with Mustache variables that is sent to the create comment URL to create a case comment.
	A user name, which is required when `hasAuth` is `true`.
	A password, which is required when `hasAuth` is `true`.

xMatters connectors

edit

The following example creates an xMatters connector with basic authentication:

xpack.actions.preconfigured:
  my-xmatters:
    name: preconfigured-xmatters-connector-type
    actionTypeId: .xmatters
    config:
      configUrl: <REQUEST_URL> 
      usesBasic: true 
    secrets:
      user: testuser 
      password: passwordkeystorevalue

	The request URL for the Elastic Alerts trigger in xMatters.
	Indicates whether the connector uses HTTP basic authentication. If `true`, you must provide `user` and `password` values. Defaults to `true`.
	A user name for authentication, which is required when `usesBasic` is `true`.
	A password for authentication, which is required when `usesBasic` is `true`. NOTE: This value should be stored in the Kibana keystore.

The following example creates an xMatters connector with URL authentication:

xpack.actions.preconfigured:
  my-xmatters:
    name: preconfigured-xmatters-connector-type
    actionTypeId: .xmatters
    config:
      usesBasic: false 
    secrets:
      secretsUrl: <SECRETS_URL>

	Indicates whether the connector uses HTTP basic authentication. Set to `false` to use URL authentication. Defaults to `true`.
	The request URL for the Elastic Alerts trigger in xMatters with the API key included in the URL.

« xMatters connector and action License Management »