Document toolboxDocument toolbox

securityData

The securityData API is used to get additional information about a BankID transaction related to preventing fraud.

Please not that securityData is currently only available for issuer banks. This may be changed in a future release.


Overview

URLhttps://<fraud-data-baseurl>/securityData/<tid>
Request

GET with URL path parameter tid for the authentication session is question (Transaction ID from the ID Token)

AuthenticationAccess Token as Bearer Token in Authorization Header
Response
202AcceptedA new process for retrieval of fraud data for tid  is accepted
204No ContentA process for retrieval of fraud data for tid  is still ongoing (not yet completed)
200OKA process for retrieval of fraud data for tid has completed. The body contains a JSON with fraud data response elements.
400Bad requestThe tid value does not correspond to a session associated with the requesting OIDC client
401Unauthorized Bearer token is missing or not accepted for any reason
403ForbiddenBearer token has insufficient scope
404Not foundThe tid  is an unknown value for the OIDC Provider.
410GoneFraud data for tid is no longer available
429Too many requests The fraud data service is currently too busy to serve the request
500Internal server error Any other error condition

Error responses contains further information on the reason according to standard.

ExampleSee below

This method provides data (security data / fraud data) that can be used for risk scoring on a recent authentication session via the OIDC Provider. The  tid claim from the ID Token works as the reference to the session in question. At first invocation of this method for a given tid, the Fraud Data service starts a process to retrieve all relevant data for the transaction in question. When all available fraud data for the given transaction has been retrieved, the set of available data may be returned to the requesting OIDC Client upon request. The typical usage pattern for an OIDC Client is to receive a 202 in response to the initial request, followed by one or more 204 responses on subsequent polling requests, before the service eventually responds with a 200 along with the actual fraud data in the body. 

The Fraud Data service is classified as a near-realtime service. Retrieval of a full set of fraud data may take up to 10 seconds to complete. After completion fraud data will be available for an extended time period of 3600 seconds. The polling interval while waiting for data should not be more frequent that once every 1-5 seconds.

Response elements

The set of fraud data is returned as JSON containing supported fraud data claims for the Identity Provider in question. The following table shows a selection of the supported claims in response from the fraud-data service. A complete list of supported claims are not included in this documentation for security reasons. Documentation on all supported claims can be provided upon request. Note that a distinction is made between raw data and derived data about the transaction in question.


Claim ExampleSupported IDPDescriptionComment
tid754a1771-8f6a-4fa5-b6d7-47d81dda493dAnyTransaction ID
transaction_data
{...}
AnyList of key-value pairs with raw data about the transaction
transaction_data:BankID_browserNameChromeBankID netcentricUser-Agent name from the end-user device
transaction_data:BankID_timeZoneEurope/OsloBankID netcentric Default time-zone from the end-user device
transaction_data:BankID_osNameLinuxBankID netcentric Operating system on the end-user device
transaction_data:BankID_osVersion UnknownBankID netcentric Operating system version on the end-user device
transaction_data:BankID_userAgent Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36BankID netcentric  User-Agent string from the end-user device
transaction_data:BankID_language\"en-US\"BankID netcentricDefault langue setting from the end-user device
derived_data{...}Any List of key-value pairs with derived data about the transaction
derived_data:BankID_User_IP
195.18.161.2
BankID netcentric IP address from which the traffic from the end-user device come.
derived_data:BankID_Alarm_IDxNo alarmsBankID netcentric List of defined IDx alarms that are triggered for the transaction in question (ID2, ID3, ID4m ID5m ID6, ID8).
derived_data:BankID_fpf 0BankID netcentric 

Foul Play Factor risk score (0-1). Is an aggregate/composite risk score indicating how suspicious a transaction is considered to be. The threshold may vary as the raw data and relative weighting are subject to continuous analysis and adjustment.


derived_data:BankID_fpf_classificationUnknownBankID netcentricTraffic light classification of Foul Play Factor risk score (Green, Yellow, Red, Unknown).
derived_data:BankID_env 0BankID netcentric  Environment risk score (0-1). Indicates to which extent the transaction is from an environment that the user has used before. The environment is a composite of information relating to the device used, geographic location etc. The closer the score is to 1, the more unknown the environment is for the user.
derived_data:BankID_env_classificationUnknownBankID netcentric  

Traffic light classification of Environment risk score (Green, Yellow, Red, Unknown).


derived_data:BankID_irs 0BankID netcentricInfection risk score (0-1). Indicates that data from the end-user device is not as expected. This could be because the device has been infected by a banking trojan or crapware, in the form of html injects or overloaded built-in functions.
derived_data:BankID_irs_classificationUnknownBankID netcentricTraffic light classification of Infection risk score (Green, Yellow, Red, Unknown).
derived_data:BankID_dms 0BankID netcentricData manipulation risk score (0-1). Indicates that data from the end-user device is not as expected. This could be because a deliberate attempt has been made to manipulate parameter values.
derived_data:BankID_dms_classificationUnknownBankID netcentricTraffic light classification of Data manipulation risk score (Green, Yellow, Red, Unknown).
derived_data:BankID_ips 0BankID netcentricIP address risk score (0-1). Based on previous traffic observed from this IP address. It is strongly recommended that if the corresponding classification is Red, all transactions from this IP address the last 3 hours (or more) should be investigated.
derived_data:BankID_ips_classificationUnknownBankID netcentricTraffic light classification of IP address risk score (Green, Yellow, Red, Unknown).


Example

The following is an example for a request to the Fraud Data service for a given tid value

seurityData request
TBC

The following is a truncated JSON example from the response from the Fraud Data service for an authentication session with BankID netcentric. A complete JSON example is not included in this documentation for security reasons. A complete example can be provided upon request.

seurityData JSON response
{
  "tid": "754a1771-8f6a-4fa5-b6d7-47d81dda493d",
  "transaction_data": {
    ...
    "BankID_browserName": "Chrome",
    "BankID_timeZone": "Europe/Oslo",
    "BankID_osName": "Linux",
    "BankID_osVersion": "Unknown",
    "BankID_userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36",
    "BankID_language": "\"en-US\"",
	...
   },
  "derived_data": {
	...
    "BankID_User_IP": "195.18.161.2",
    "BankID_Alarm_IDx": "No alarms",
    "BankID_fpf": "0",
    "BankID_fpf_classification": "Unknown",
    "BankID_env": "0",
    "BankID_env_classification": "Unknown",
    "BankID_irs": "0",
    "BankID_irs_classification": "Unknown",
    "BankID_dms": "0",
    "BankID_dms_classification": "Unknown",
    "BankID_ips": "0",
    "BankID_ips_classification": "Unknown",
	...
  }
}