Third-party risk API contract

Edit online

When the user's application evaluation request comes to IBM® Verify, the internal component inside the access policy framework evaluates the access policy object that is attached to the application. Then, it creates a payload toward third-party integration through the real-time webhooks.

Access policy webhooks request model

The access policy framework reads the enabled value for the config node. If the value is false, it skips the rule's processing, and does NOT invoke the third-party integration. Otherwise, the access policy rule is processed and the config node is processed.

Based on the evaluationOutboundAttributes defined in the config node, the internal Verify component sends the following data to the third party through the webhooks. That way it can get the risk, or their supported attribute values from their risk engine.

A sample of the data model, which Verify sends to the third party (through the webhooks internal API):

{
    "sessionContext": {
       ...
    },
    "attributeContext" :{
       ...
    },
    "policyContext" :{
       ...
    },
    "adaptiveContext" : {
        ...
    },
    "customAttributes" :  { 
        "customAttributeId1" : ["value"], 
        .. 
    },
    authnMethods : [...] 
}

Access policy framework for webhooks request details


Element	Description
Payload type	JSON object that represents request model.
`sessionContext`	The user's subject attributes that are available inside Verify.
`attributeContext`	The user's context attributes that are available inside Verify.
`policyContext`	The access policy object attributes that are available inside Verify.
`adaptiveContext`	The user's adaptive session attributes that are available inside Verify.
`customAttributes`	The map of custom attributes IDs and list of values. They represent the custom attributes that are available for the Verify tenant. The custom attributes that are sent to the third party are derived from the list of `customAttributes` IDs that are specified as part of the third-party integration configuration.
`authnMethods`	Verify known authentication factors defined in the access policy object that is being evaluated.

Webhooks for access policy response models

During the access policy object evaluation, after the Verify internal component sends the data payload to the third party through the webhooks, it receives the response from the third-party integration. The response includes version, supported attributes, key value pairs, and the result.

The response data model, which Verify receives from the third-party integration:

{
    "version" :"some version",
    "result": { 
        "action" : "any one of the Verify access policy actions.",
        "message" : "Reason why this decision was returned.",
        "authnMethods" : ["List of Verify authentication factors which the third party requires the user to complete. It must be the same, or a subset of the authnMethods sent to the third party via webhooks in the request."],
        "redirectURI" : "Verify relative or absolute URL to redirect the browser when additional information is required." 
    },
    "attributes": {
        "attrName1" : "value",
        "attrNameN" : "value",
    },
}

Webhooks access policy response details


Element	Description
Payload type	JSON object that represents response model.
HTTP status code	See HTTP Status Code.
`version`	Optional- Represents the third-party integration response version.
`result`	Optional- Represents the third-party integration result. The third party can return a response with no result block and can return only their supported `attributes`. If the result object is present, then it must contain the `decision` field.
`result.decision`	Mandatory- Represents the third-party integration decision and its value can contain one of the ISV access policy actions. The valid values are `ACTION_DENY, ACTION_ALLOW, ACTION_MFA_ALWAYS, ACTION_MFA_PER_SESSION, ACTION_DENY_OVERRIDE, ACTION_MFA_OVERRIDE, ACTION_ALLOW_OVERRIDE, ACTION_DENY_AND_REDIRECT, ACTION_REDIRECT and ACTION_CONTINUE`.
`result.message`	Optional- Represents the third-party integration reason/message that why this `action` was returned.
`result.authnMethods`	Optional- ["List of ISV authentication factors that the third party requires the user to complete. It must be the same, or a subset of the authnMethods sent to the third party through webhooks in the request."]
`result.redirectURI`	Optional- Represents the endpoint that the browser must be redirected to in the case of ACTION_REDIRECT/ACTION_DENY_AND_REDIRECT or recoverable error flow. The query string parameter that is sent to the browser as a result of a redirect variant response has a Target. The client must be directed back to the Target after their required interaction with the client browser is completed.
`attributes`	Optional- Represents the attributes (hash map) supported by the third-party integration.