---
title: ServiceNow SecOps connector and action
description: The ServiceNow SecOps connector uses the import set API to create ServiceNow security incidents. You can use the connector for rule actions and cases...
url: https://www.elastic.co/docs/reference/kibana/connectors-kibana/servicenow-sir-action-type
---

# ServiceNow SecOps connector and action

The ServiceNow SecOps connector uses the [import set API](https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest/c_ImportSetAPI) to create ServiceNow security incidents. You can use the connector for rule actions and cases.

## Create connectors in Kibana

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 SecOps connector using basic auth](https://www.elastic.co/docs/reference/kibana/images/servicenow-sir-connector-basic.png)

![ServiceNow SecOps connector using OAuth](https://www.elastic.co/docs/reference/kibana/images/servicenow-sir-connector-oauth.png)


### Connector configuration

ServiceNow SecOps connectors have the following configuration properties:
<definitions>
  <definition term="Client ID">
    The client ID assigned to your OAuth application.
  </definition>
  <definition term="Client Secret">
    The client secret assigned to your OAuth application.
  </definition>
  <definition term="JWT verifier key ID">
    The key identifier assigned to the JWT verifier map of your OAuth application.
  </definition>
  <definition term="Password">
    The password for HTTP basic authentication.
  </definition>
  <definition term="Private key">
    The RSA private key that you created for use in ServiceNow.
  </definition>
  <definition term="Private key password">
    The password for the RSA private key. This value is required if you set a password for your private key.
  </definition>
  <definition term="ServiceNow instance URL">
    The full ServiceNow instance URL.
  </definition>
  <definition term="Use OAuth authentication">
    By default, basic authentication is used instead of open authorization (OAuth).
  </definition>
  <definition term="User identifier">
    The 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.
  </definition>
  <definition term="Username">
    The username for HTTP basic authentication.
  </definition>
</definitions>


## Test connectors

You can test connectors as you're creating or editing the connector in Kibana. For example:
![ServiceNow SecOps params test](https://www.elastic.co/docs/reference/kibana/images/servicenow-sir-params-test.png)

ServiceNow SecOps actions have the following configuration properties.
<definitions>
  <definition term="Additional comments">
    Additional information for the client, such as how to troubleshoot the issue.
  </definition>
  <definition term="Additional fields">
    An object that contains custom field identifiers and their values. These fields must exist in the Elastic ServiceNow application and must be specified in JSON format.
    For example:
    ```sh
    {
        "u_cmdb_ci": "host-a",
        "u_company": "My company",
        "u_assignment_group": "Testing"
    }
    ```
    Note that the default source field names in the Elastic ServiceNow application are prefixed with "u_".
  </definition>
  <definition term="Category">
    The category of the incident.
  </definition>
  <definition term="Correlation display">
    A descriptive label of the alert for correlation purposes in ServiceNow.
  </definition>
  <definition term="Correlation ID">
    Connectors using the same correlation ID will be associated with the same ServiceNow incident. This value determines whether a new ServiceNow incident will be created or an existing one is updated. Modifying this value is optional; if not modified, the rule ID and alert ID are combined as `{{ruleID}}:{{alert ID}}` to form the correlation ID value in ServiceNow. The maximum character length for this value is 100 characters.
    <note>
      Using the default configuration of `{{ruleID}}:{{alert ID}}` ensures that ServiceNow will create a separate incident record for every generated alert that uses a unique alert ID. If the rule generates multiple alerts that use the same alert IDs, ServiceNow creates and continually updates a single incident record for the alert.
    </note>
  </definition>
  <definition term="Description">
    The details about the incident.
  </definition>
  <definition term="Priority">
    The priority of the incident.
  </definition>
  <definition term="Short description">
    A short description for the incident, used for searching the contents of the knowledge base.
  </definition>
  <definition term="Subcategory">
    The subcategory of the incident.
  </definition>
</definitions>


## Connector networking configuration

Use the [Action configuration settings](/docs/reference/kibana/configuration-reference/alerting-settings#action-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 SecOps

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

### Prerequisites

After upgrading from Elastic Stack version 7.15.0 or earlier to version 7.16.0 or later, you must complete the following within your ServiceNow instance before creating a new ServiceNow SecOps connector or [updating an existing one](#servicenow-sir-connector-update):
1. Install [Elastic for Security Operations (SecOps)](https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f) from the ServiceNow Store.
2. [Assign cross-scope privileges for the Elastic for Security Operations app](#servicenow-sir-connector-privileges).
3. [Create a ServiceNow integration user and assign it the appropriate roles](#servicenow-sir-connector-prerequisites-integration-user).
4. [Create a Cross-Origin Resource Sharing (CORS) rule](#servicenow-sir-connector-prerequisites-cors-rule).
5. If you use open authorization (OAuth), you must also:   
   1. [Create an RSA keypair and add an X.509 Certificate](#servicenow-sir-connector-prerequisites-rsa-key).
   2. [Create an OAuth JWT API endpoint for external clients with a JWT Verifiers Map](#servicenow-sir-connector-prerequisites-endpoint).


### Assign cross-scope privileges

The Elastic for Security Operations app requires specific cross-scope privilege records to run successfully. In particular, you must have a privilege record for the `Elastic for Security Operations` application with the status set to `Allowed` for each of the following targets:

| Target scope                       | Name                                   | Type       | Operation   |
|------------------------------------|----------------------------------------|------------|-------------|
| Global                             | Glide API: string utilities            | Scriptable | Execute API |
| Global                             | GlideRecord.insert                     | Scriptable | Execute API |
| Global                             | GlideRecord.setValue                   | Scriptable | Execute API |
| Global                             | GlideRecordSecure.getValue             | Scriptable | Execute API |
| Global                             | RESTAPIRequest                         | Scriptable | Execute API |
| Global                             | RESTAPIRequestBody                     | Scriptable | Execute API |
| Global                             | ScopedGlideElement                     | Scriptable | Execute API |
| Global                             | ScriptableServiceResultBuilder.setBody | Scriptable | Execute API |
| Security incident response         | sn_si_incident                         | Table      | Read        |
| Threat intelligence support common | sn_ti_m2m_task_observable              | Table      | Create      |
| Threat intelligence support common | sn_ti_m2m_task_observable              | Table      | Read        |
| Threat intelligence support common | sn_ti_observable                       | Table      | Create      |
| Threat intelligence support common | sn_ti_observable                       | Table      | Read        |
| Threat intelligence support common | sn_ti_observable_type                  | Table      | Read        |

To access the cross scope privileges table:
1. Log into ServiceNow and set your application scope to Elastic for Security Operations.
2. Click **All** and search for `sys_scope_privilege`.

For more details, refer to the [ServiceNow product documentation](https://docs.servicenow.com/).

### Create a ServiceNow integration user

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:   
   - `import_set_loader`
   - `import_transformer`
   - `personalize_choices`
   - `sn_si.basic`
   - `x_elas2_sir_int.integration_user`
6. Click **Save**.


### Create a CORS rule

A CORS rule is required for communication between Elastic and ServiceNow. To create a CORS rule:
1. In your ServiceNow instance, go to **System Web Services → REST → CORS Rules**.
2. Click **New**.
3. Configure the rule as follows:   
   - **Name**: Name the rule.
   - **REST API**: Set the rule to use the Elastic SecOps API by choosing `Elastic SIR API [x_elas2_sir_int/elastic_api]`.
   - **Domain**: Enter the Kibana URL, including the port number.
4. Go to the **HTTP methods** tab and select **GET**.
5. Click **Submit** to create the rule.


### Create an RSA keypair and add an X.509 Certificate

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

#### Create an RSA keypair

1. Use [OpenSSL](https://www.openssl.org/docs/man1.0.2/man1/genrsa.md) to generate an RSA private key.   
   - To create a private key with a password, use the `passout` option. For example:     
   ```sh
   openssl genrsa -passout pass:foobar -out example-private-key-with-password.pem 3072
   ```
   - To create a private key without a password, omit the `passout` option. For example:     
   ```sh
   openssl genrsa -out example-private-key.pem 3072
   ```
2. Use [OpenSSL](https://www.openssl.org/docs/man1.0.2/man1/req.md) to generate the matching public key:   
   ```sh
   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](https://www.elastic.co/docs/reference/kibana/images/servicenow-new-certificate.png)
3. Click **Submit** to create the certificate.


### 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 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](https://www.elastic.co/docs/reference/kibana/images/servicenow-jwt-endpoint.png)
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](https://www.elastic.co/docs/reference/kibana/images/servicenow-new-application.png)   
   <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**.
   </important>
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](https://www.elastic.co/docs/reference/kibana/images/servicenow-new-jwt-verifier-map.png)
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](https://www.elastic.co/docs/reference/kibana/images/servicenow-oauth-values.png)


## Update a deprecated ServiceNow SecOps connector

ServiceNow SecOps connectors created in Elastic Stack version 7.15.0 or earlier are marked as deprecated after you upgrade to version 7.16.0 or later. Deprecated connectors have a yellow icon after their name and display a warning message when selected.
![Shows deprecated ServiceNow connectors](https://www.elastic.co/docs/reference/kibana/images/servicenow-sir-update-connector.png)

<important>
  Deprecated connectors will continue to function with the rules they were added to and can be assigned to new rules. However, it is strongly recommended to update deprecated connectors or [create new ones](/docs/reference/kibana/connectors-kibana#creating-new-connector) to ensure you have access to connector enhancements, such as updating incidents.
</important>

To update a deprecated connector:
1. Go to the **Connectors** page using the navigation menu or the [global search field](https://d34ipnu52o64md.cloudfront.net/docs/explore-analyze/find-and-organize/find-apps-and-objects).
2. Select the deprecated connector to open the **Edit connector** flyout.
3. In the warning message, click **Update this connector**.
4. Complete the guided steps in the **Edit connector** flyout.   
   1. Install [Elastic for Security Operations (SecOps)](https://store.servicenow.com/sn_appstore_store.do#!/store/application/2f0746801baeb01019ae54e4604bcb0f) from the ServiceNow Store and complete the [required prerequisites](#servicenow-sir-connector-prerequisites).
   2. Enter the URL of your ServiceNow instance.
   3. Enter the username and password of your ServiceNow instance.
5. Click **Update**.
