Webhooks

09/2024

Overview

In addition to notification destinations like Microsoft Teams, Slack channels, and email destinations, CII supports webhooks as a target for Failed Check findings.

This article explains how to configure webhooks in CII and provides several basic examples.

Requirements

The following is required to leverage webhooks with CII -

• Moderate familiarity with webhooks (external overview) as a method of platform-to-platform communication

• A platform capable of receiving webhooks and ideally parsing a JSON payload for resulting categorization or desired action(s)

Design Considerations

To successfully leverage CII webhooks, it is best to first fully conceptualize a desired outcome when a user object within the CII platform is flagged for a particular Check.

A basic use case might be:

1. Configure a webhook destination to an automation platform, such as Okta Workflows or a SOAR solution and assign it to a particular CII Check, such as No MFA

2. Once a day, CII will send an event to a webhook with a payload including the list of new users failing this check

3. For each user account in the list, send an email from a specific company-specific email address with instructions for the user to enroll in MFA

The possibilities are endless and very specific to the context of the CII Check upon which you want to take action.

API Authorization

One key design consideration is how the CII webhook communication will authenticate and be authorized to the recipient platform. CII supports the following methods:

• Basic (username and password)

• API Key

• OAuth Client Credentials

Each of these types are explored in more detail in the examples below. The main determining factor here is the type(s) of authorization supported by the target platform.

CII Configuration

To create a webhook notification integration, perform the following steps:

1. Navigate to Integrations -> Add Integration -> Webhooks
2. Provide the following:

   1. Display name

   2. Description (optional)

   3. Webhook URL
3. Choose the appropriate Authorization Type for your webhook integration

   1. Basic - provide the Username and Password, as shown above

   2. API Key - provide the API key name and API key value
   3. OAuth Client Credentials

      1. Enter the Authorization endpoint URL

      2. Select HTTP method - POST, PUT, GET

      3. Enter Client ID and Client secret

      4. Add any necessary OAuth HTTP Parameters - OAuth HTTP parameters are additional credentials used to sign the request to the authorization endpoint to exchange the OAuth Client information for an access token.

4. Add any necessary Invocation HTTP Parameters - Invocation HTTP parameters are additional parameters that can be sent to a webhook and used during request authorization.

5. Click Save

Testing the Webhook Integration

To test the connectivity of the Webhook:

1. On the Integrations page, find the row under Notifications section corresponding to the Webhook notification target you just created

1. Select the Webhook notification target or click 3-dot menu on the righthand side and select Test Connectivity

1. This will send a basic test message to the webhook destination to confirm that connectivity is successful. The contents of the message will be:

{
  "version": "0",
  "id": "abf0607d-3856-b397-5138-0131ec1b63d7",
  "detail-type": "WebhookTest",
  "source": "11111111-2222-3333-4444-555555555555__66666666",
  "account": "000000000000",
  "time": "2023-08-08T13:27:22Z",
  "region": "us-east-2",
  "resources": [],
  "detail": {
    "id": "11111111-2222-3333-4444-555555555555",
    "checkId": "oort-test-check-id",
    "title": "OORT Failing Check Event Test",
    "description": [
      "description1",
      "description2"
    ],
    "recommendedActions": [
      "action1",
      "action2"
    ],
    "severity": "critical",
    "usersFailing": [
      "[e-mail]",
      "[e-mail]"
    ],
    "published": "2023-08-08T13:27:22.416Z"
  }

To test what a custom message for a specific failing check will look like:

1. Go to a specific check page and click Customize Messages

2. Customize the message as desired and select Save

3. Click the Test button for the Webhook Notification Target to send a test message to verify the custom message looks as intended

Enabling Webhook Notifications for Checks

When the webhook integration is created, it is not assigned to any check notifications by default. Nothing will be sent via the webhook until it is enabled in the desired Oort Check(s).

To enable it, navigate to the desired Check details page and expand the dropdown on the top-right corner of the page.

Check the box of the webhook that you would like enabled for this check.

Note that on the main Checks page, there is a Run Checks Now button in the top right corner. This will re-analyze the existing data set and any new Checks insights will trigger new notifications to any of the connected notification targets.

New Features

2024.09.19

CII has added `checkTags` to the webhook event payload. This allows organizations to add custom tags to specific checks (see below), and then pass these through the events to their webhook destination for further automation or classification.

Example Event Payload

An example of the payload for new users failing a check would look as follows:

{
  "version": "0",
  "id": "dcce9254-2047-1bf2-a7d8-0a511133e8dc",
  "detail-type": "FAILED_CHECK",
  "source": "5b04504c-bd5c-43a4-b1a2-5096f9c7974f__aa06caa6",
  "account": "227542035969",
  "time": "2024-09-15T13:38:34Z",
  "region": "us-east-2",
  "resources": [],
  "detail": {
    "id": "e02da5c7-e96f-4d9b-bfda-de514fdd145b",
    "checkId": "unmanaged-devices-access",
    "title": "Unmanaged Devices Access",
    "description": [
      "Detects users logging in from an unmanaged device in the last {{numberOfDays}} days.",
      "For closer inspection, Identity Intelligence will give an indication of the event, IP address, if the device was managed."
    ],
    "recommendedActions": [
      "We recommend directly alerting the users to recommend using their managed devices. If the behavior persists, consider alerting their manager."
    ],
    "severity": "low",
    "usersFailing": [
      "[e-mail]",
      "[e-mail]"
    ],
    "failingUsersByProvider": {
      "AZURE_AD::Demo Azure AD": [
        "[e-mail]",
        "[e-mail]"
      ]
    },
    "checkTags": [
      "demo1",
      "demo2"
    ],
    "loginDetails": [
      {
        "login": "[e-mail]",
        "details": [
          {
            "value": "UNKNOWN",
            "key": "userLevelOfTrust"
          },
          {
            "value": "[\"providerFailingCheck-unmanaged-devices-access-5b04504c-bd5c-43a4-b1a2-5096f9c7974f__AZURE_AD__d2f6affb\"]",
            "key": "providersFailingChecks"
          },
          {
            "value": "[{\"deviceDisplayName\":\"EUCZ4627ABC\",\"deviceId\":\"c791f68b-7580-4918-a257-212eabed9123\",\"ipAddress\":\"3.21.2.5\"},{\"deviceDisplayName\":\"EUCZ4627ABC\",\"deviceId\":\"c791f68b-7580-4918-a257-212eabed9123\",\"ipAddress\":\"31.209.149.121\"},{\"deviceDisplayName\":\"EUCZ4627ABC\",\"deviceId\":\"c791f68b-7580-4918-a257-212eabed9123\",\"ipAddress\":\"85.220.34.189\"},{\"deviceDisplayName\":\"EUCZ4627BC3\",\"deviceId\":\"c791f68b-7580-4918-a257-212eabed9d3b\",\"ipAddress\":\"32.120.207.5\"}]",
            "key": "deviceDetails"
          }
        ]
      },
      {
        "login": "[e-mail]",
        "details": [
          {
            "value": "hr operations specialist",
            "key": "userTitle"
          },
          {
            "value": "UNKNOWN",
            "key": "userLevelOfTrust"
          },
          {
            "value": "[\"providerFailingCheck-unmanaged-devices-access-5b04504c-bd5c-43a4-b1a2-5096f9c7974f__AZURE_AD__d2f6affb\"]",
            "key": "providersFailingChecks"
          },
          {
            "value": "[{\"deviceDisplayName\":\"EUCZ4627ABCD\",\"deviceId\":\"c791f68b-7580-4918-a257-212eabed9124\",\"ipAddress\":\"31.209.149.121\"}]",
            "key": "deviceDetails"
          }
        ]
      }
    ],
    "published": "2024-09-15T13:38:34.712Z"
  }
}

In most cases, the receiving platform will need to do some level of parsing of this content, unless the intent is simply to store the information in a 3rd party SIEM or security data lake. (Note that CII has direct integrations for Azure Sentinel or Snowflake security data lakes.)

Direct Message payload example

An example of the payload for a direct message to a specific end user, or the end user's manager, who is failing a check would look as follows:

      {
        recipient: recipientEmail,
        checkId: checkMetadata.id,
        title: checkMetadata.title,
        severity: checkMetadata.severity,
        directMessage,
        referenceVideoUrls: WizerVideoUrl
      }