From 0fc24f4181b70c88bc7cacbe0d295b6dd5255438 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 3 Oct 2023 09:14:26 -0700 Subject: [PATCH] [DOCS] Move preconfigured ServiceNow connector details (#166202) --- .../action-types/servicenow-itom.asciidoc | 60 +------ .../action-types/servicenow-sir.asciidoc | 66 +------- .../action-types/servicenow.asciidoc | 66 +------- .../pre-configured-connectors.asciidoc | 155 +++++++++++++++++- docs/settings/alert-action-settings.asciidoc | 33 +++- 5 files changed, 197 insertions(+), 183 deletions(-) diff --git a/docs/management/connectors/action-types/servicenow-itom.asciidoc b/docs/management/connectors/action-types/servicenow-itom.asciidoc index 1549949cd23b9..3f104006cd1e7 100644 --- a/docs/management/connectors/action-types/servicenow-itom.asciidoc +++ b/docs/management/connectors/action-types/servicenow-itom.asciidoc @@ -3,6 +3,10 @@ ++++ {sn-itom} ++++ +:frontmatter-description: Add a connector that can create {sn} events. +:frontmatter-tags-products: [kibana] +:frontmatter-tags-content-type: [how-to] +:frontmatter-tags-user-goals: [configure] The {sn-itom} connector uses the https://docs.servicenow.com/bundle/rome-it-operations-management/page/product/event-management/task/send-events-via-web-service.html[event API] @@ -79,62 +83,6 @@ JWT Key ID:: The key ID assigned to the JWT verifier map of your OAuth applicati Private Key:: The RSA private key generated during setup. Private Key Password:: The password for the RSA private key generated during setup, if set. -[float] -[[preconfigured-servicenow-itom-configuration]] -=== Create preconfigured connectors - -If you are running {kib} on-prem, you can define connectors by -adding `xpack.actions.preconfigured` settings to your `kibana.yml` file. -For example: - -Connector using Basic Authentication -[source,text] --- -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 --- - -Connector using OAuth -[source,text] --- - my-servicenow: - name: preconfigured-oauth-servicenow-connector-type - actionTypeId: .servicenow-itom - 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----- --- - -Config defines information for the connector type. - -`apiUrl`:: An address that corresponds to *URL*. -`isOAuth`:: A boolean that corresponds to *Is OAuth* and indicates if the connector uses Basic Authentication or OAuth. -`userIdentifierValue`:: A string that corresponds to *User Identifier*. Required if `isOAuth` is set to `true`. -`clientId`:: A string that corresponds to *Client ID*, used for OAuth authentication. Required if `isOAuth` is set to `true`. -`jwtKeyId`:: A string that corresponds to *JWT Key ID*, used for OAuth authentication. Required if `isOAuth` is set to `true`. - -Secrets defines sensitive information for the connector type. - -`username`:: A string that corresponds to *Username*. Required if `isOAuth` is set to `false`. -`password`:: A string that corresponds to *Password*. Should be stored in the <>. Required if `isOAuth` is set to `false`. -`clientSecret`:: A string that corresponds to *Client Secret*. Required if `isOAuth` is set to `true`. -`privateKey`:: A string that corresponds to *Private Key*. Required if `isOAuth` is set to `true`. -`privateKeyPassword`:: A string that corresponds to *Private Key Password*. - [float] [[servicenow-itom-action-configuration]] === Test connectors diff --git a/docs/management/connectors/action-types/servicenow-sir.asciidoc b/docs/management/connectors/action-types/servicenow-sir.asciidoc index 0fc96f9baa85c..30ea222aa4e14 100644 --- a/docs/management/connectors/action-types/servicenow-sir.asciidoc +++ b/docs/management/connectors/action-types/servicenow-sir.asciidoc @@ -3,6 +3,10 @@ ++++ {sn-sir} ++++ +:frontmatter-description: Add a connector that can create {sn} security incidents. +:frontmatter-tags-products: [kibana] +:frontmatter-tags-content-type: [how-to] +:frontmatter-tags-user-goals: [configure] The {sn-sir} connector uses the https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest/c_ImportSetAPI[import set API] @@ -122,68 +126,6 @@ JWT Key ID:: The key ID assigned to the JWT verifier map of your OAuth applicati Private Key:: The RSA private key generated during setup. Private Key Password:: The password for the RSA private key generated during setup, if set. -[float] -[[preconfigured-servicenow-sir-configuration]] -=== Create preconfigured connectors - -If you are running {kib} on-prem, you can define connectors by -adding `xpack.actions.preconfigured` settings to your `kibana.yml` file. -For example: - -Connector using Basic Authentication -[source,text] --- -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 --- - -Connector using OAuth -[source,text] --- -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----- --- - -Config defines information for the connector type. - -`apiUrl`:: An address that corresponds to *URL*. -`usesTableApi`:: A boolean that indicates if the connector uses the Table API or the Import Set API. - -NOTE: If `usesTableApi` is set to false, the Elastic application should be installed in {sn}. - -`isOAuth`:: A boolean that corresponds to *Is OAuth* and indicates if the connector uses Basic Authentication or OAuth. -`userIdentifierValue`:: A string that corresponds to *User Identifier*. Required if `isOAuth` is set to `true`. -`clientId`:: A string that corresponds to *Client ID*, used for OAuth authentication. Required if `isOAuth` is set to `true`. -`jwtKeyId`:: A string that corresponds to *JWT Key ID*, used for OAuth authentication. Required if `isOAuth` is set to `true`. - -Secrets defines sensitive information for the connector type. - -`username`:: A string that corresponds to *Username*. Required if `isOAuth` is set to `false`. -`password`:: A string that corresponds to *Password*. Should be stored in the <>. Required if `isOAuth` is set to `false`. -`clientSecret`:: A string that corresponds to *Client Secret*. Required if `isOAuth` is set to `true`. -`privateKey`:: A string that corresponds to *Private Key*. Required if `isOAuth` is set to `true`. -`privateKeyPassword`:: A string that corresponds to *Private Key Password*. - [float] [[servicenow-sir-action-configuration]] === Test connectors diff --git a/docs/management/connectors/action-types/servicenow.asciidoc b/docs/management/connectors/action-types/servicenow.asciidoc index 2151100451232..f3c636df29b6b 100644 --- a/docs/management/connectors/action-types/servicenow.asciidoc +++ b/docs/management/connectors/action-types/servicenow.asciidoc @@ -3,6 +3,10 @@ ++++ {sn-itsm} ++++ +:frontmatter-description: Add a connector that can create {sn} incidents. +:frontmatter-tags-products: [kibana] +:frontmatter-tags-content-type: [how-to] +:frontmatter-tags-user-goals: [configure] The {sn-itsm} connector uses the https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest/c_ImportSetAPI[import set API] @@ -206,68 +210,6 @@ JWT Key ID:: The key ID assigned to the JWT Verifier Map of your OAuth applicati Private Key:: The RSA private key generated during setup. Private Key Password:: The password for the RSA private key generated during setup, if set. -[float] -[[preconfigured-servicenow-configuration]] -=== Create preconfigured connectors - -If you are running {kib} on-prem, you can define connectors by -adding `xpack.actions.preconfigured` settings to your `kibana.yml` file. -For example: - -Connector using Basic Authentication -[source,text] --- -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 --- - -Connector using OAuth -[source,text] --- -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----- --- - -Config defines information for the connector type. - -`apiUrl`:: An address that corresponds to *URL*. -`usesTableApi`:: A boolean that indicates if the connector uses the Table API or the Import Set API. - -NOTE: If `usesTableApi` is set to false, the Elastic application should be installed in {sn}. - -`isOAuth`:: A boolean that corresponds to *Is OAuth* and indicates if the connector uses Basic Authentication or OAuth. -`userIdentifierValue`:: A string that corresponds to *User Identifier*. Required if `isOAuth` is set to `true`. -`clientId`:: A string that corresponds to *Client ID*, used for OAuth authentication. Required if `isOAuth` is set to `true`. -`jwtKeyId`:: A string that corresponds to *JWT Key ID*, used for OAuth authentication. Required if `isOAuth` is set to `true`. - -Secrets defines sensitive information for the connector type. - -`username`:: A string that corresponds to *Username*. Required if `isOAuth` is set to `false`. -`password`:: A string that corresponds to *Password*. Should be stored in the <>. Required if `isOAuth` is set to `false`. -`clientSecret`:: A string that corresponds to *Client Secret*. Required if `isOAuth` is set to `true`. -`privateKey`:: A string that corresponds to *Private Key*. Required if `isOAuth` is set to `true`. -`privateKeyPassword`:: A string that corresponds to *Private Key Password*. - [float] [[servicenow-action-configuration]] === Test connectors diff --git a/docs/management/connectors/pre-configured-connectors.asciidoc b/docs/management/connectors/pre-configured-connectors.asciidoc index 79b4e331fa19a..6e6694e8a839d 100644 --- a/docs/management/connectors/pre-configured-connectors.asciidoc +++ b/docs/management/connectors/pre-configured-connectors.asciidoc @@ -117,6 +117,9 @@ Index names must start with `kibana-alert-history-` to take advantage of the pre * <> * <> * <> +* <> +* <> +* <> * <> * <> * <> @@ -442,6 +445,155 @@ xpack.actions.preconfigured: actionTypeId: .server-log -- +[float] +[[preconfigured-servicenow-itom-configuration]] +==== {sn-itom} connectors + +The following example creates a <> with basic authentication: + +[source,text] +-- +xpack.actions.preconfigured: + my-servicenow-itom: + name: preconfigured-servicenow-connector-type + actionTypeId: .servicenow-itom + config: + apiUrl: https://example.service-now.com/ <1> + secrets: + username: testuser <2> + password: passwordkeystorevalue <3> +-- +<1> The ServiceNow instance URL. +<2> A user name. +<3> A password. NOTE: This value should be stored in the <>. + +The following example creates a {sn-itom} connector with OAuth authentication: + +[source,text] +-- +xpack.actions.preconfigured: + my-servicenow: + name: preconfigured-oauth-servicenow-connector-type + actionTypeId: .servicenow-itom + config: + apiUrl: https://example.service-now.com/ + isOAuth: true <1> + userIdentifierValue: testuser@email.com <2> + clientId: abcdefghijklmnopqrstuvwxyzabcdef <3> + jwtKeyId: fedcbazyxwvutsrqponmlkjihgfedcba <4> + secrets: + clientSecret: secretsecret <5> + privateKey: -----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY----- <6> +-- +<1> Specifies whether the connector uses basic or OAuth authentication. +<2> The user identifier. +<3> The client identifier assigned to your OAuth application. +<4> The key identifier assigned to the JWT verifier map of your OAuth application. +<5> The client secret assigned to your OAuth application. +<6> The RSA private key. If it has a password, you must also provide `privateKeyPassword`. + +[float] +[[preconfigured-servicenow-configuration]] +==== {sn-itsm} connectors + +The following example creates a <> with basic authentication: + +[source,text] +-- +xpack.actions.preconfigured: + my-servicenow: + name: preconfigured-servicenow-connector-type + actionTypeId: .servicenow + config: + apiUrl: https://example.service-now.com/ <1> + usesTableApi: false <2> + secrets: + username: testuser <3> + password: passwordkeystorevalue <4> +-- +<1> The ServiceNow instance URL. +<2> Specifies whether the connector uses the Table API or the Import Set API. If `usesTableApi` is `false`, the Elastic application should be installed in {sn}. +<3> The user name. +<4> The password. NOTE: This value should be stored in the <>. + +The following example creates a {sn-itsm} connector with OAuth authentication: + +[source,text] +-- +xpack.actions.preconfigured: + my-servicenow: + name: preconfigured-oauth-servicenow-connector-type + actionTypeId: .servicenow + config: + apiUrl: https://example.service-now.com/ + usesTableApi: false + isOAuth: true <1> + userIdentifierValue: testuser@email.com <2> + clientId: abcdefghijklmnopqrstuvwxyzabcdef <3> + jwtKeyId: fedcbazyxwvutsrqponmlkjihgfedcba <4> + secrets: + clientSecret: secretsecret <5> + privateKey: -----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY----- <6> +-- +<1> Specifies whether the connector uses basic or OAuth authentication. +<2> The user identifier. +<3> The client identifier assigned to your OAuth application. +<4> The key ID assigned to the JWT verifier map of your OAuth application. +<5> The client secret assigned to the OAuth application. +<6> The RSA private key. If it has a password, you must also provide `privateKeyPassword`. + +[float] +[[preconfigured-servicenow-sir-configuration]] +==== {sn-sir} connectors + +The following example creates a <> with basic authentication: + +[source,text] +-- +xpack.actions.preconfigured: + my-servicenow-sir: + name: preconfigured-servicenow-connector-type + actionTypeId: .servicenow-sir + config: + apiUrl: https://example.service-now.com/ <1> + usesTableApi: false <2> + secrets: + username: testuser <3> + password: passwordkeystorevalue <4> +-- +<1> The ServiceNow instance URL. +<2> Specifies whether the connector uses the Table API or the Import Set API. If `usesTableApi` is false, the Elastic application should be installed in {sn}. +<3> The user name. +<4> The password. NOTE: This value should be stored in the <>. + +The following example creates a {sn-sir} connector with OAuth authentication: + +[source,text] +-- +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 <1> + userIdentifierValue: testuser@email.com <2> + clientId: abcdefghijklmnopqrstuvwxyzabcdef <3> + jwtKeyId: fedcbazyxwvutsrqponmlkjihgfedcba <4> + secrets: + clientSecret: secretsecret <5> + privateKey: -----BEGIN RSA PRIVATE KEY-----\nprivatekeyhere\n-----END RSA PRIVATE KEY----- <6> +-- +<1> Specifies whether the connector uses basic or OAuth authentication. +<2> The user identifier. +<3> The client identifier assigned to the OAuth application. +<4> The key ID assigned to the JWT verifier map of your OAuth application. +<5> The client secret assigned to the OAuth application. +<6> The RSA private key. If it has a password, you must also specify +`privateKeyPassword`. + + [float] [[preconfigured-slack-configuration]] ==== Slack connectors @@ -605,7 +757,6 @@ xpack.actions.preconfigured: NOTE: SSL authentication is not supported in preconfigured webhook connectors. - [float] [[preconfigured-cases-webhook-configuration]] ==== {webhook-cm} connectors @@ -664,7 +815,7 @@ The following example creates an <> wit [source,text] -- xpack.actions.preconfigured: -my-xmatters: + my-xmatters: name: preconfigured-xmatters-connector-type actionTypeId: .xmatters config: diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc index 76b1ebadc98d1..4312d2825a9d4 100644 --- a/docs/settings/alert-action-settings.asciidoc +++ b/docs/settings/alert-action-settings.asciidoc @@ -272,6 +272,7 @@ A configuration URL that varies by connector: * For a <>, specifies the Jira instance URL. * For an <>, specifies the {opsgenie} URL. For example, `https://api.opsgenie.com` or `https://api.eu.opsgenie.com`. * For a <>, specifies the PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. +* For a <>, <>, or <> specifies the ServiceNow instance URL. * For a <>, specifies the {swimlane} instance URL. NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname in the URL is added to the allowed hosts. @@ -285,7 +286,12 @@ An application ID that varies by connector: -- `xpack.actions.preconfigured..config.clientId`:: -For an <>, specifies a GUID format value that corresponds to the client ID, which is a part of OAuth 2.0 client credentials authentication. +A client identifier that varies by connector: ++ +-- +* For an <>, specifies a GUID format value that corresponds to the client ID, which is a part of OAuth 2.0 client credentials authentication. +* For a <>, <>, or <> specifies the client identifier assigned to the OAuth application. +-- `xpack.actions.preconfigured..config.configUrl`:: For an <> with basic authentication, specifies the request URL for the Elastic Alerts trigger in xMatters. @@ -350,6 +356,12 @@ For an <>, specifies the host name of the ser `xpack.actions.preconfigured..config.index`:: For an <>, specifies the {es} index. +`xpack.actions.preconfigured..config.isOAuth`:: +For a <>, <>, or <>, specifies whether to use basic or OAuth authentication. + +`xpack.actions.preconfigured..config.jwtKeyId`:: +For a <>, <>, or <>, specifies the key ID assigned to the JWT verifier map of your OAuth application. It is required when `xpack.actions.preconfigured..config.isOAuth` is `true`. + `xpack.actions.preconfigured..config.mappings`:: For a <>, specifies field mappings. @@ -427,9 +439,16 @@ A configuration URL that varies by connector: NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure this hostname is added to the allowed hosts. -- +`xpack.actions.preconfigured..config.userIdentifierValue`:: +For a <>, <>, or <>, specifies the user identifier. It is required when required when `xpack.actions.preconfigured..config.isOAuth` is `true`. + `xpack.actions.preconfigured..config.usesBasic`:: For an <>, specifies whether it uses HTTP basic authentication. Defaults to `true`. +`xpack.actions.preconfigured..config.usesTableApi`:: +For a <> or <>, specifies whether the connector uses the Table API or the Import Set API. +If set to `false`, the Elastic application should be installed in ServiceNow. + `xpack.actions.preconfigured..config.viewIncidentUrl`:: For a <>, specifies a URL string with either the external service ID or external service title Mustache variable to view a case in the external system. @@ -466,6 +485,7 @@ A client secret that varies by connector: + -- * For an <>, specifies the client secret that you generated for your app in the app registration portal. It is required when the email service is `exchange_server`, which uses OAuth 2.0 client credentials authentication. +* For a <>, <>, or <>, specifies the client secret assigned to the OAuth application. It is required when `xpack.actions.preconfigured..config.isOAuth` is `true`. NOTE: The client secret must be URL-encoded. -- @@ -482,10 +502,18 @@ An email address that varies by connector: A password secret that varies by connector: + -- + * For an <>, <>, or <>, specifies a password that is required when `xpack.actions.preconfigured..config.hasAuth` is `true`. +* For a <>, <>, or <>, specifies a password that is required when `xpack.actions.preconfigured..config.isOAuth` is `false`. * For an <>, specifies a password that is required when `xpack.actions.preconfigured..config.usesBasic` is `true`. -- +`xpack.actions.preconfigured..secrets.privateKey`:: +For a <>, <>, or <>, specifies the RSA private key. It is required when `xpack.actions.preconfigured..config.isOAuth` is `true`. + +`xpack.actions.preconfigured..secrets.privateKeyPassword`:: +For a <>, <>, or <>, specifies the password for the RSA private key. + `xpack.actions.preconfigured..secrets.routingKey`:: For a <>, specifies the 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key. @@ -523,6 +551,9 @@ For a <>, specifies the Slack webhook URL. NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname is added to the allowed hosts. -- +`xpack.actions.preconfigured..secrets.username`:: +For a <>, <>, or <>, specifies a user name that is required when `xpack.actions.preconfigured..config.isOAuth` is `false`. + [float] [[alert-settings]] === Alerting settings