ServiceNow ITOM connector and action

edit

ServiceNow ITOM connector and action

edit

The ServiceNow ITOM connector uses the event API to create ServiceNow events. You can use the connector for rule actions.

Prerequisites

edit
Create a ServiceNow integration user
edit

To ensure authenticated communication between Elastic and ServiceNow, create a ServiceNow integration user and assign it the appropriate roles.

  1. In your ServiceNow instance, go to System Security → Users and Groups → Users.
  2. Click New.
  3. Complete the form, then right-click on the menu bar and click Save.
  4. Go to the Roles tab and click Edit.
  5. 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.
  6. Click Save.
Create an RSA keypair and add an X.509 Certificate
edit

This step is required to use OAuth for authentication between Elastic and ServiceNow.

Create an RSA keypair:

  1. Use OpenSSL to generate an RSA private key:

    openssl genrsa -out example-private-key.pem 3072
    openssl genrsa -passout pass:foobar -out example-private-key-with-password.pem 3072 

    Use the passout option to set a password on your private key. This is optional but remember your password if you set one.

  2. Use OpenSSL to generate the matching public key:

    openssl req -new -x509 -key example-private-key.pem -out example-sn-cert.pem -days 360

Add an X.509 certificate to ServiceNow:

  1. In your ServiceNow instance, go to Certificates and select New.
  2. Configure the certificate as follows:

    • Name: Name the certificate.
    • PEM Certificate: Copy the generated public key into this text field.
    Shows new certificate form in ServiceNow
  3. Click Submit to create the certificate.
Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map
edit

This step is required to use OAuth for authentication between Elastic and ServiceNow.

  1. In your ServiceNow instance, go to Application Registry and select New.
  2. Select Create an OAuth JWT API endpoint for external clients from the list of options.

    Shows application type selection
  3. Configure the application as follows:

    • Name: Name the application.
    • User field: Select the field to use as the user identifier.
    Shows new application form in ServiceNow

    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.

  4. Click Submit to create the application. You will be redirected to the list of applications.
  5. Select the application you just created.
  6. Find the Jwt Verifier Maps tab and click New.
  7. 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.
    Shows new JWT Verifier Map form in ServiceNow
  8. Click Submit to create the verifier map.
  9. Note the Client ID, Client Secret and JWT Key ID. You will need these values to create your ServiceNow connector.

    Shows where to find OAuth values in ServiceNow

Create connectors in Kibana

edit

You can create connectors in Stack Management > Connectors or as needed when you’re creating a rule. You must choose whether to use OAuth for authentication.

ServiceNow ITOM connector using basic auth
ServiceNow ITOM connector using OAuth
Connector configuration
edit

ServiceNow ITOM connectors have the following configuration properties:

Name
The name of the connector.
Is OAuth
The type of authentication to use.
URL
ServiceNow 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.

Create preconfigured connectors

edit

If you are running Kibana on-prem, you can define connectors by adding xpack.actions.preconfigured settings to your kibana.yml file. For example:

Connector using Basic Authentication

xpack.actions.preconfigured:
  my-servicenow-itom:
    name: preconfigured-servicenow-connector-type
    actionTypeId: .servicenow-itom
    config:
      apiUrl: https://example.service-now.com/
    secrets:
      username: testuser
      password: passwordkeystorevalue

Connector using OAuth

 my-servicenow:
   name: preconfigured-oauth-servicenow-connector-type
   actionTypeId: .servicenow-itom
   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. Required if isOAuth is set to false.
password
A string that corresponds to Password. Should be stored in the Kibana 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.

Test connectors

edit

You can test connectors with the run connector API or as you’re creating or editing the connector in Kibana. For example:

ServiceNow ITOM params test

ServiceNow ITOM actions have the following configuration properties.

Source
The name of the event source type.
Node
The Host that the event was triggered for.
Type
The type of event.
Resource
The name of the resource.
Metric name
Name of the metric.
Source instance (event_class)
Specific instance of the source.
Message key
All actions sharing this key will be associated with the same ServiceNow alert. Default value: <rule ID>:<alert instance ID>.
Severity
The severity of the event.
Description
The details about the event.

Refer to ServiceNow documentation for more information about the properties.

Connector networking configuration

edit

Use the 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.

Configure ServiceNow ITOM

edit

ServiceNow offers free Personal Developer Instances, which you can use to test incidents.