Creating an extended integration for Rapid7 InsightVM users

Let Oomnitza be your single source of truth!

You'll get complete visibility of your users as data from Rapid7 InsightVM is automatically transformed into consumable information and actionable insights.

Connect Oomnitza and Rapid7 InsightVM in minutes

Get the information and insights that you need to reduce costs and the time that you spend on administration tasks such as:

• Configurable dashboards and list views of key user information
• Configurable reports to share information about users with your colleagues and management
• Configurable workflows that you can easily create such as: 
  • Workflows for getting users and getting user details 
  • Workflows for resetting user passwords and unlocking user accounts

Navigation

Setting your Rapid7 Subdomain as a global variable

Adding the credentials

Creating the user integration

Creating custom mappings

Creating workflows

Creating user workflows with the API block

Get User Details

Reset User Password

Unlock User Account

Before you start

Best practice
For the integration with Oomnitza, create a dedicated user account.

To stream Rapid7 InsightVM user data into Oomnitza, you must add your Rapid7 authentication credentials to the vault in Oomnitza. 

To create the integrations with Oomnitza, you must know:

• The email address and password of a Rapid7 user with administrator privileges. When adding the credentials to Oomnitza, you enter the email as the username.
• The Rapid7 API host name. The format of the URL is https://<host>:<port>/api/3 . You enter the host part of the URL. If you don't know the Rapid7 host name, contact Rapid7 Support. 
• The Rapid7 API port number. The format of the URL is https://<host>:<port>/api/3 . You enter the number that is shown after the colon (:). If you don't know the Rapid7 port number contact Rapid7 Support. 

 For more information, see INSIGHTVM API (V3) 

Setting your Rapid7 API host name and port as a global variable

To save time entering information when you integrate Rapid7, you can add the API port number and API host name as global variables in Oomnitza.

1. Click Configuration > General > Global Settings.
2. Click Add new variable (+). 
3. Enter Rapid7.Api Port as the variable key.
4. Enter the port number as the value.
5. Click SAVE.
6. Repeat step 1 and 2.
7. Enter Rapid7.Api Host as the variable key.
8.  Enter the host name as the value.
9. Click SAVE.

Adding the credentials

To authorize connections between Oomnitza and Rapid7, complete these steps:

1. In Oomnitza, go to Configuration>Security>Credentials.
2. Click Add new credential (+).
3. Search for the integration, and then click the forward button > to select the integration.
4. Enter the user name and password of your account
5. Click Create.

Integration not in the list? Click Advanced Mode and complete these steps:

1. Add the information details.
2. Click the AUTHORIZATION tab.
3. Ensure that Basic Auth is selected as the authorization type.
4. Enter the user name and password of your account.
5. Click Create. 

You use the credentials that you added to create and customize your Rapid7 integrations with Oomnitza.

Create the user integration

1. In Oomnitza, click Configuration > Integrations > Overview.
2. Click Block view .
3. On the Integrations page, scroll down to the Extended section for user integrations.
4. Click NEW INTEGRATION.
5. In the sidebar, search for the integration.
6. Click ADD.

Integration details overview

More information is provided about the following fields to help you complete the integration:

• User only. Add user records.
• User plus SaaS user. Add user and SaaS user records. 

The benefit of adding SaaS user records is that you can run a workflow to validate the status and activity of SaaS users and retrieve information such as the role of the SaaS user. The information that can be retrieved depends on whether SaaS user workflows are available for the integration. 

Installation types

• Cloud. Store credentials in the Oomnitza cloud.
• Local. Store credentials locally. If you want to sync Oomnitza with vendor applications that require AWS or OAUTH authentication, select cloud as the type of installation. Local installations don't support AWS and OAuth authentication. 

Integration preferences

• Create & Update. Add and update records.
• Create only. Add records.
• Update only. Update records.

Editing the integration details

1. Click Edit .
2. Make your changes.

Editing the credential details

If you selected Cloud as the installation type, choose one of the following options:

• Select the credentials that were created for the integration.
• Edit the credentials that were created for the integration.
• Create new credentials

Scheduling the integration

By default, data is synced once every day. Change the interval or the time so that the data is streamed when your system isn't busy.

1. Click Edit .
2. Make and save your changes.

Mapping fields to Oomnitza

To map the fields to Oomnitza, click Edit .

  Selecting Edit integration to add rules for syncing data. Filtering integration results.  
 

You can add new fields to your integration by selecting Add new field   on the mapping page. 
Creating custom API fields. 

Creating custom mappings

Map the Rapid7 fields to Oomnitza fields and create custom mappings to get the user information that you need.

Complete these actions:

1. Click Smart Mapping to automatically detect appropriate mapping fields. Values from the integration can also be dragged to the appropriate field on the Oomnitza side, or selected from the integration field dropdown.
2. You must create a custom mapping for the Rapid7 Id field. To do this, complete these steps:
   1. Click the down arrow on the Id field.
   2. Select Add new Oomnitza users field.
   3. Change the name of the Id field to Rapid7 User ID. 
   4. Select the Unique checkbox.
   5. Click CREATE. 
3. Ensure that the Email is mapped to the
   1. Username field on the Oomnitza side (required for integration).
   2. Email field on the Oomnitza side (required for integration).
4. Select the Role field on the Oomnitza mapping side.
5. Choose a suitable role from the list (a defined role is necessary for the integration)
6. Assign a sync key to a unique field, such as the Email.
7. Click UPDATE.

Tracking information for asset integration  

When the integration is run, you can track the name of the credentials that were used and the source of the data. To do this, you map the following fields to Oomnitza:   

• Connect: Credentials
• Connect: Rapid7 API Host
• Connect: Rapid7 API Port

Custom mappings

The following Rapid7 fields can be mapped to Oomnitza:

Authentication Type
Connector Sync Time
Email
Id
Is Enabled
Is Locked
Is Password Reset On Login
Is Role All Asset Groups
Is Role All Sites
Is Role Superuser
Locale Default
Locale Reports
Login
Name
Password
Role Id

Launching the integration

Your integration is in Draft mode until the required mandatory fields are added. When added, click Launch to activate your integration. 

If you selected Cloud as the installation type when creating the integration, see Running an extended integration

If you selected Local as the installation type when creating the integration, see Running an extended integration locally.

Viewing data ingested by Oomnitza

Viewing ingested asset data

For asset integrations, click Hardware. If the asset integration also ingests software data, click Software.

Viewing ingested user data

For user integrations, click People. If you chose the option to ingest User and SaaS user data, click Software > SaaS, click the SaaS app, and then click the Users tab. 

Related Links

• Running an extended integration
• Troubleshooting integrations
• Mapping extended integrations

Creating workflows

Creating user workflows with the API block

To reduce your workload and automate complex and repetitive tasks, you can create user workflows with the API block by following the steps in Using the API block. To locate the available presets, enter Rapid7 in the Select Preset search field. Select your preset of choice and for every preset enter the following information in the Configure section:

• Your Rapid7 API host name and port number, which is derived from the global variable Rapid7.Api Host and Rapid7.Api Port that you configured in Setting your Rapid7 Subdomain as a global variable. Alternatively, you can enter this information manually.
• You credentials, which you created in Adding the credentials.

The Rapid7 API block workflow comes with the following presets for users:

Get User Details
Reset User Password
Unlock User Account

Using the Rapid7 Get User Details preset

The Get User Details preset returns the details of a user. You can use the Advanced Mode to map the API response. To do this, complete the following steps:

1. In the API block window, click the Advanced Mode button located in the upper right of the window.
2. Select the Response tab. You can map the entire response by placing {{response}} in the Response field and mapping it to a custom long text Oomnitza field, such as API Response. For further information on how to map an API response, see Mapping positive and negative responses.

For further information see Rapid7 REST API documentation: Users.

Using the Rapid7 Reset User Password preset

The Reset User Password preset resets the users password to a new password that is provided as input. When constructing a workflow that uses this preset, the New Password field is required. You can use the Advanced Mode to configure the message payload. To do this, complete the following steps:

1. In the API block window, click the Advanced Mode button located in the upper right of the window.
2. In the Information tab, you will notice that the Rapid7 User ID is referenced in the field {{rapid7_user_id}}that you created in Creating custom mappings.  If this is not correct, you can replace the variable {{rapid7_user_id}} in the URL field with the correct variable or user id. 
3. Select the Response tab. You can map the entire response by placing {{response}} in the Response field and mapping it to a custom long text Oomnitza field, such as API Response. For further information on how to map an API response, see Mapping positive and negative responses.

For further information see Rapid7 REST API documentation: Password Reset.

Using the Rapid7 Unlock User Account preset

The Unlock User Account preset unlocks a user account that has been locked by the system due to too many failed password attempts. Disabled accounts may not be unlocked. You can follow the steps in Using the Rapid7 Get User Details preset to configure the message payload.

For further information see Rapid7 REST API documentation: Unlock Account.

Reference articles for workflows

• Mapping positive and negative responses
• Troubleshooting workflows 
• Using the API block

Unleash the power of Oomnitza

To get valuable actionable insights that help you manage your users, learn how to:

• Configure dashboards for your users and software
• Configure custom reports about your users and software
• Create workflows to automate tasks

See Getting started for more information.

Did you know
You can also create extended connector integrations for Rapid7 assets.
Creating an extended integration for Rapid7 assets