Getting started with enabling third-party assessment

To integrate the IBM® Security Verify and the third-party risk assessment, the Verify admin needs to configure following components and frameworks:

  1. Creation of webhooks config
  2. Creation of third-party integration config
  3. Creation of access policy object along with third-party risk API contract

Creating webhooks config

A realtime webhook configuration must be associated with a third-party risk provider. The realtime webhook provides the technical run-time integration between Verify and the third-party risk provider service. Realtime webhook configuration must be completed before the third-party risk can be computed.

A fictitious realtime webhook config that might support the third-party risk provider:

{
  "name": "some name",
  "type": "realtime",
  "urls": [
    "https://somedomain.com/1351/app_proxy/api/risk"
  ],
  "authentication": {
    "header": {
      "values": [
        {
          "key": "SEC",
          "value": "some-value"
        }
      ]
    },
    "type": "header"
  }
  "purpose": [
    "external_risk"
  ],
  "notification": null
}
Note: If the third-party integration fails to provide the response in the format Verify expects, it might implement a mediator service or API gateway for simple conversion, or use webhooks transforms. For webhooks transforms, see webhooks configuration API reference.

Creating the third-party integration config

For every third-party risk integration, a config needs to be created. This config object identifies the webhooks that are used (webhook ID) and Verify internal attributes. The Verify internal components must send to the third party for the assessment (through realtime webhooks).

The Access policy framework provides a set of APIs, which allows creation and management of this config.

POST '/integrations/v1.0/config' \
'Content-Type: application/json' \
'Accept: application/json' \

{
        "WebhookId": "some-Webhook-id",
        "name": "some third party integration",
        "version": 1,
        "evaluationOutboundAttributes": {
            "sessionContext": {
                ...
            },
            "attributeContext": {
                ...
            },
            "policyContext": {
                ...
            },
            "adaptiveContext": {
                ...
            }
        },
        "supportedAttributes": [],
        "integrationProcessingEndpoint": {
            "redirectUri": ""
        }
}
Integration config request details
Element Description
HTTP Request POST.
HTTP Header - Content-Type The content type of the request payload is always application/json.
HTTP Header - Accept The content type that is expected of the response payload is always application/json.
Payload JSON object that represents the third-party integration config.
WebhookId Mandatory: The unique identifier of the realtime webhook used while it creates the third-party provider.
name Mandatory: The name of this config object.
version Version for the config object.
evaluationOutboundAttributes Optional: This object represents what Verify data needs to be passed to the third-party risk integration available from the relevant context objects, currently SessionContext (SubjectContext), AttributeContext, AdaptiveContext, or PolicyContext.
supportedAttributes Optional: Represents the attributes that this third-party integration provides values for. During the webhook orchestration, a new Fixed value attribute is created to represent the returned attribute. The Fixed value attribute can be configured with a predefined value that can be updated. If a webhooks invocation fails, or that attribute is not returned in a webhooks response despite the API contract, the Verify internal component responsible for the attributes management can be called in the same way as the custom attributes are populated at run-time to get the preconfigured value. Create the enrichment attribute placeholder (including a default value if some exception occurs) if you are using the attributes that are supported by the 3rd party integration. See Attribute management API reference..

A sample integration config response payload:

{
        "id" : "config-id"
        "WebhookId": "some-Webhook-id",
        "referenceId": "reference-id",
        "created": "created timestamp",
        "name": "some third  integration",
        "version": 1,
        "evaluationOutboundAttributes": {
            "sessionContext": {
                ...
            },
            "attributeContext": {
                ...
            },
            "policyContext": {
                ...
            },
            "adaptiveContext": {
                ...
            }
        },
        "supportedAttributes": [],
        "integrationProcessingEndpoint": {
            "redirectUri": ""
        }
}
Integration config response details
Element Description
Payload type JSON object that represents third-party integration config.
HTTP status code 201-Created (success), 400-Bad Response, 403-Forbidden, 500-Internal server Error
id Mandatory: Represents the unique ID for this config object.
referenceId Mandatory: Represents the reference ID that is used by Verify internal components in communicating with the webhooks.
created Mandatory: Represents the timestamp when this config object was created.
WebhookId Mandatory: The unique identifier of the realtime webhook that is used while it is creating the third-party provider.
name Mandatory: The name of this config object
version Optional: Version for the config object.
evaluationOutboundAttributes Optional: If the original requests were sent with them.
supportedAttributes Optional: If the original requests were sent with them.
integrationProcessingEndpoint If the original requests were sent with them.

See Risk Management configuration API reference for details.

A fictitious third-party config object:

{
    "WebhookId": "some-Webhook-id",
    "name": "some third party integration",
    "version": 1,
    "evaluationOutboundAttributes": {
        "sessionContext": {
            "uid": true,
            "groupIds": false
        },
        "attributeContext": {
            "appId": false,
            "ipAddress": true
        },
        "policyContext": {
            "id": true,
            "policyName": true
        },
        "adaptiveContext": {
            "city": true
        }
    },
    "supportedAttributes": [],
    "integrationProcessingEndpoint": {
        "redirectUri": ""
    }
}

Creating an access policy object

Access Policy framework in Verify provides a mechanism by which the Verify internal components can compute the external risk from the third-party provider. The Verify internal components evaluate this access policy object and refers to the third-party integration config created in Step two to send data to the third-party integration (through realtime webhooks). That way external risk or attributes enrichment can take place.

The format for enabling the third-party risk integration inside the access policy object:

{
      "name": "3rd Party Risk Evaluation",
      "alwaysRun": true,
      "conditions": [ {
        "type":"integrationAttributes":,
        "id" : "<configId>"
        }]
      },
      "result": {
        "action": "ACTION_MFA_ALWAYS",
        "serverSideActions": {[]},
        "authnMethods": <["urn:ibm:security:authentication:asf:macotp"]> or <["smsotp", "emailotp", ....]>
      }
    }
Condition Attribute Description
ID 3rd party integrationconfigId 3rd party integration configId, see Creating the third party integration Config.
result Verify risk assessment result if an error is encountered from realtime webhooks.
authnMethods Verify authentication factors.

See the Access and Risk Policies API for policy creation and management.

An example of access policy object that has third-party integration condition:

{
    "name": "3rd Party Integration via webhooks",
    "description": "",
    "rules": [
        {
            "id": "1",
            "name": "3rd party provider",
            "alwaysRun": true,
            "firstFactor": false,
            "conditions": [
                {
                    "type": "integrationAttributes",
                    "id": "16a1f2fb-c43f-4a0e-b294-1b25a87a9546"
                }
            ],
            "result": {
                "action": "ACTION_ALLOW",
                "serverSideActions": [],
                "authnMethods": [
                    "urn:ibm:security:authentication:asf:macotp"
                ]
            }
        },
        {
            "id": "1634292657617",
            "name": "Colour Severity",
            "description": "",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [
                {
                    "type": "customAttributes",
                    "customAttributes": [
                        {
                            "name": "external_risk_score",
                            "opCode": "EQ",
                            "values": [
                                "4"
                            ]
                        }
                    ],
                    "firstFactor": false
                }
            ],
            "result": {
                "action": "ACTION_DENY",
                "serverSideActions": [],
                "authnMethods": []
            }
        },
        {
            "id": "1634292240488",
            "name": "Default rule",
            "description": "",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [],
            "result": {
                "action": "ACTION_ALLOW",
                "serverSideActions": [],
                "authnMethods": [
                    "urn:ibm:security:authentication:asf:macotp"
                ]
            }
        }
    ],
    "meta": {
        "label": "initial policy",
        "state": "ACTIVE",
        "scope": [
            "developers"
        ],
        "schema": "urn:access:policy:5.0:schema",
        "enforcementType": "fedSSO"
    }
}
  • This access policy object shows a third-party risk integration whose config is identified by the field id.
  • Apart from integrationAttributes, the policy also has a customAttributes condition. The custom attribute external_risk_score is the attribute whose value is provided by the 3rd party risk integration.

After the access policy object is created, attach it to the wanted user application.