1. Administering Oracle Identity Cloud Service
  2. Configure Security Settings
  3. Use Device Fingerprints

36 Use Device Fingerprints

You can use information collected about the user system to maintain a fingerprint which can be used to identify the end user system uniquely.

Topics:

About Device Fingerprints

Information about the device used by an end user is collected and a hash value is generated. This allows the end user system to be uniquely identified.

Enable Device Fingerprints. This is Standard License feature. To learn about these features, see Standard License Tier Features for Oracle Identity Cloud Service.

A user's device can be identified uniquely by collecting details of the device and encrypting them to create a fingerprint hash value.

The login calls either from the default Oracle Identity Cloud Service sign-in page or from custom UI sign-in page are modified to send device detail attributes. If any of the attributes are missing from the device details sent to SSO, a value of null will be used when the fingerprint hash is generated.

Device Fingerprints and Custom Sign In Pages

Learn how to use device fingerprints with custom sign in pages.

Note:

This is only for the case of custom login pages. If you are using the default login page, device fingerprinting works after you enable it.

For a full description about collecting device details and adding the details in a custom log in page, see Enable the 'Access for an unknown device' Event for a Custom Sign-In Page.

The device fingerprint is stored in a cookie as part of the SSO request. If the device fingerprint value is already present in the persistent cookie, the value will be used across the flow for auditing. If the device fingerprint value is not present in the persistent cookie, a new device fingerprint hash value is created based on the device details sent in login request to SSO. The use cases below show the state of the cookie the first time a user logs in using a custom sign in page, and then on subsequent logins.

An alternative way of using device fingerprints with custom sign in pages is described in Enable the 'Access for an unknown device' Event for a Custom Sign-In Page.

Use Case: First time login using custom sign in page

The first time login use case is the scenario where there is no device fingerprint value of the end user in the cookie at end user browser or with custom UI. In this case, the request payload to /sso/v1/sdk/authenticate authN api carries device attributes. SSO processes these device attributes in order to calculate device fingerprint hash value and it sends this value in the response payload.

Request payload:

{
    "op":"credSubmit",
    "credentials": 
	{
        "username" : "testUser",
        "password": "Welcome@1",
        "device": 
		"
            {
            \"screenWidth\":null,\"screenHeight\":900,\"screenPixelDepth\":\"24\",
			\"windowPixelRatio\":2,\"language\":\"en-GB\",\"userAgent\":\"Mozilla 5.0 (Macintosh;
			Intel Mac OS X 10_13_6) AppleWebKit 537.36 (KHTML, like Gecko) Chrome 85.0.4183.102 
			Safari 537.36\",\"plugins\":\"3\",\"timeZone\":-330
		    }
        "
    },

    "requestState": "requestState"
}

In case of AuthN SDK, the custom UI application might have access to more end user information. In this case, the application can send these additional device details in the request payload to authN api in addition to the other device attributes.

However, it is suggested that the additional values are provided in string format in the request payload. For example, if the custom UI has access to the location of the end user, the additional detail "location":"Hyd" can be sent as part of the device details.

Response payload:

{
	"authnToken": "....",
	"status": "success",
	"ecId": "6cjO20H1000000000",
	"deviceFingerPrint": "db68d19334304e2624ca217de1196d30e9150335e0bd7b6072c44a0841073a79"
}

Use Case: Logins using a custom sign in page after the first time

Logins after the first time are represented by this use case, where device fingerprint is already present in the cookie at end user browser or with custom UI. The custom UI renders this value from the cookie and sends the value in the POST request payload to /sso/v1/sdk/authenticate authN api. SSO service in this case will use this device fingerprint hash value sent by the custom UI and store the value in sdk context(request state) for all the subsequent processing.

Request Payload:

{
    "op": "credSubmit",
    "credentials": 
	{
        "username": "testUser",
        "password": "Welcome@1",
        "device": "
        {....}
        "
    },
    "requestState": "requestState",
    "deviceFingerPrint": "123456789"
}

Response Payload:

{
    "status": "success",
    "ecId": "6cjO20L1000000000",
    "nextAuthFactors": [
        "SECURITY_QUESTIONS"
    ],
    "nextOp": [
        "credSubmit",
        "getBackupFactors"
    ],
    "scenario": "AUTHENTICATION",
    "requestState" : "...."
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    },
    "deviceFingerPrint": "123456789"
}

Enabling the Device Fingerprint

To use device fingerprint, you have to enable SSO settings.

Enable SSO settings for device fingerprinting by setting deviceFingerPrint to true using the REST API Replace SSO Settings PUT call. See Replace SSO Settings (PUT).

ssoSettings payload

{
	"logoutLandingPageURI": "/ui/v1/myconsole",
	"userMappingAttribute": "userName",
	"fedSsoOnly": false,
	"cookieSessionTimeout": 15,
	"ssoChooserEnabled": false,
	"sessionExpiryMinutes": 480,
	"sdkEnabled": true,
	"userNameFirst": null,
	"deviceFingerPrint": true,
	"schemas": [
		"urn:ietf:params:scim:schemas:oracle:idcs:SsoSettings"
	]
}

Device Fingerprint in UserDevices

The UserDevices REST API allows you to list all the devices linked to a specific user. See REST API for Oracle Identity Cloud Service.

To list all the devices with a unique fingerprint used by a specific user, use

GET /admin/v1/UserDevices?filter=owner eq "userid"

Sample response payload

"Resources": 
[
    { 
        "deviceType": "Mac",
        "verified": true, 
        "deviceFingerPrint":"c2NyZWVuQ29sb3JEZXB0aD0yNCwgbWltZVR5cGVzPW51bGwsIHBsdWdpbnM9bnVsbCwgYnJvd3Nlcj1DaHJvbWUsIGxhbmd1YWdlPWVuLUdCLW94ZW5kaWN0LCBwbGF0Zm9ybT1NYWMgT1MgWA==",
        "dfp": "7039602ba45600acf1234046c5d6133b327187ff9dc9af65eb6d97b6324a44d8" 
        "id": "b4c9a31d67aa4c45b9f1a441ee71b0d5" 
    }
]

The dfp value in the response payload is calculated and stored only when deviceFingerPrint Sso Settings is enabled. When it is not enabled, the dfp is marked as Unknown for new devices.

Use cases

Here, you can see when a New Device Login Detected with Your Account email is sent.

Use Case Behaviour
Alex logs in from Chrome browser for the first time and they do not have any previous entry in UserDevices from Chrome and Adaptive Access is enabled and deviceFingerPrint Sso setting disabled. Record the entry for Chrome in UserDevices. The dfp value is Unknown, and send a notification.
Alex logs in from Chrome browser for the first time and they do not have any previous entry in UserDevices from Chrome and Adaptive Access is enabled and deviceFingerPrint Sso setting enabled. Record the entry for Chrome in UserDevices with a proper dfp value and send a notification.
Alex logs in from Chrome browser for the first time and they do not have any previous entry in UserDevices from Chrome and Adaptive Access is disabled and deviceFingerPrint Sso setting disabled. Do not record any value and don't send a notification.
Alex logs in from Chrome browser for the first time and they do not have any previous entry in UserDevices from Chrome and Adaptive Access is disabled and deviceFingerPrint Sso setting enabled. Record the entry for Chrome in UserDevices with a proper dfp value, but don't send a notification.
Alex logs in from Chrome browser for the first time and they have a previous entry in UserDevices from Chrome and Adaptive Access is enabled and deviceFingerPrint Sso setting disabled. Record the dfp value as Unknown for the existing device if a dfp value does not already exist, but don't send a notification.
Alex logs in from Chrome browser for the first time and they have a previous entry in UserDevices from Chrome and Adaptive Access is enabled and deviceFingerPrint Sso setting enabled. Record a proper dfp value for the existing device if it does not already exist, but don't send a notification.
Alex logs in from Chrome browser for the first time and they have a previous entry in UserDevices from Chrome and Adaptive Access is disabled and deviceFingerPrint Sso setting disabled. Do not record any value and don't send a notification.
Alex logs in from Chrome browser for the first time and they have a previous entry in UserDevices from Chrome and Adaptive Access is disabled and deviceFingerPrint Sso setting enabled. Record a proper dfp value but don't send a notification.

Device Fingerprint in Tokens

Device fingerprint is added as part of ID tokens and Access tokens.

Whenever device fingerprint settings are enabled, dfp will be added as a claim in the following use cases:
  • JWT Assertion flow: When custom application exchanges the authnToken from sso/v1/sdk/authenticate endpoint for the access token, the device fingerprint from authnToken is added to the access token. See Understand the REST API Calls.
  • Authz code flow: In openId connect flows, when a custom application exchanges authz code for AT/ IT, the device fingerprint from the existing Identity Cloud Service session is added to the tokens based on scopes.
  • Get token from IDCS console: After successful login with Identity Cloud Service, the token retrieved from console to Invokes other APIs will also bear the device fingerprint as a claim. See Generate Personal Access Tokens.

Example 36-1 authn api response post successful authentication

{
    "authnToken":
        "eyJ4NXQjUzI1NiI6Iks0R0hvZVdoUmFhOTd6Um0xeDIzM0pwdlB3bm1GQVJGVlE1cE5QRDhsTEUiLCJ4NXQiOi
         JUYkdPcWVUWnJpeXZNZGplTC01MjAtaGVfRUUiLCJraWQiOiJTSUdOSU5HX0tFWSIsImFsZyI6IlJTMjU2In0.ey
         J1c2VyX3R6IjoiQW1lcmljYVwvQ2hpY2FnbyIsInN1YiI6ImFkbWluQG9yYWNsZS5jb20iLCJ1c2VyX2xvY2FsZSI
         6ImVuIiwiaWRwX25hbWUiOiJVc2VyTmFtZVBhc3N3b3JkIiwiaWRwX2d1aWQiOiJVc2VyTmFtZVBhc3N3b3JkIwiY
         W1yIjpbIlVTRVJOQU1FX1BBU1NXT1JEIl0sImlzcyI6Imh0dHBzOlwvXC9pZGVudGl0eS5vcmFjbGVjbG91ZC5jb21
         …"
    "status": "success",
    "ecId": "9uQ251a3000000000",
    "deviceFingerPrint": "d59c35b2baba97730fc359c1a2b592f6e773cc1eec073d0f11385edf6abd7fd4"
}

Example 36-2 authn token decrypted

{
	"user_tz": "America/Chicago",
	"sub": "admin@oracle.com",
	"user_locale": "en",
	"idp_name": "UserNamePassword",
	"idp_guid": "UserNamePassword",
	"amr": [
		"USERNAME_PASSWORD"
	],
	"iss": "https://identity.oraclecloud.com/",
	"island_name": "Global",
	"user_tenantname": "slc1",
	"client_id": "91932046c2df4090851c7b93efe1cf1f",
	"sid": "11eb7d7b9ee020bba7e3e7cd3f20296a",
	"acs": "N4K...",
	"azp": "custom ui",
	"authn_strength": 2,
	"auth_time": 1614925546,
	"client_tenantname": "slc1",
	"session_exp": 1614954346,
	"region_name": "slc12kps",
	"user_lang": "en",
	"exp": 1614954346,
	"iat": 1614925546,
	"client_name": "custom ui",
	"client_guid": "c513ad464a664ca091452937bf4030cf",
	"tenant": "slc1",
	"idp_type": "LOCAL",
	"jti": "11eb7d7b9ee2439ca7e3a131d1100b2a",
	"user_displayname": "admin opc",
	"sub_mappingattr": "userName",
	"primTenant": false,
	"tok_type": "IT",
	"dfp": "d59c35b2baba97730fc359c1a2b592f6e773cc1eec073d0f11385edf6abd7fd4",
	"aud": [
		"https://identity.oraclecloud.com/",
		"91932046c2df4090851c7b93efe1cf1f",
		"custom ui"
	],
	"user_id": "2003002e92e4492e960fde36c34e45c9",
	"tenant_iss": "https://slc1.identity.internal.oracle.com:8943"
}

Device Fingerprint in Audit Logs

The audit event attribute ssoDeviceFingerPrint maintains the device fingerprint hash value in all the SSO events, and it is added to audit records.

Example of an SSO Audit Event

{
	"ssoSessionExpiryTime": "2020-12-22T19:01:39Z",
	"idcsCreatedBy": {
		"type": "User",
		"display": "admin opc",
		"value": "16b5ae8e9dfd4ec4a68f449252159e5b",
		"$ref": "https://tenant1.identity.internal.oracle.com:8943/admin/v1/Users/16b5ae8e9dfd4ec4a68f449252159e5b"
	},
	"actorName": "admin@oracle.com",
	"id": "cc50265b-9448-4f19-8981-0d14703ace2a"
	.......
    "clientIp": "10.191.242.183",
    "ssoComments": "Session create success",
    "ssoBrowser": "Chrome",
    "ssoMatchedSignOnRule": "DefaultSignOnRule",
    "ssoDeviceFingerPrint": "db68d19334304e2624ca217de1196d30e9150335e0bd7b6072c44a0841073a79",
    "eventId": "sso.session.create.success",
    .......
}

ssoDeviceFingerPrint is not directly searchable in audit events.

Instead you can search for the application ID, a searchable attribute to which ssoDeviceFingerPrint is appended. See Audit Log Report

The sso.application.id will be "application.Id -ssoDeviceFingerPrint"

For example:

ssoApplicationId": "ec0cc4b24bfc4b87a3945c6f7e251882 - ca6c3e77d75dc3e318608493495726150371a4910c5c8a2994007c1f7e07875b
ssoApplicationId": "adminconsole - ca6c3e77d75dc3e318608493495726150371a4910c5c8a2994007c1f7e07875b
 ssoApplicationId": "NA - ca6c3e77d75dc3e318608493495726150371a4910c5c8a2994007c1f7e07875b