Introduction
This guide is designed for users who want to enable Dark Web ID integration with ConnectWise. It walks you through a step-by-step setup process and will allow you to enable this integration.
Integration Overview
The functionality is a significant Dark Web ID enhancement that leverages integration with ConnectWise:
- This integration improves customers' ability to manage compromises by creating PSA tickets for each new compromise. This makes them easier to track, manage, and remediate.
Prerequisites
- You must have access to both Dark Web ID and ConnectWise accounts.
Additionally, please note that sometimes your Dark Web ID user account must be configured to allow integration access. Please get in touch with support at darkwebid.com or call 844-ID AGENT, and a customer support representative will help you enable integration access for your user account.
Setting up the Integration
To Get Started
Enter your credentials on the ConnectWise page and click LOGIN. (For your convenience, we have provided the current login URL: https://na.myconnectwise.net/ ).
Instructions to Configure ConnectWise
The below section covers the step-by-step ConnectWise (CW) configuration permissions workflow.
Users & Roles
It is advised to operate with API using different users.
Permissions
API User has the following permissions assigned to the role:
Companies → Company Maintenance → Inquire Level: All
Service Desk → Service Tickets → Inquire Level: All
Service Desk → Service Tickets → Add Level: All
System → Table Setup → Inquire Level: All
Under the customize link next to Table Setup, please configure it as follows:
Allow List should include Company / Company Status, Service / Priority, Service / Service Board, and Service / Source.
Click Save to close the customized setup. Then save the role.
Generating an API Key
It's recommended to use API Key and secret instead of username and password. You can generate one or more API keys for your account. To generate a new API key, go to the upper-right corner of the ConnectWise admin panel and click My Account under your user's settings.
Then, open the API Keys tab and click + (New Item) to create a new key and secret set.
Your ConnectWise user must be assigned a Security.
Enabling Integration
To enable Dark Web ID integration with ConnectWise, follow these steps:
1. Log in to the Dark Web ID.
2. On the Partner Dashboard page, navigate to the left panel and click Integrations.
3. Click New Integration under the PSA tab to define your ticketing integration.
4. This page shows you the available integration services. Select the ConnectWise service from the New Integration modal window and click Submit to proceed.
5. On the Create Integration page, name your integration. It is possible to have multiple integrations of the same type, so we recommend calling them as needed:
- Credentials: The region is selected to identify the data center location from where data is being fetched. Available data centers are in North America, Europe, and Australia.
Note: If your organizations are between multiple managed sites, you must set up multiple ConnectWise integrations.
- ConnectWise documentation suggests creating an API Member for third-party use.
- From ConnectWise Documentation:
- Using the same setup screen as creating a member, an API Member allows granular control over what type of information an integration can access. A global user allows integrations to be turned on and off easily without requiring the person initially to set up the integration.
- API Members are the recommended route for most integrations.
- The Members screen can be found by opening the System Module and the Members page. After accessing the Members page, click the API Members tab. You can create a new user and generate API Keys for them here.
- API Members do not require a user license.
- From ConnectWise Documentation:
- In addition to username and password, this step also accepts public and private API keys.
6. Enter your ConnectWise Information. Regarding Users & Roles, using separate users to operate with API is recommended. Please create a new user and assign a role with the permissions described in the next paragraph.
7. Once you enter information on the Integration page, click Save. You will see the ConnectWise authentication successful message on a page as shown.
8. Ensure you edit your organization name to match them across both products. The Dark Web ID Organization title should exactly match ConnectWise company names.
9. Populate required content as it should map to ConnectWise service ticket fields. You can use the Dark Web ID tokens to add context to your service tickets.
Note: One Dark Web ID SMB organization can only be mapped to one ConnectWise service ticket.
Available Dark Web ID Tokens
[uuid] UUID (text) - Dark Web ID's unique identifier for the compromise
[password] Password Hit (text (255)) - The password hit associated with the compromise
[obscured_password] Password Hit (Obscured) (text (255)) – The password hit related to the compromise is obscured with asterisks after the first four characters.
[record_type] Record Type (text (255)) – The type of record monitored: Email, Domain, or IP
[Source] Source (text (255)) – The record source as reported in Dark Web ID
[website] Website (text (255)) – The record website as reported by Dark Web ID
[organization_name] Organization Name (text (255)) – The name of the organization to which the compromise belongs
[compromise] Compromise (text (255)) – The record compromise as reported in Dark Web ID
[password_criteria] Password Criteria (text (255)) – An indication of whether the compromised password meets the organization's password criteria: 'N/A' 'Matches' 'Doesn't Match'
[search_value] Email Domain / IP Address (text (255)) – The email or IP address found by Dark Web ID [date_added] Date Added (Date) – The date on which the compromise was added to Dark Web ID[date_found] Date Found (Date) – The date on which the compromise was found
10. Add additional fields as necessary.
Available ConnectWise Fields
Address 1 (String(50))
Address 2 (String(50))
Automatic Email CC Address (String (1000)) City (String(50))
Company (CompanyReference) Contact Email Address (String (250)) Contact Email Lookup (String) Contact Name (String (62))
Contact Phone Extension (String (15)) Contact Phone Number (String (20)) Date ResPlan (String)
Date Resolved (String) Date Responded (String)
Estimated State Date (String) External Reference (String (100)) Initial Description (String)
Initial Internal Analysis (String) Initial Resolution (String)
Item (ServiceItemReference) PO Number (String (50)) Priority (PriorityReference) Required Date (String) Resources (String)
Site Name (String (50))
Source (ServiceSourceReference) State (String (50))
Status (ServiceStatusReference) Sub Date Accepted (String)
Sub Type (ServiceTypeReference)
Summary (String (100))
Type (ServiceTypeReference) Zip (String (12))
11. Save your Integration: In the lower-right corner of the page, click Save or Save And Submit A Test Compromise for your configuration. This option will populate a service ticket as you've constructed here with test data in your ConnectWise platform. If you receive an error upon saving, check your field mapping and try again. Contact support@idagent.com if you experience any unexpected behavior.
Note: You can map a single Dark Web ID SMB organization to ConnectWise per ticket.
Health indicators: There are two Health statuses for Integrations. Healthy, represented by a tick mark, means your most recent integration request was successful! Unhealthy, represented by a cross mark X, means that your most recent integration request was unsuccessful or resulted in an error. This status will persist until a successful integration request is completed.
Note: Integration is marked unhealthy after the fifth unsuccessful consecutive attempt. The error will be shown on the Edit screen.
Status indicators: You can turn your integration on/off using the toggle button.
You can edit the integration using the edit icon, and the delete icon will completely delete your integration.
12. Associate Organizations with Integrations: You can edit an existing organization or add a new organization. Organizations can be associated with multiple integrations, and any new SMBs will be dynamically mapped with the company on the ConnectWise side. Still, you must enable integration on the SMB edit page to send compromises for those integrations. A count of associated organizations is displayed in the Integrations table.
13. Enable your Integration: Integrations are turned off by default. You can enable your integration using the toggle button.
After that, all new compromises imported to Dark Web ID will attempt to create a service ticket with the associated platform. Turning off an integration will cease the attempts to generate service tickets with the associated platform.
Note: You can turn your integrations on or off at any time.
14. Enable Integration on SMB: Once you enable the integration toggle button on the Integrations page, you must enable it on the SMB edit page for compromises to send this SMB organization.
- You can go to the SMB edit page.
- You can scroll down to view the Associated Integration section.
- Select the ConnectWise Integration_Test (or given Integration Title) check box and click Save.
Important: If an organization is disabled, monitoring of the domains continues and the integration remains active. PSA notifications will still be generated, but email notifications will not be sent to this organization. If it is necessary to prevent PSA tickets from being created, in the Associated Integrations section, clear the ConnectWise Integration_Test (or given Integration Title) check box.
You can view the list of active organizations connected to ConnectWise on the Integrations page.