KnowBe4 Plugin for Risk Exchange

This document explains how to configure the KnowBe4 v2.0.0 plugin with the Risk Exchange module of the Netskope Cloud Exchange platform. This plugin fetches Users from the Users > User Management page of the KnowBe4 console. This plugin supports the Add User to Group, Remove User from Group, Enroll in Training, and Update Custom Field actions on users in KnowBe4.

Netskope normalization score calculation for users > (1000 – (KnowBe4’s Current Risk Score) x 10).

Prerequisites

To complete this configuration, you need:

• A Netskope tenant (or multiple, for example, production and development/test instances).
• A Netskope Cloud Exchange tenant with the Tenant plugin and Risk Exchange plugin already configured.
• A KnowBe4 instance with a KSAT API token
  • PasswordIQ and SecurityCoach tokens (optional)
• Connectivity to the following hosts:
  • https://training.knowbe4.com (US), 
  • https://eu.knowbe4.com (EU), 
  • https://ca.knowbe4.com (CA), 
  • https://uk.knowbe4.com (UK),
  • https://de.knowbe4.com (DE).
• For Secret Manager configuration, refer to this documentation. To set up Azure Key Vault Secrets Manager refer to this documentation.

KnowBe4 Plugin Support

This plugin fetches Users from the Users > User Management page of the KnowBe4 console. This plugin supports the Add User to Group, Remove User from Group, Enroll in Training, and Update Custom Field actions on users in KnowBe4.

Mappings

Mappings are used to view the pulled Users details. Fields mapped during the plugin configuration will be visible on the Records page after the data is pulled. Here are the suggested mapping to use while configuring the plugin.

Pull Mapping for Users

Normalized Score Calculation

The expected score type on KnowBe4 is in the range 0 to 1000. Netskope normalization score calculation for users > (1000 – (KnowBe4’s Current Risk Score) x 10).
Note that for Risk Score values 0, 100, and string, it will skip the calculation of Netskope normalization score.

Permissions

Ensure the user, for which tokens will be created, has the necessary permissions to create an API token. Tokens have below permissions:

• KSAT API Token: Read/Write
• PasswordIQ API Token: Read Only
• SecurityCoach API Token: Read Only

{
  "data": {
    "users": {
      "nodes": [{ "id": 1234567 }],
      "pagination": { "totalCount": 250 }
    }
  }
}

{
  "data": {
    "users": {
      "nodes": [
        {
          "id": 1234567,
          "email": "sample_user@netskope.com",
          "firstName": "Sample",
          "lastName": "User",
          "displayName": "Sample User",
          "employeeNumber": "E-00001",
          "jobTitle": "Analyst",
          "department": "Sample Department",
          "managerEmail": "sample_user@netskope.com",
          "archived": false,
          "riskScore": 42.7,
          "currentPpp": 12.5,
          "customField1": "Tier 2",
          "customField2": null,
          "customField3": null,
          "customField4": null,
          "customDate1": "2026-09-01",
          "customDate2": null,
          "groups": [{ "id": 5001, "name": "Finance" }]
        }
      ],
      "pagination": { "page": 1, "pages": 3, "per": 100, "totalCount": 250 }
    }
  }
}

{
  "data": {
    "u0": {
      "nodes": [
        {
          "status": "IN_PROGRESS",
          "pastDue": true,
          "trainingCampaign": { "name": "2026 Annual Security Awareness" },
          "enrollmentItem": { "title": "2026 Security Awareness Training" }
        }
      ],
      "pagination": { "totalCount": 2, "pages": 1 }
    }
  }
}

{
  "data": {
    "passwordIqUserStates": {
      "users": [
        {
          "id": 88120,
          "kmsatId": 1234567,
          "events": [
            { "detectionType": { "name": "AD_PW_FOUND_IN_BREACH" }, "detected": true, "resolved": false },
            { "detectionType": { "name": "AD_PW_NEVER_EXPIRES" }, "detected": true, "resolved": true }
          ]
        }
      ],
      "pagination": { "page": 1, "pages": 1, "per": 100, "totalCount": 1 }
    }
  }
}

{
  "data": {
    "securityCoachListMappedUsers": {
      "recordsTotal": 250,
      "data": [
        {
          "id": 1234567,
          "email": "sample_user@netskope.com",
          "awarenessScore": 78,
          "antiPhishingScore": 64,
          "phishingReportScore": 55,
          "trainingScore": 90
        }
      ]
    }
  }
}

{
  "data": {
    "groups": {
      "nodes": [
        { "id": 5001, "name": "Finance" },
        { "id": 5002, "name": "Netskope High Risk" }
      ],
      "pagination": { "page": 1, "pages": 1, "totalCount": 2 }
    }
  }
}

{
  "data": {
    "trainingCampaigns": {
      "nodes": [{ "id": 7001, "name": "Remedial Phishing Training" }],
      "pagination": { "page": 1, "pages": 1, "totalCount": 1 }
    }
  }
}

{
  "data": {
    "groupCreate": {
      "errors": [],
      "node": { "id": 5002, "name": "Netskope High Risk" }
    }
  }
}

{
  "data": {
    "userAddToGroups": {
      "errors": [],
      "node": [
        { "id": 1234567, "email": "sample_user@netskope.com" },
        { "id": 1234568, "email": "sample_user@netskope.com" }
      ]
    }
  }
}

{
  "data": {
    "userDeleteMemberships": {
      "errors": [],
      "node": [{ "id": 1234567, "email": "sample_user@netskope.com" }]
    }
  }
}

{
  "data": {
    "trainingCampaignAddUser": {
      "errors": [],
      "node": true
    }
  }
}

{
  "data": {
    "userEdit": {
      "errors": [],
      "node": { "id": 1234567, "email": "sample_user@netskope.com" }
    }
  }
}

Performance Matrix

Here is the performance matrix conducted on a Large Cloud Exchange Stack with these specifications while pulling 500k users.

User Agent

netskope-ce-7.0.0-cre-knowbe4-v2.0.0

Workflow

1. Get your KnowBe4 API tokens.
2. Configure the KnowBe4 plugin.
3. Configure a Business Rule.
4. Configure Risk Exchange Actions.
5. Validate the KnowBe4 Plugin.

Watch a Video

Click play to watch a video.

Get your KnowBe4 API Tokens

1. Log in to the KnowBe4 console.

2. Go to Account Settings > Account Integrations > API > Product API.

   

   

3. Click Create New API Token to generate a KSAT API token.

   

4. Enter a Name, select KSAT for Products and Read/Write for Scopes, select an Expiration Date and User, and then click Create Token.

   

5. Copy the generated token and click OK.

   

6. If PasswordIQ is selected for Products, repeat the process in the PasswordIQ product’s API section to generate a PasswordIQ API token.

   

7. If SecurityCoach is selected for Products, repeat the process in the SecurityCoach product’s API section to generate a SecurityCoach API token.

   

Configure the KnowBe4 Plugin

1. In Cloud Exchange, go to Settings > Plugin Store. Search for and select the KnowBe4 v2.0.0 (CRE) plugin.

   

2. Enter a Configuration Name and change the Sync Interval if needed.

   

3. Click Next and enter the Configuration Parameters:

   • Base URL: Base URL of the tenant’s KnowBe4 account, without a path.
   • Custom Region URL: Base URL of the tenant’s KnowBe4 deployment, without a path. Required only when Base URL is set to Custom Region URL.
   • KSAT API Token: API token of the KnowBe4 Security Awareness Training (KSAT) product.
   • Pull Archived Users: Select Yes to also pull archived users in addition to active ones; select No to pull only active users.
   • Group Action Batch Size: Number of users sent in a single Add User to Group or Remove User from Group API call. Valid range 1–100. Default is 50.
   • Pull Additional Details: Select which additional details to pull for each user: Custom Fields, PasswordIQ, or SecurityCoach.
   • PasswordIQ API Token: API token of the KnowBe4 PasswordIQ product. Shown and required only when PasswordIQ is selected in Pull Additional Details.
   • SecurityCoach API Token: API token of the KnowBe4 SecurityCoach product. Shown and required only when SecurityCoach is selected in Pull Additional Details.

   

4. Click Next and configure the Entity source for Users. Select Users from the Entity dropdown, or click Add New Entity to create a new entity.

   

5. Map the plugin fields for the users entity with Risk Exchange fields (map the email string field of the plugin with the Email string field of the Users entity).

   

   Data type of the field will be enclosed in “()”

6. Click Add to map multiple fields.

7. Click Add Field to add a field in the Users entity. 

   

8. Add a Field Label, select a Data Type, Normalization, enable or disable the Unique restriction for the new field being added, and then select an Aggregate Strategy. When finished, click Save.

   

9. Map all the fields for Users Entity.

   

   

   

10. Click Save. Your plugin will appear on the Plugins page.

    

Configure a Risk Exchange Business Rule for KnowBe4

1. In Risk Exchange, go to Business Rules and click Add Business Rule.
2. Configure the source and filter conditions.

   

3. Click Save.

   

Configure a Risk Exchange Action for KnowBe4

To configure actions:

1. Go to Risk Exchange > Actions.

2. Click Add Action Configuration.

   

3. From the Business Rule dropdown, select the Business Rule you created.

4. From the Configuration dropdown, select your plugin.

5. From the Actions dropdown, select one of these actions:

   • Add User to Group: When triggered, it will add users to a group.
   • Remove User from Group: When triggered, it will remove users from a group.
   • Enroll in Training: When triggered, it will enroll users to training.
   • Update Custom Field: When triggered, it will update any of the custom fields of the user.
   • No action: This does not perform any actions on users. When No Action is selected, enable the Generate Alert toggle so that new alerts are added in the Ticket Orchestrator module.
     Make sure to enable the CTO (Ticket Orchestrator) module at Settings > General.

   

6. If you wish to perform an action during the Maintenance Window, enable the Perform action during Maintenance Window toggle. The Action will be performed during the Maintenance Window; otherwise, it will be performed instantly.

7. Disable the Require Approval toggle. Disabling this toggle will trigger the action automatically without any manual intervention. If the toggle is enabled, each action will require manual approval from the Cloud Exchange user.

8. Click Save.

9. To perform the actions, click Sync, add a Time Period, and click Fetch. The number of records for the action will be taken when you click Sync again.

   

   You can perform any actions on the Users pulled from KnowBe4 on the Netskope Tenant or any 3rd-party platform or vice-versa. For performing the Users related actions on Netskope or any 3rd-party plugin, refer to the Netskope’s plugin guide or 3rd-party plugin guide.

Add a User to a Group

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your plugin.
3. For Actions, select Add user to group.
4. For the Action Parameters, enter these details:
   • User ID: ID of the user on which action is to be taken. Select from Source Field dropdown, or provide static comma-separated User IDs.
   • Group: KnowBe4 group to add the user to. Only console groups are listed. Select the group from the Static Field dropdown only.
   • New Group name: Name of the group to create. This is used only when Create new group is selected in the Group parameter. Maximum 128 characters are allowed.
5. Enable the Require Approval toggle if Approval is needed before performing an action on the users.
6. Click Save.

Remove a User from a Group

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your plugin.
3. For Actions, select Remove user from group.
4. In the Action Parameters, enter these details:
   • User ID: ID of the user on which action is to be taken. Select from Source Field dropdown, or provide static comma-separated User IDs.
   • Group: KnowBe4 group to remove the user from. Only console groups are listed. Select the group from the Static Field dropdown only.
5. Enable the Require Approval toggle if Approval is needed before performing an action on the users.
6. Click Save.

Enroll in Training

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your plugin.
3. For Actions, select Enroll in Training.
4. For the Action Parameters, enter these details:
   • User ID: ID of the user on which action is to be taken. Select from Source Field dropdown, or provide static comma-separated User IDs.
   • Training Campaign: KnowBe4 training campaign to enroll the user into. Only campaigns that accept new users are listed. Select the training campaign from the static dropdown only.
5. Enable the Require Approval toggle if Approval is needed before performing an action on the users.
6. Click Save.

Update a Custom Field

1. In Risk Exchange, go to Actions click Add Action Configuration.
2. Select a Business Rule and your plugin.
3. For Actions, select Update Custom Field.
4. In the Action Parameters, enter these details:
   • User ID: ID of the user on which action is to be taken. Select from Source Field Dropdown or provide static comma-separated User IDs.
   • Custom Field: KnowBe4 custom field to write the value into. Select the custom field from the static dropdown only.
   • Value: Value to write into the selected custom field. It can be up to 255 characters. Enter a static value only.
5. Enable the Require Approval toggle if Approval is needed before performing an action on the users.
6. Click Save.

No Action

1. In Risk Exchange, go to Actions and click Add Action Configuration.
2. Select a Business Rule and your plugin.
3. For Actions, select No action.
4. Enable the Require Approval toggle if Approval is needed before performing an action on the users.
5. Click Save.

Validate the KnowBe4 Plugin

Validate in Cloud Exchange

To verify the Users pulled from KnowBe4, go to Logging and search for the logs from the CRE KnowBe4 plugin.

To check the records pulled and stored in Cloud Exchange, go to Records in Risk Exchange. Select the entity type used while adding the mapping in the plugin configuration.

Performed Actions

To verify the performed action, navigate to the Action Logs page and provide an approval to the action.

To verify the performed actions on Cloud Exchange, go to Logging and search for the logs from the CRE KnowBe4 plugin.

Add a User to a Group

Remove a User from a Group

Enroll in Training

Update a Custom Field

No Action

Validate on KnowBe4

Log in to the KnowBe4 console and go to Users.

All the details of the user are pulled from the User Information page.

The passed due Training details of the user are pulled from the Training page:

The PasswordIQ details are pulled from the PasswordIQ page:

The SecurityCoach details are pulled from the Coaching page:

Performed Actions

To validate the Add User to Group and Remove User from Group actions on KnowBe4, go to Users > Group, and click on the group where you have added or removed the user.

To validate the Enroll in Training, go to Training and click on the training you have performed an action on. Go to the Users section, and there you will see all the users that are currently enrolled in.

To validate the Update Custom Field, go to Users > User Management and click on the user you have performed an action on. Then go to the User Information section, and there you will see all the Custom Fields for the user.

Troubleshooting the KnowBe4 Plugin

Receiving error in the plugin workflow

CRE KnowBe4 [CRE KnowBe4]: Validation error occurred, Received exit code 401, Unauthorized, Verify Base URL and API Token provided in the configuration parameters.

What to do: 

1. Verify the API Token for KnowBe4. Refer to Get your KnowBe4 API tokens.
2. Verify the Base URL for KnowBe4 platform. Refer to prerequisites.

Users are not pulled from KnowBe4

If no data for the User is pulled, it could be due to one of these reasons:

• No User is available on the platform to pull.
• Mapping is not added in the plugin.

What to do:

1. Go to KnowBe4 and check if the Users are available to pull from the Users > User Management page. Or follow the steps.
2. Edit the plugin configuration and check the Entity Source page, there should be some fields mapped in order to pull the same.

Plugin fails to validate or shows an authentication error

If the plugin fails to validate or shows an authentication error, it could be due to one of these reasons:

• The KSAT API Token is invalid or has expired.
• The PasswordIQ or SecurityCoach API Token is invalid and the respective option is selected in Pull Additional Details.
• The Base URL or Custom Region URL does not match the tenant’s KnowBe4 region.

What to do:

1. Verify that the KSAT API Token is valid and was generated from Users > Manage User in the KnowBe4 console. For that follow the steps.
2. If PasswordIQ or SecurityCoach is selected in Pull Additional Details, ensure the corresponding API token was generated from the same section in the respective product’s API settings.
3. Confirm that the Base URL matches the KnowBe4 region for your tenant (like https://training.knowbe4.com for US, or https://eu.knowbe4.com for EU).

Group or training campaign actions fail partway through processing

If a group or training campaign action fails partway through processing, it could be due to one of the following reasons:

• An authentication failure (401/403) was encountered during action execution.
• The Group Action Batch Size is too large, causing a gateway timeout.

What to do:

1. Check the Logging screen in Cloud Exchange for the specific error message to identify whether it is an authentication failure or a timeout.
2. Regenerate the KSAT API Token if authentication failures are reported in the logs.
3. Reduce the Group Action Batch Size configuration parameter (default 50, valid range 1–100) if gateway timeouts are observed for group membership actions.

Getting error while upgrading the plugin to latest version

If you are getting this error while upgrading the plugin to latest version, 

follow these steps to configure the plugin:

1. Click Skip on the update screen.
2. Go to the Risk Exchange > Plugins screen and edit the plugin.
3. Provide the values for all Configuration Parameters, then click Next. Add the Mappings as per the requirement. (Note that the User ID field data type is changed from Number to String, so you need to update the CRE Field data type as well.)
4. Click Save and then enable the plugin.

API calls intermittently hang for 5 minutes before resuming

If API calls such as validate or sync intermittently hang for about 5 minutes before resuming or failing, it could be due to one of these reasons:

• The KnowBe4 regional hostname resolves to multiple IP addresses behind a shared CDN.
• The network firewall silently drops traffic to one or more of the resolved IP addresses, causing the connection to hang until Cloud Exchange’s 5-minute internal timeout is reached.

What to do:

1. Run nslookup <region>.knowbe4.com (for example, nslookup ca.knowbe4.com) from the Cloud Exchange machine.
2. Share all the IP addresses returned by the command with your network/IT team.
3. Ask the network/IT team to verify that all the returned IP addresses are unblocked for outbound access from the Cloud Exchange machine.
4. Unblock any IP addresses that are being blocked by the firewall.

Update Custom Fields action does not update custom field values on the KnowBe4 UI

If the Update Custom Fields action shows as successful in Cloud Exchange but the custom field value is not updated on the KnowBe4 UI, it could be because the user is managed by user provisioning.

• Custom field values can be updated only for users who are not managed by user provisioning.
• For users managed by user provisioning, the KnowBe4 API may return a successful response, so Cloud Exchange shows the action as successful, but the updated value will not be visible on the KnowBe4 UI.

What to do:

1. On the KnowBe4 UI, verify whether the user displays “This User is not managed by user provisioning…”.
2. Run the Update Custom Fields action only for users who are not managed by user provisioning.
3. If the user is managed by user provisioning, update the custom field through the user provisioning system instead.

Additional parameters not available during plugin upgrade

When upgrading the CRE KnowBe4 plugin from version 1.0.0 to 2.0.0 in Cloud Exchange v7.0.0, users can define only the required parameters during the upgrade.

What to do:

To configure additional parameters (like Custom Region URL), edit the plugin after the upgrade from the Risk Exchange > Plugin page.