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:
- Creation of webhooks config
- Creation of third-party integration config
- 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
}
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": ""
}
}
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": ""
}
}
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 acustomAttributes
condition. The custom attributeexternal_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.