Adaptive Risk Analysis for Custom Client Applications
Customers moving to the Cloud can leverage IAM identity domain adaptive capabilities to meet risk-based analysis for their on-premises access management system, such as Oracle Access Manager (OAM), or client applications.
Identity domains provide an adaptive REST API interface to enable these on-premises access management systems or client applications to use an identity domain risk-based engine to evaluate authentication activities for users.
For example, John Doe is a user in the OAM identity store and in an identity domain. John accesses a finance application protected by OAM. The OAM server redirects him to the OAM sign-in page for authentication. John Doe submits his credentials and based on the risk score returned by the identity domain adaptive risk-based engine, the 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 sign in failed.
-
Populate Risk:
/admin/v1/sdk/adaptive/PopulateRisks
-
Fetch Risk Info:
/admin/v1/sdk/adaptive/FetchRisks
-
Mitigate Risk:
/admin/v1/sdk/adaptive/MitigateRisks
The adaptive REST API interface requires the client application to send information such as user identification, information of the device the user uses to sign in, and client's true IP address.
To gather device information that your access management system needs to use a device fingerprint JavaScript file. You can download the device fingerprint JavaScript file from the identity domain console.
- Sign in to identity domain Console as an application administrator.
- Expand the Navigation Drawer, click Settings, and then click Downloads.
- 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's a JavaScript file that the access management system sign-in 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 the identity domains 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 an identity domain to increase the user's risk score.
curl -k -X POST 'https://<domainURL>/admin/v1/sdk/adaptive/PopulateRisks'
-H 'Authorization: Bearer <Access_Token>'
-H 'Accept:application/json'
-d '<Request_Body>'
{
"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.
10.11.12.13
. The device fingerprint and IP address will be validated against all enabled risk events in an identity domain. curl -k -X POST https://<domainURL>/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"
}
]
}'
{
"userName": "johndoe@example.com",
"riskLevel": "LOW",
"riskScores": [
{
"lastUpdateTimestamp": "2022-11-12T10:41:57.997Z",
"score": 15,
"riskLevel": "LOW",
"value": "ORACLE_IDCS",
"status": "ACTIVE",
"source": "Default Risk Provider",
"$ref": "https://<domainURL>/admin/v1/RiskProviderProfiles/ORACLE_IDCS"
}
]
}
Fetch Risk Info
This endpoint enables clients to get current risk information for a single user, multiple users, or for all users in an identity domain.
curl -k -X POST 'https://<domainURL>/admin/v1/sdk/adaptive/FetchRisks' -H 'Authorization: Bearer <Access_Token>' -H 'Accept:application/json' -d '<Request_Body>'
{
"userNames": [
"<user_name>"
]
}
{
"userNames": [
"<user_name_1>",
"<user_name_2>"
]
}
{}
curl -k -X POST https://<domainURL>/admin/v1/sdk/adaptive/FetchRisks \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer <Access_Token>' \
-d '{
"userNames": [
"johndoe@example.com"
]
}'
{
"totalResults": 1,
"resources": [
{
"userName": "johndoe@example.com",
"riskLevel": "LOW",
"riskScores": [
{
"lastUpdateTimestamp": "2022-11-13T18:41:57.997Z",
"score": 15,
"riskLevel": "LOW",
"value": "ORACLE_IDCS",
"status": "ACTIVE",
"source": "Default Risk Provider",
"$ref": "https://<domainURL>/admin/v1/RiskProviderProfiles/ORACLE_IDCS"
}
]
}
],
"startIndex": 1,
"itemsPerPage": 50
}
Mitigate Risk
This endpoint enables client applications to request mitigation of a user's risk score because the user has logged in or reset their password successfully.
curl -k -X POST 'https://<domainURL>/admin/v1/sdk/adaptive/MitigateRisks' -H 'Authorization: Bearer <Access_Token>' -H 'Accept:application/json' -d '<Request_Body>'
{
"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"
}
event
attribute of the request body can receive multiple
values:- For successful user sign-in, provide
SSO_THREAT_MITIGATION_SUCCESS
. - For successful user password reset, provide
ADMIN_ME_PASSWORD_CHANGE_SUCCESS
.
10.11.12.13
. curl -X POST \
https://<domainURL>/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"
}'
{
"userName": "johndoe@example.com",
"riskLevel": "LOW",
"riskScores": [
{
"lastUpdateTimestamp": 1574726401582,
"score": 10,
"riskLevel": "LOW",
"providerId": "ORACLE_IDCS",
"providerStatus": "ACTIVE",
"providerDescription": "Default Risk Provider",
"reference": "https://<domainURL>/admin/v1/RiskProviderProfiles/ORACLE_IDCS"
}
]
}