Evaluating risk
This section describes how to call the OIP Risk Management Policy Manager from your back-end to evaluate a risk. In other words, it focuses on the exchanges 4 to 5 of this use case.
Prerequisite
The communication with OIP Risk Management is realised through an API which serves both management and operational purposes.
This REST API is secured with JSON Web Token (JWT) authentication [RFC7519]. It is assumed that the clients of this API are capable of issuing valid JWT tokens.
JWT tokens may be obtained by requesting them from an Identity Provider (such as Keycloak) or created manually. In both cases, the public key to be used for the signature verification has to be provisioned in the OIP Risk Management back-end.
In the case where no Identity Provider is available, then the following section describes how to generate an RSA key pair that can be used to issue and verify JWT tokens.
Prerequisite
Click Authorisation token to know more.
Note
Click here for an introduction on how policies are configured to return the decisions.
Evaluate risk
Click here to know more on Request Parameters and Response Message for Evaluate_Risk.
Response example
HTTP/1.1 200
status: 201
Date: Thu, 20 Dec 2018 15:53:22 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: XXX
{
"risk": {
"status": "SUCCESS",
"decision": { "access": "allowed", "auth": [ { "type": "otp" } ] },
"decisionDetails": {
"gemaltoRiskEngine": [
{
"rulesetExternalId": "ruleset_1",
"rulename": "true",
"ruleExpectedValue": true,
"result": {
"device new": "false",
"network anonymous": "false",
"device recurring 1hour 1x": "false",
"device recurring 1hour 2x": "false",
"device recurring 1hour 3x": "false",
"device recurring 1hour 5x": "false",
"device recurring 1hour 10x": "false",
"device recurring 1day 1x": "false",
"device recurring 1day 2x": "false",
"device recurring 1day 3x": "false",
"device recurring 1day 5x": "false",
"device recurring 1day 10x": "false",
"device recurring 1week 1x": "false",
"device recurring 1week 2x": "false",
"device recurring 1week 3x": "false",
"device recurring 1week 5x": "false",
"device recurring 1week 10x": "false",
"device recurring 1month 1x": "false",
"device recurring 1month 2x": "false",
"device recurring 1month 3x": "false",
"device recurring 1month 5x": "false",
"device recurring 1month 10x": "false",
"device recurring 6month 1x": "false",
"device recurring 6month 2x": "false",
"device recurring 6month 3x": "false",
"device recurring 6month 5x": "false",
"device recurring 6month 10x": "false",
"network tor": "false",
"device rooted": "unknown",
"country changed 1hour": "unknown",
"country changed": "unknown",
"country changed 6hour": "unknown",
"country changed 1month": "unknown",
"country changed 12hour": "unknown",
"country changed 1day": "unknown",
"country changed 1week": "unknown",
"ip address is private": "false",
"ip address is class a - large": "false",
"ip address is class d - multicast": "false",
"ip address is class b - medium": "false",
"ip address is class c - small": "false",
"ip address is reserved": "false",
"ip address is class e - future": "false",
"true": "true"
},
"attributes": {
"deviceBrowser": {
"networkIp": "1.0.0.1",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:69.0) Gecko/20100101 Firefox/69.0",
"browserName": "firefox",
"browserVersion": "69.0",
"osName": "windows",
"osVersion": "7",
"osFamily": "Windows",
"osVersionOfFamily": "7",
"osReleaseDateOrder": 3,
"screenWidth": 1920,
"screenHeight": 1080
},
"ipintelligence": {
"continent": "europe",
"country": "france",
"country_code": "fr",
"country_cf": 99,
"region": "ile-de-france",
"state": "seine-saint-denis",
"state_cf": "80",
"city": "la plaine-saint-denis",
"city_cf": "61",
"postal_code": "12345",
"time_zone": "1",
"latitude": "11.2222",
"longitude": "1.2222",
"connection_type": "tx",
"line_speed": "high",
"ip_routing_type": "fixed",
"asn": "123",
"organization": "proxy",
"carrier": "carrier",
"hosting_facility": "true",
"ip_address": "1.0.0.1"
}
}
},
{
"rulesetExternalId": "ruleset_2",
"rulename": "true",
"ruleExpectedValue": true,
"result": {
"browser firefox": "true",
"browser ie": "false",
"browser chrome": "false",
"browser edge": "false",
"browser opera": "false",
"browser safari": "false",
"browser android": "false",
"os windows": "true",
"os mac": "false",
"os linux": "false",
"os android": "false",
"os ios": "false",
"region eu6": "true",
"continent europe": "true",
"continent north america": "false",
"continent oceania": "false",
"continent south america": "false",
"continent asia": "false",
"continent africa": "false",
"continent antartica": "false",
"screen resolution svga+": "true",
"screen resolution hd+": "true",
"screen resolution cga+": "true",
"true": "true"
},
"attributes": {
"deviceBrowser": {
"networkIp": "1.0.0.1",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:69.0) Gecko/20100101 Firefox/69.0",
"browserName": "firefox",
"browserVersion": "69.0",
"osName": "windows",
"osVersion": "7",
"osFamily": "Windows",
"osVersionOfFamily": "7",
"osReleaseDateOrder": 3,
"screenWidth": 1920,
"screenHeight": 1080
},
"ipintelligence": {
"continent": "europe",
"country": "france",
"country_code": "fr",
"country_cf": 99,
"region": "ile-de-france",
"state": "seine-saint-denis",
"state_cf": "80",
"city": "la plaine-saint-denis",
"city_cf": "61",
"postal_code": "12345",
"time_zone": "1",
"latitude": "11.2222",
"longitude": "1.2222",
"connection_type": "tx",
"line_speed": "high",
"ip_routing_type": "fixed",
"asn": "123",
"organization": "company",
"carrier": "company",
"hosting_facility": "true",
"ip_address": "1.0.0.1"
}
}
}
],
"threatmetrix": [
{
"policyName": "default_pilot",
"result": {
"api_call_datetime": "2019-10-22 16:00:14.305",
"api_version": "10.5",
"digital_id_result": "not_enough_attribs",
"event_datetime": "2019-10-22 16:00:14.305",
"event_type": "login",
"input_ip_activities": "_AUTH_PASSED",
"input_ip_address": "1.0.0.1",
"input_ip_assert_history": "NEGATIVE_HISTORY",
"input_ip_attributes": [
"_AUTH_PASSED",
"_CHALLENGED",
"_LOCK",
"_WATCH",
"_LOGIN_FAILED",
"_LOGIN_PASSED"
],
"input_ip_city": "la plaine-saint-denis",
"input_ip_connection_type": "tx",
"input_ip_first_seen": "2019-03-15",
"input_ip_geo": "FR",
"input_ip_home": "no",
"input_ip_hosting_facility": "true",
"input_ip_isp": "company",
"input_ip_last_event": "2019-10-22",
"input_ip_last_update": "2019-10-22",
"input_ip_latitude": "11.2222",
"input_ip_line_speed": "high",
"input_ip_longitude": "1.22222",
"input_ip_organization": "company",
"input_ip_postal_code": "12345",
"input_ip_region": "seine-saint-denis",
"input_ip_result": "success",
"input_ip_routing_type": "fixed",
"input_ip_score": "25",
"input_ip_worst_score": "-28",
"org_id": "2rj4semg",
"policy": "default_pilot",
"policy_details_api": "{\"policy_detail_api\":[{\"type\":\"champion\",\"id\":\"0\",\"customer\":{\"score\":\"-34\",\"pvid\":\"1000006802\",\"review_status\":\"reject\",\"risk_rating\":\"high\",\"rules\":[{\"rid\":\"1003162364\",\"reason_code\":\"true\",\"score\":\"0\"},{\"rid\":\"1003162367\",\"reason_code\":\"Profiling Failed\",\"score\":\"-30\"},{\"rid\":\"1003162396\",\"reason_code\":\"IP Missing\",\"score\":\"-1\"},{\"rid\":\"1003162402\",\"reason_code\":\"Cloud_Security_Layer\",\"score\":\"0\"},{\"rid\":\"1003162443\",\"reason_code\":\"Auth_Pass Any 1x 15month\",\"score\":\"0\"},{\"rid\":\"1003163062\",\"reason_code\":\"Value Medium\",\"score\":\"0\"},{\"rid\":\"1003163064\",\"reason_code\":\"Device ID Missing\",\"score\":\"0\"},{\"rid\":\"1003163164\",\"reason_code\":\"Browser Other\",\"score\":\"-2\"},{\"rid\":\"1003163172\",\"reason_code\":\"Resolution Other\",\"score\":\"-1\"}]}}]}",
"policy_score": "-34",
"primary_industry": "banking",
"reason_code": [
"true",
"Profiling Failed",
"IP Missing",
"Cloud_Security_Layer",
"Auth_Pass Any 1x 15month",
"Value Medium",
"Device ID Missing",
"Browser Other",
"Resolution Other"
],
"request_duration": "15",
"request_id": "e8f138a3-2309-4233-b90e-829df840f8b7",
"request_result": "success",
"review_status": "reject",
"risk_rating": "high",
"secondary_industry": "retail",
"service_type": "session-policy",
"session_id": "a43bb82e-0d15-4629-92b1-8208c9117f9e",
"session_id_query_count": "2",
"summary_risk_score": "-34",
"tmx_reason_code": [
"_IP_GBL_VEL_10_88_120_120",
"_IP_GBL_AGE_GT_3MTHS",
"_IP_LCL_AGE_GT_3MTHS",
"_EXPRESSION_ERROR",
"_InputIP_Org_Global_Whitelist",
"_InputIP_ISP_Global_Whitelist",
"_Cloud_Security_Layer",
"_TMX_GBL_TT_LIMIT_REACHED_INPUT_IP_ADDRESS",
"_TMX_GBL_PDB_LIMIT_REACHED_INPUT_IP_ADDRESS"
],
"tmx_risk_rating": "neutral",
"unknown_session": "yes"
}
}
]
},
"policy": {
"id": "fdeba170-1d63-36e7-f36f-844c31b3003e",
"name": "test1",
"scenario": {
"id": "0011c00d-b48b-b82c-4a66-1d394b64ff67",
"name": "step1"
}
}
}
}
