Skip to content

[DOCS] Edits OAuth instructions in ServiceNow connector docs #134970

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

Merged
lcawl merged 5 commits into from
Jun 23, 2022
Merged

[DOCS] Edits OAuth instructions in ServiceNow connector docs #134970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dfc300b
[DOCS] Add anchors to serviceNow ITSM connector
lcawl Jun 22, 2022
1b0b300
[DOCS] Add anchors and tagged regions to servicenow connectors
lcawl Jun 23, 2022
f54a499
Merge branch 'main' into oauth
lcawl Jun 23, 2022
7b445eb
[DOCS] Adds sn-itom attribute
lcawl Jun 23, 2022
9aa4fad
[DOCS] Fixed end of tagged region
lcawl Jun 23, 2022
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
139 changes: 34 additions & 105 deletions docs/management/connectors/action-types/servicenow-itom.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,129 +1,58 @@
[role="xpack"]
[[servicenow-itom-action-type]]
=== ServiceNow ITOM connector and action
== {sn-itom} connector and action
++++
<titleabbrev>ServiceNow ITOM</titleabbrev>
<titleabbrev>{sn-itom}</titleabbrev>
++++

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] to create {sn} events.
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]
to create {sn} events.

[float]
[[servicenow-itom-connector-prerequisites]]
==== Prerequisites
* Create a {sn} integration user and assign it the appropriate roles.
=== Prerequisites

If you use open authorization (OAuth), you must also:

* Create an RSA keypair and add an X.509 Certificate.
* Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map.
. <<servicenow-itom-connector-prerequisites-integration-user,Create a {sn} integration user and assign it the appropriate roles.>>
. If you use open authorization (OAuth), you must also:
.. <<servicenow-itom-connector-prerequisites-rsa-key,Create an RSA keypair and add an X.509 Certificate>>.
.. <<servicenow-itom-connector-prerequisites-endpoint,Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map>>.

[float]
===== Create a {sn} integration user
[[servicenow-itom-connector-prerequisites-integration-user]]
==== 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: 
. 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
[[servicenow-itom-connector-prerequisites-rsa-key]]
==== 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:*
include::servicenow.asciidoc[tag=servicenow-rsa-key]

. 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.
include::servicenow.asciidoc[tag=servicenow-certificate]

[float]
===== Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map
[[servicenow-itom-connector-prerequisites-endpoint]]
==== 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]
--
include::servicenow.asciidoc[tag=servicenow-endpoint]

[float]
[[servicenow-itom-connector-configuration]]
==== Connector configuration
=== Connector configuration

{sn} ITOM connectors have the following configuration properties.
{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.
Expand All @@ -139,13 +68,13 @@ Private Key Password:: The password for the RSA private key generated during set

[float]
[[servicenow-itom-connector-networking-configuration]]
==== Connector networking configuration
=== Connector networking configuration

Use the <<action-settings, Action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.

[float]
[[Preconfigured-servicenow-itom-configuration]]
==== Preconfigured connector type
=== Preconfigured connector type

Connector using Basic Authentication
[source,text]
Expand Down Expand Up @@ -196,26 +125,26 @@ Secrets defines sensitive information for the connector type.

[float]
[[define-servicenow-itom-ui]]
==== Define connector in Stack Management
=== Define connector in Stack Management

Define {sn} ITOM connector properties. Choose whether to use OAuth for authentication.
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]
image::management/connectors/images/servicenow-itom-connector-basic.png[{sn-itom} connector using basic auth]

[role="screenshot"]
image::management/connectors/images/servicenow-itom-connector-oauth.png[ServiceNow ITOM connector using OAuth]
image::management/connectors/images/servicenow-itom-connector-oauth.png[{sn-itom} connector using OAuth]

Test {sn} ITOM action parameters.
Test {sn-itom} action parameters.

[role="screenshot"]
image::management/connectors/images/servicenow-itom-params-test.png[ServiceNow ITOM params test]
image::management/connectors/images/servicenow-itom-params-test.png[{sn-itom} params test]

[float]
[[servicenow-itom-action-configuration]]
==== Action configuration
=== Action configuration

{sn} ITOM actions have the following configuration properties.
{sn-itom} actions have the following configuration properties.

Source:: The name of the event source type.
Node:: The Host that the event was triggered for.
Expand All @@ -227,10 +156,10 @@ Message key:: All actions sharing this key will be associated with the same {sn
Severity:: The severity of the event.
Description:: The details about the event.

Refer to https://docs.servicenow.com/bundle/rome-it-operations-management/page/product/event-management/task/send-events-via-web-service.html[ServiceNow documentation] for more information about the properties.
Refer to https://docs.servicenow.com/bundle/rome-it-operations-management/page/product/event-management/task/send-events-via-web-service.html[{sn} documentation] for more information about the properties.

[float]
[[configuring-servicenow-itom]]
==== Configure {sn} ITOM
=== Configure {sn-itom}

{sn} offers free https://developer.servicenow.com/dev.do#!/guides/madrid/now-platform/pdi-guide/obtaining-a-pdi[Personal Developer Instances], which you can use to test incidents.
Loading