[ResponseOps][Docs] Updating ServiceNow docs with OAuth setup instructions

docs/management/connectors/action-types/servicenow-itom.asciidoc

@@ -10,10 +10,114 @@ The {sn} ITOM connector uses the https://docs.servicenow.com/bundle/rome-it-oper
 [float]
 [[servicenow-itom-connector-prerequisites]]
 ==== Prerequisites
-Create an integration user in {sn} and assign it the following roles.
+* Create a {sn} integration user and assign it the appropriate roles.
 
+*If using OAuth*
+
+* Create an RSA keypair and add an X.509 Certificate.
+* Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map.
+
+[float]
+===== Create a {sn} integration user
+
+To ensure authenticated communication between Elastic and {sn}, create a {sn} integration user and assign it the appropriate roles.
+
+. In your {sn} instance, go to *System Security -> Users and Groups -> Users*.
+. Click *New*.
+. Complete the form, then right-click on the menu bar and click *Save*.
+. Go to the *Roles* tab and click *Edit*.
+. Assign the integration user the following roles: 
 * `personalize_choices`: Allows the user to retrieve Choice element options, such as Severity.
 * `evt_mgmt_integration`: Enables integration with external event sources by allowing the user to create events.
+. Click *Save*.
+
+[float]
+===== Create an RSA keypair and add an X.509 Certificate
+
+This step is required to use OAuth for authentication between Elastic and {sn}.
+
+*Create an RSA keypair:*
+
+. Use https://www.openssl.org/docs/man1.0.2/man1/genrsa.html[OpenSSL] to generate an RSA private key:
++
+--
+[source,sh]
+----
+openssl genrsa -out example-private-key.pem 3072
+openssl genrsa -passout pass:foobar -out example-private-key-with-password.pem 3072 <1>
+----
+<1> Use the `passout` option to set a password on your private key. This is optional but remember your password if you set one.
+--
+
+. Use https://www.openssl.org/docs/man1.0.2/man1/req.html[OpenSSL] to generate the matching public key:
++
+--
+[source,sh]
+----
+openssl req -new -x509 -key example-private-key.pem -out example-sn-cert.pem -days 360
+----
+--
+
+*Add an X.509 Certificate to ServiceNow:*
+
+. In your {sn} instance, go to *Certificates* and select *New*.
+. Configure the certificate as follows:
++
+--
+* *Name*: Name the certificate.
+* *PEM Certificate*: Copy the generated public key into this text field.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-new-certificate.png[Shows new certificate form in ServiceNow]
+--
+
+. Click *Submit* to create the certificate.
+
+[float]
+===== Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map
+
+This step is required to use OAuth for authentication between Elastic and {sn}.
+
+. In your {sn} instance, go to *Application Registry* and select *New*.
+. Select *Create an OAuth JWT API endpoint for external clients* from the list of options.
++
+--
+[role="screenshot"]
+image::management/connectors/images/servicenow-jwt-endpoint.png[Shows application type selection]
+--
+
+. Configure the application as follows:
++
+--
+* *Name*: Name the application.
+* *User field*: Select the field to use as the user identifier.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-new-application.png[Shows new application form in ServiceNow]
+
+IMPORTANT: Remember the selected user field. You will use this as the *User Identifier Value* when creating the connector. For example, if you selected *Email* for *User field*, you will use the user's email for the *User Identifier Value*.
+--
+
+. Click *Submit* to create the application. You will be redirected to the list of applications.
+. Select the application you just created.
+. Find the *Jwt Verifier Maps* tab and click *New*.
+. Configure the new record as follows:
++
+--
+* *Name*: Name the JWT Verifier Map.
+* *Sys certificate*: Click the search icon and select the name of the certificate created in the previous step.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-new-jwt-verifier-map.png[Shows new JWT Verifier Map form in ServiceNow]
+--
+
+. Click *Submit* to create the application.
+. Note the *Client ID*, *Client Secret* and *JWT Key ID*. You will need these values to create your {sn} connector.
++
+--
+[role="screenshot"]
+image::management/connectors/images/servicenow-oauth-values.png[Shows where to find OAuth values in ServiceNow]
+--
 
 [float]
 [[servicenow-itom-connector-configuration]]
@@ -22,9 +126,16 @@ Create an integration user in {sn} and assign it the following roles.
 {sn} ITOM connectors have the following configuration properties.
 
 Name::      The name of the connector. The name is used to identify a  connector in the **Stack Management** connector listing, and in the connector list when configuring an action.
+Is OAuth::  The type of authentication to use.
 URL::       {sn} instance URL.
 Username::  Username for HTTP Basic authentication.
 Password::  Password for HTTP Basic authentication.
+User Identifier:: Identifier to use for OAuth type authentication. This identifier should be the *User field* you selected during setup. For example, if the selected *User field* is *Email*, the user identifier should be the user's email address.
+Client ID:: The client ID assigned to your OAuth application.
+Client Secret:: The client secret assigned to your OAuth application.
+JWT Key ID:: The key ID assigned to the JWT verifier map of your OAuth application.
+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]
 [[servicenow-itom-connector-networking-configuration]]
@@ -36,6 +147,7 @@ Use the <<action-settings, Action configuration settings>> to customize connecto
 [[Preconfigured-servicenow-itom-configuration]]
 ==== Preconfigured connector type
 
+Connector using Basic Authentication
 [source,text]
 --
  my-servicenow-itom:
@@ -48,23 +160,51 @@ Use the <<action-settings, Action configuration settings>> to customize connecto
      password: passwordkeystorevalue
 --
 
+Connector using OAuth
+[source,text]
+--
+ 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*.
+`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*.
-`password`::  A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
+`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 <<creating-keystore, {kib} keystore>>. 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]
 [[define-servicenow-itom-ui]]
 ==== Define connector in Stack Management
 
-Define {sn} ITOM connector properties.
+Define {sn} ITOM connector properties. Choose whether to use OAuth for authentication.
+
+[role="screenshot"]
+image::management/connectors/images/servicenow-itom-connector-basic.png[ServiceNow ITOM connector using basic auth]
 
 [role="screenshot"]
-image::management/connectors/images/servicenow-itom-connector.png[ServiceNow ITOM connector]
+image::management/connectors/images/servicenow-itom-connector-oauth.png[ServiceNow ITOM connector using OAuth]
 
 Test {sn} ITOM action parameters.