Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.4] [DOCS] Add Webhook connector to case and connector docs #2221 (backport #2297) #2326

Merged
merged 1 commit into from
Aug 18, 2022
Merged

[8.4] [DOCS] Add Webhook connector to case and connector docs #2221 (backport #2297) #2326

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/cases/cases-overview.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@ Collect and share information about security issues by opening a case in {elasti

You can also send cases to these external systems by <<cases-ui-integrations, configuring external connectors>>:

* {sn} ITSM
* {sn} SecOps
* {sn-itsm}
* {sn-sir}
* {jira} (including Jira Service Desk)
* {ibm-r}
* {swimlane}
* {webhook-cm}

[role="screenshot"]
image::images/cases-home-page.png[Case UI Home]
Expand Down
143 changes: 9 additions & 134 deletions docs/cases/cases-ui-integrations.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ You can push {es-sec} cases to these third-party systems:
* {jira} (including Jira Service Desk)
* {ibm-r}
* {swimlane}
* {webhook-cm}

To push cases, you need to create a connector, which stores the information required to interact with an external system. After you have created a connector, you can set {es-sec} cases to automatically close when they are sent to external systems.

Expand All @@ -24,140 +25,14 @@ https://www.elastic.co/subscriptions[appropriate license], and your role needs *
[role="screenshot"]
image::images/cases-ui-connector.png[Shows the page for creating connectors]
. From the *Incident management system* list, select *Add new connector*.
. Select the system to send cases to: *{sn}*, *{jira}*, *{ibm-r}*, or *{swimlane}*.

+
IMPORTANT: If you've upgraded from {stack} version 7.15.0 or earlier to 7.16.0 or later, you must complete several prerequisites before creating a new {sn-itsm} or {sn-sir} connector. For more information, refer to prerequisites for {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites[{sn-itsm}] and {kibana-ref}/servicenow-sir-action-type.html#servicenow-sir-connector-prerequisites[{sn-sir}].

. Enter your required settings.
+
|===

| *Connector name* | Name for the connector.

| *URL* | ({ibm-r} and {jira} only) The URL of the external system to which you want to send cases.

| *{sn} instance URL* | ({sn} only) The URL of the {sn} instance to which you want to send cases.

| *Use OAuth authentication* | ({sn} only) Enable this to use open authorization (OAuth) to authenticate a connection between Elastic and {sn}.

To use open authorization (OAuth), you must {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites-rsa-key[create an RSA keypair and add an X.509 Certificate] and also {kibana-ref}/servicenow-action-type.html#servicenow-itsm-connector-prerequisites-endpoint[create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map.]

| *API URL* | ({swimlane} only) The URL of the {swimlane} instance to which you want to send cases.

| *Organization ID* | ({ibm-r} only) Your organization’s {ibm-r} ID number.

| *Application ID* | ({swimlane} only) The application ID of your {swimlane} application. From {swimlane}, you can find the application
ID by checking your application’s settings or at the end of your application’s URL after you’ve opened it.

| *Username* | ({sn} only and displays if *Use OAuth authentication* is turned off) The username of the {sn} account used to access the {sn} instance.

| *Password* | ({sn} only and displays if *Use OAuth authentication* is turned off) The password of the {sn} account used to access the {sn} instance.

| *Client ID* | ({sn} only and displays if *Use OAuth authentication* is turned on) The client ID assigned to your OAuth application.

| *User Identifier* | ({sn} only and displays if *Use OAuth authentication* is turned on) Identifier to use for OAuth type authentication. Use the value you entered into the *User field* when you created an OAuth JWT API endpoint for external clients.

| *JWT Verifier Key ID* | ({sn} only and displays if *Use OAuth authentication* is turned on) The key ID assigned to the JWT Verifier Map of your OAuth application.

| *Client Secret* | ({sn} only and displays if *Use OAuth authentication* is turned on) The client secret assigned to your OAuth application.

| *Private Key* | ({sn} only and displays if *Use OAuth authentication* is turned on) The RSA private key generated when you created an RSA keypair.

| *Private Key Password* | ({sn} only and displays only if *Use OAuth authentication* is turned on) The The password for the RSA private key generated during setup, if set.

| *Project key* | ({jira} only) The key of the {jira} project to which you are sending cases.

| *Email address* | ({jira} only) The {jira} account username or email.

| *API token* | ({jira} only) The API token or password is used to authenticate {jira} updates.

| *API key ID* | ({ibm-r} only) The API key is used to authenticate {ibm-r} updates.

| *API key secret* | ({ibm-r} only) The API key secret is used to authenticate {ibm-r} updates.

| *API token* | ({swimlane} only) The {swimlane} API authentication token is used for HTTP Basic authentication.
This is the personal access token for your user role.

|===
+
. Choose the connector type ({swimlane} only):
+
|===

| *All* | You can choose to set all or no field mappings when creating your new {swimlane} connector. However, note that if
you don’t set field mappings now, you’ll be prompted to do so if you want to use the connector for a case or a rule.

| *Alerts* | Provide an alert ID and rule name.

| *Cases* | Provide a case ID, a case name, comments, and a description.

|===
+
. Save the connector.

TIP: To learn how to connect {elastic-sec} to {jira}, check out the <<connect-security-to-jira, tutorial>> at the end of this topic.

[float]
[[mapped-case-fields]]
=== Mapped case fields

To represent an {es-sec} case in an external system, {es-sec} case fields are
mapped as follows:

NOTE: Data from mapped case fields can be pushed to external systems but cannot be pulled in.

* For {sn} incidents:
+
|===

| *Title* | Mapped to the {sn} `Short description` field. When an update to a case title is sent to {sn}, the existing {sn} `Short description` field is overwritten.

| *Description* | Mapped to the {sn} `Description` field. When an update to a case description is sent to {sn}, the existing {sn} `Description` field is overwritten.

| *Comments* | Mapped to the {sn} `Work Notes` field. When a comment is updated in a case, a new comment is added to the {sn} incident.

|===
+

* For {jira} issues:
+
|===

| *Title* | Mapped to the {jira} `Summary` field. When an update to a case title is sent to {jira}, the existing {jira} `Summary` field is overwritten.

| *Description* | Mapped to the {jira} `Description` field. When an update to a case description is sent to {jira}, the existing {jira} `Description` field is overwritten.

| *Comments* | Mapped to the {jira} `Comments` field. When a comment is updated in a case, a new comment is added to the {jira} incident.

|===
+

* For {ibm-r} issues:
+
|===

| *Title* | Mapped to the {ibm-r} `Name` field. When an update to a case title is sent to {ibm-r}, the existing {ibm-r} `Name` field is overwritten.

| *Description* | Mapped to the {ibm-r} `Description` field. When an update to a case description is sent to {ibm-r}, the existing {ibm-r} `Description` field is overwritten.

| *Comments* | Mapped to the {ibm-r} `Comments` field. When a comment is updated in a case, a new comment is added to the {ibm-r} incident.

|===
+

* For {swimlane} records:
+
|===

| *Title* | Mapped to the {swimlane} `caseName` field. When an update to a case title is sent to {swimlane}, the field that is mapped to the {swimlane} `caseName` field is
overwritten.

| *Description* | Mapped to the {swimlane} `Description` field. When an update to a case description is sent to {swimlane}, the field that is mapped to the {swimlane} `Description` field is overwritten.

| *Comments* | Mapped to the {swimlane} `Comments` field. When a new comment is added to a case, or an existing one is updated, the field that is mapped to the {swimlane} `Comment` field is appended. Comments are posted to the {swimlane} incident record individually.

|===
. Select the system to send cases to: *{sn}*, *{jira}*, *{ibm-r}*, *{swimlane}*, or *{webhook-cm}*.
. Enter your required settings. For connector configuration details, refer to:
- {kibana-ref}/servicenow-action-type.html[{sn-itsm} connector]
- {kibana-ref}/servicenow-sir-action-type.html[{sn-sir} connector]
- {kibana-ref}/jira-action-type.html[{jira} connector]
- {kibana-ref}/resilient-action-type.html[{ibm-r} connector]
- {kibana-ref}/swimlane-action-type.html[{swimlane} connector]
- {kibana-ref}/cases-webhook-action-type.html[{webhook-cm} connector]

[[close-connector]]
[float]
Expand Down