Elastic Docs ›Kibana Guide [8.13] ›Stack Management ›Connectors
« xMatters connector and action License Management »

Preconfigured connectorsedit

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 connectorsedit

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: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz'
    webhook-service:
      actionTypeId: .webhook
      name: 'Email service'
      config:                   
        url: 'https://email-alert-service.elastic.co'
        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 connectorsedit

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 connectorsedit

Kibana provides the following built-in preconfigured connectors:

Preconfigured alert history Elasticsearch index connectoredit

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.

Examplesedit

Amazon Bedrock connectorsedit

The following example creates an Amazon Bedrock connector:

xpack.actions.preconfigured:
  my-bedrock:
    name: preconfigured-bedrock-connector-type
    actionTypeId: .bedrock
    config:
      apiUrl: https://bedrock-runtime.us-east-1.amazonaws.com 
      defaultModel: anthropic.claude-v2:1 
    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 connectorsedit

The following example creates a D3 Security connector:

xpack.actions.preconfigured:
  my-d3security:
    name: preconfigured-d3security-connector-type
    actionTypeId: .d3security
    config:
      url: https://testurl.com/elasticsearch/VSOC/api/Data/Kibana/Security%20Operations/CreateEvents 
    secrets:
      token: superlongtoken

The D3 Security API request URL.

The D3 Security token.
Email connectorsedit

The following example creates an email connector:

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 
      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
Gmailedit

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 authenticationedit

[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.0edit

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.comedit

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 connectorsedit

The following example creates a OpenAI connector:

xpack.actions.preconfigured:
  my-open-ai:
    name: preconfigured-openai-connector-type
    actionTypeId: .gen-ai
    config:
      apiUrl: https://api.openai.com/v1/chat/completions 
      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 connectorsedit

The following example creates a IBM Resilient connector:

xpack.actions.preconfigured:
 my-resilient:
    name: preconfigured-resilient-connector-type
    actionTypeId: .resilient
    config:
      apiUrl: https://elastic.resilient.net 
      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 connectorsedit

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 connectorsedit

The following example creates a Jira connector:

xpack.actions.preconfigured:
  my-jira:
    name: preconfigured-jira-connector-type
    actionTypeId: .jira
    config:
      apiUrl: https://elastic.atlassian.net 
      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 connectorsedit

The following example creates a Microsoft Teams connector:

xpack.actions.preconfigured:
  my-teams:
    name: preconfigured-teams-connector-type
    actionTypeId: .teams
    secrets:
      webhookUrl: 'https://outlook.office.com/webhook/abcd@0123456/IncomingWebhook/abcdefgh/ijklmnopqrstuvwxyz'

The URL of the incoming webhook.
Opsgenie connectorsedit

The following example creates an Opsgenie connector:

xpack.actions.preconfigured:
  my-opsgenie:
    name: preconfigured-opsgenie-connector-type
    actionTypeId: .opsgenie
    config:
      apiUrl: https://api.opsgenie.com 
    secrets:
      apiKey: apikey

The Opsgenie URL.

The Opsgenie API authentication key for HTTP basic authentication.
PagerDuty connectorsedit

The following example creates a PagerDuty connector:

xpack.actions.preconfigured:
  my-pagerduty:
    name: preconfigured-pagerduty-connector-type
    actionTypeId: .pagerduty
    config:
      apiUrl: https://test.host 
    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 connectorsedit

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 connectorsedit

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: testuser@email.com 
      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 connectorsedit

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: testuser@email.com 
      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 connectorsedit

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: testuser@email.com 
      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 connectorsedit

The following example creates a Slack connector with webhook:

xpack.actions.preconfigured:
  my-slack:
    name: preconfigured-slack-webhook-connector-type
    actionTypeId: .slack
    secrets:
      webhookUrl: 'https://hooks.slack.com/services/xxxx/xxxx/xxxx'

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 connectorsedit

The following example creates a Swimlane connector:

xpack.actions.preconfigured:
  my-swimlane:
    name: preconfigured-swimlane-connector-type
    actionTypeId: .swimlane
    config:
      apiUrl: https://elastic.swimlaneurl.us 
      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 connectorsedit

The following example creates a Tines connector:

xpack.actions.preconfigured:
my-tines:
    name: preconfigured-tines-connector-type
    actionTypeId: .tines
    config:
      url: https://some-tenant-2345.tines.com 
    secrets:
      email: some.address@test.com 
      token: ausergeneratedapitoken

The Tines tenant URL.

The email used to sign in to Tines.

The Tines API token.
Torq connectorsedit

The following example creates a Torq connector:

xpack.actions.preconfigured:
  my-torq:
    name: preconfigured-torq-connector-type
    actionTypeId: .torq
    config:
      webhookIntegrationUrl: https://hooks.torq.io/v1/somehook 
    secrets:
      token: mytorqtoken

The endpoint URL of the Elastic Security integration in Torq.

The secret of the webhook authentication header.
Webhook connectorsedit

The following example creates a webhook connector with basic authentication:

xpack.actions.preconfigured:
  my-webhook:
    name: preconfigured-webhook-connector-type
    actionTypeId: .webhook
    config:
      url: https://test.host 
      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 connectorsedit

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://example.com/rest/api/2/issue' 
      createIncidentMethod: 'post' 
      createIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}' 
      getIncidentUrl: 'https://example.com/rest/api/2/issue/{{{external.system.id}}}' 
      getIncidentResponseExternalTitleKey: 'key' 
      viewIncidentUrl: 'https://example.com/browse/{{{external.system.title}}}' 
      updateIncidentUrl: 'https://example.com/rest/api/2/issue/{{{external.system.id}}}' 
      updateIncidentMethod: 'put' 
      updateIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}' 
      createCommentMethod: 'post', 
      createCommentUrl: 'https://example.com/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 connectorsedit

The following example creates an xMatters connector with basic authentication:

xpack.actions.preconfigured:
  my-xmatters:
    name: preconfigured-xmatters-connector-type
    actionTypeId: .xmatters
    config:
      configUrl: https://test.host 
      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: https://test.host?apiKey=1234-abcd

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 »