[DOCS] OAuth authentication added to SN connectors

docs/cases/cases-ui-integrations.asciidoc

@@ -4,121 +4,172 @@
 
 You can push {es-sec} cases to these third-party systems:
 
-* {sn} ITSM
-* {sn} SecOps
+* {sn-itsm}
+* {sn-sir}
 * {jira} (including Jira Service Desk)
 * {ibm-r}
 * {swimlane}
 
-To push cases, you need to create a connector, which stores the information
-required to interact with an external system.
+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.
 
-After you have created a connector, you can set {es-sec} cases to
-automatically close when they are sent to external systems.
+IMPORTANT: To create connectors and send cases to external systems, you need the
+https://www.elastic.co/subscriptions[appropriate license], and your role needs *All* privileges for the *Action and Connectors* feature. For more information, refer to <<case-permissions>>.
 
-NOTE: To create connectors and send cases to external systems, you need the
-https://www.elastic.co/subscriptions[appropriate license] and your role needs *All* privileges for the *Action and Connectors* feature. For more information, refer to <<case-permissions>>.
-
-[[create-new-connector]]
 [float]
+[[create-new-connector]]
 === Create a new connector
 
 . Go to *Investigate* -> *Cases* -> *Edit external connection*.
 +
 [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 one of these:
-* *{sn}*: To send cases to {sn}
+. 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):
 +
-IMPORTANT: If you've upgraded from {stack} version 7.15.0 or earlier to version 7.16.0 or later, you must install https://store.servicenow.com/sn_appstore_store.do#!/store/application/7148dbc91bf1f450ced060a7234bcb88[Elastic for ITSM] or https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f[Elastic for Security Operations (SecOps)] on your {sn} instance and complete additional configuration steps before creating a new {sn} ITSM or SecOps connector. If you don't, an error message displays and you cannot create the new connector. For more information, refer to {kibana-ref}/servicenow-sir-action-type.html[{sn} SecOps] and {kibana-ref}/servicenow-action-type.html[{sn} ITSM].
-
-* *{jira}*: To send cases to {jira} or {jira} Service Desk
-* *{ibm-r}*: To send cases to {ibm-r}
-* *{swimlane}*: To send cases to {swimlane}
-
-. Fill in the following:
-* *Connector name*: A name for the connector.
-* *URL*: The URL of the external system to which you want to send cases.
-* *{sn} instance URL* (for {sn} connectors only): The URL of the {sn} to which you want to send cases.
-* *API Url* ({swimlane} connectors only): The URL of the {swimlane} instance to which you want to send cases.
-* *Organization ID* ({ibm-r} connectors only): Your organization's {ibm-r} ID
-number.
-* *Application ID* ({swimlane} connectors 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} connectors only): The username of the {sn} account used to
-access the {sn} instance.
-* *Password* ({sn} connectors only): The password of the {sn} account used to access the {sn} instance.
-* *Project key* ({jira} connectors only): The key of the {jira} project to which
-you are sending cases.
-* *Email address* ({jira} connectors only): The {jira} account's username or email address.
-* *API token* ({jira} connectors only): The API token or password used
-to authenticate {jira} updates.
-* *API key ID* ({ibm-r} connectors only): The API key used to authenticate
-{ibm-r} updates.
-* *API key secret* ({ibm-r} connectors only): The API key secret used to
-authenticate {ibm-r} updates.
-* *API token* ({swimlane} connectors only): The {swimlane} API authentication token used for HTTP Basic authentication. This is the personal access token for your user role.
-
-. Choose the connector type (for {swimlane} connectors 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. The prompts no longer display once you set up the required mappings.
-** *Alerts*: Provide an alert ID and rule name.
-** *Cases*: Provide a case ID, a case name, comments, and a description.
+|===
+
+| *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
-Security 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
-Security 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 Security case, a new comment is added to the {sn} incident.
++
+|===
+
+| *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
-Security 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
-Security 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 Security case, a new comment is added to the {jira} incident.
++
+|===
+
+| *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
-Security 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
-Security 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 Security case, a new comment is added to the {ibm-r} incident.
++
+|===
+
+| *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
-Security case title is sent to {swimlane}, the field that is mapped to the {swimlane} `caseName` field is
++
+|===
+
+| *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
-Security 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 Security 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.
+
+| *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.
+
+|===
 
 [[close-connector]]
 [float]
+[[close-sent-cases]]
 === Close sent cases automatically
 
 To close cases when they are sent to an external system, select
 *Automatically close Security cases when pushing new incident to external system*.
 
 [[default-connector]]
 [float]
+[[change-default-connector]]
 === Change the default connector
 
 To change the default connector used to send cases to external systems, go to *Cases* -> *Edit external connection* and select the required connector from the Incident management system list.
@@ -138,6 +189,7 @@ image::images/add-connectors.png[width=60%][height=60%][Shows how to add connect
 
 [[modify-connector]]
 [float]
+[[modify-connector-settings]]
 === Modify connector settings
 
 To change the settings of an existing connector: