1. Oracle Identity Cloud Service REST APIREST API for Oracle Identity Cloud Service
  2. Use Cases
  3. Adaptive Risk Analysis for Custom Client Applications

Adaptive Risk Analysis for Custom Client Applications

Customers moving to the Cloud can leverage Oracle Identity Cloud Service adaptive capabilities to meet risk based analysis for their on-premises access management system, such as Oracle Access Manager (OAM), or client applications.

Oracle Identity Cloud Service provides adaptive REST API interface to enable these on-premises access management systems or client applications to use Oracle Identity Cloud Service risk-based engine to evaluate authentication activities for users.

For example, John Doe is a user in OAM's identity store as well as in Oracle Identity Cloud Service. John accesses a finance application protected by OAM. OAM server redirect him to OAM's loin page for authentication. John Doe submits his credentials and based on the risk score returned by Oracle Identity Cloud Service adaptive risk-based engine, OAM server may challenge the user with a second factor. If the risk score is high, then OAM may deny access to John and present him a message indicating his attempt to log in failed.

The adaptive REST API interface implements 3 use cases in the form of the corresponding endpoints:

  • Populate Risk: /admin/v1/sdk/adaptive/PopulateRisks

  • Fetch Risk Info: /admin/v1/sdk/adaptive/FetchRisks

  • Mitigate Risk: /admin/v1/sdk/adaptive/MitigateRisks

To make REST API calls to these endpoints, your access management system or custom application need an access token from a client credential application registered in Oracle Identity Cloud Service.

Note:

To obtain an access token, see Working with OAuth 2 to Access the REST API.

The adaptive REST API interface requires the client application to send information such as user identification, information of the device the user uses to log in, and client's true IP address.

To gather device information your access management system needs to use a device fingerprint JavaScript file. You can download the device fingerprint JavaScript file from Oracle Identity Cloud Service console.

  1. Sign in to Oracle Identity Cloud Service console as an application administrator.
  2. Expand the Navigation Drawer, click Settings, and then click Downloads.
  3. In the Downloads page, download the Identity Cloud Service Device Fingerprint Utility.

The file you download is a compressed (zip) file. Inside the zip file there is a JavaScript file that the access management system loin page or the client application itself needs to load to collect fingerprint information. Then use the getFingerprint() function to collect user's device fingerprint to send to Oracle Identity Cloud Service's adaptive REST API interface.

See also Enable the Access for an unknown device Event for a Custom Sign-In Page.

Populate Risk

This endpoint is used to submit risk data to Oracle Identity Cloud Service to increase user's risk score.

The cURL command structure is: 
curl -k -X POST 'https://tenant-base-url/admin/v1/sdk/adaptive/PopulateRisks' -H 'Authorization: Bearer <Access_Token>' -H 'Accept:application/json' -d '<Request_Body>'
The following is the structure of the request body for the Populate Risk endpoint. 
{
    "userName": "<User_Name>",
    "data": [
        {
            "name": "device",
            "value": "<result_of_the_devicefingerprint_javascript_file>"
        },
        {
            "name": "client-ip",
            "value": "<ip_address_of_the_user_browser>"
        }
    ],
    "event": "MAX_PASSWORD_FAILED_ATTEMPTS"
}

The event attribute is optional. If not present in the request then all risk events are going to be used to evaluate risk score. You can use MAX_MFA_FAILED_ATTEMPTS or MAX_PASSWORD_FAILED_ATTEMPTS values.

The following is an example of a request body to evaluate risk for John Doe trying to sign in the access management system from the IP address 10.11.12.13. The device fingerprint and IP address will be validate against all enabled risk events in Oracle Identity Cloud Service. 
curl -k -X POST https://tenant-base-url/admin/v1/sdk/adaptive/PopulateRisks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Access_Token>' \
  -d '{
    "userName": "johndoe@example.com",
    "data": [
        {
            "name": "device",
            "value": "{\"currentTime\":\"Wed Nov 13 2019 16:57:34 GMT-0700 (Pacific Daylight Time)\",\"screenWidth\":1920,\"screenHeight\":1080,\"screenColorDepth\":24,\"screenPixelDepth\":24,\"windowPixelRatio\":1,\"language\":\"en-US\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; WOW64; rv:68.0) Gecko/20100101 Firefox/68.0\"}"
        },
        {
            "name": "client-ip",
            "value": "10.11.12.13"
        }
    ]
}'
The following is an example of response body of the populate risk endpoint. 
{
 "userName": "johndoe@example.com",
 "riskLevel": "LOW",
 "riskScores": [
     {
      "lastUpdateTimestamp": "2019-11-12T10:41:57.997Z",
      "score": 15,
      "riskLevel": "LOW",
      "value": "ORACLE_IDCS",
      "status": "ACTIVE",
      "source": "Default Risk Provider",
      "$ref": "https://tenant-base-url/admin/v1/RiskProviderProfiles/ORACLE_IDCS"
     }
 ]
}

Fetch Risk Info

This endpoint enable clients to get current risk information for a single user, multiple users, or for all users in Oracle Identity Cloud Service.

The cURL command structure is: 
curl -k -X POST 'https://tenant-base-url/admin/v1/sdk/adaptive/FetchRisks' -H 'Authorization: Bearer <Access_Token>' -H 'Accept:application/json' -d '<Request_Body>'
The following is the structure of the Request Body for the Fetch Risk Info cURL command. 
{
    "userNames": [
        "<user_name>"
    ]
}
You can call fetch risk info endpoint for multiple users. To do so, use the following request body structure with the cURL command. 
{
    "userNames": [
        "<user_name_1>",
        "<user_name_2>"
    ]
}
If you want to fetch risk info for all users in Oracle Identity Cloud Service, use the following request body structure with the cURL command. 
{}
The following is an example of a request body to fetch risk info for John Doe. 
curl -k -X POST https://tenant-base-url/admin/v1/sdk/adaptive/FetchRisks \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <Access_Token>' \
  -d '{
    "userNames": [
        "johndoe@example.com"
    ]
}'
The following is an example of response body of the fetch risk info endpoint. 
{
  "totalResults": 1,
  "resources": [
     {
      "userName": "johndoe@example.com",
      "riskLevel": "LOW",
      "riskScores": [
         {
           "lastUpdateTimestamp": "2019-11-13T18:41:57.997Z",
           "score": 15,
           "riskLevel": "LOW",
           "value": "ORACLE_IDCS",
           "status": "ACTIVE",
           "source": "Default Risk Provider",
           "$ref": "https://tenant-base-url/admin/v1/RiskProviderProfiles/ORACLE_IDCS"
         }
      ]
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 50
}

Mitigate Risk

This endpoint enable client applications to request mitigation of user's risk score because the user has logged in or reseted password successfully.

The cURL command structure is: 
curl -k -X POST 'https://tenant-base-url/admin/v1/sdk/adaptive/MitigateRisks' -H 'Authorization: Bearer <Access_Token>' -H 'Accept:application/json' -d '<Request_Body>'
The following is the structure of the request body for the Mitigate Risk cURL command. 
{
    "userName": "<User_Name>",
    "data": [
        {
            "name": "device",
            "value": "<result_of_the_devicefingerprint_javascript_file>"
        },
        {
            "name": "client-ip",
            "value": "<ip_address_of_the_user_browser>"
        }
    ],
    "event": "SSO_THREAT_MITIGATION_SUCCESS"
}
The event attribute of the request body can receive multiple values:
  • For successful user login provide SSO_THREAT_MITIGATION_SUCCESS value.
  • For successful user password reset provide ADMIN_ME_PASSWORD_CHANGE_SUCCESS value.
The following is an example of a request body to Mitigate Risk endpoint for John Doe because he successfully logged in the access management system from the IP address 10.11.12.13. 
curl -X POST \
  https://tenant-base-url/admin/v1/sdk/adaptive/MitigateRisks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Access_Token>' \
  -d '{
    "userName": "johndoe@example.com",
    "data": [
        {
            "name": "device",
            "value": "{\"currentTime\":\"Thu Nov 14 2019 10:11:18 GMT-0700 (Pacific Daylight Time)\",\"screenWidth\":1440,\"screenHeight\":900,\"screenColorDepth\":24,\"screenPixelDepth\":24,\"windowPixelRatio\":2,\"language\":\"en-US\",\"userAgent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.81 Safari/537.36\"}"
        },
        {
            "name": "client-ip",
            "value": "10.11.12.13"
        }
    ],
    "event": "SSO_THREAT_MITIGATION_SUCCESS"
}'
The following is an example of response body of the populate risk endpoint: 
{
   "userName": "johndoe@example.com",
   "riskLevel": "LOW",
   "riskScores": [
       {
        "lastUpdateTimestamp": 1574726401582,
        "score": 10,
        "riskLevel": "LOW",
        "providerId": "ORACLE_IDCS",
        "providerStatus": "ACTIVE",
        "providerDescription": "Default Risk Provider",
        "reference": "https://tenant-base-url/admin/v1/RiskProviderProfiles/ORACLE_IDCS"
       }
   ]
}