-
Notifications
You must be signed in to change notification settings - Fork 8.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into bfilar.ml-refactor-2
- Loading branch information
Showing
115 changed files
with
2,110 additions
and
747 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 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. | ||
|
|
||
| [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-itom | ||
| config: | ||
| apiUrl: https://example.service-now.com/ | ||
| usesTableApi: false | ||
| isOAuth: true | ||
| userIdentifierValue: [email protected] | ||
| 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. | ||
|
|
||
|
|
||
Oops, something went wrong.