Before You Begin

In this tutorial, you learn how to enable the Access from an unknown device event of Adaptive Security so that it's triggered when users access Oracle Identity Cloud Service through a custom sign-in page.

Background

Adaptive Security is an advanced feature of Oracle Identity Cloud Service that provides strong authentication capabilities for your users, based on their behavior within Oracle Identity Cloud Service, and across multiple heterogeneous on-premises applications and cloud services.

When activated, Adaptive Security analyzes a user’s risk profile within Oracle Identity Cloud Service when they sign in to access the service, based on their historical behavior and real-time device context, such as access from unknown devices.

Adaptive Security uses the concept of risk providers to allow identity domain administrators and security administrators to configure various contextual and threat events to be analyzed within Oracle Identity Cloud Service. A default risk provider within Oracle Identity Cloud Service is seeded automatically with a list of supported contextual and threat events, such as Access from an unknown device. For this event, if a user accesses Oracle Identity Cloud Service from a device that hasn’t been previously used to access the service, then this event (commonly referred to as Device Fingerprinting) is triggered.

Although Oracle Identity Cloud Service has a default sign-in page, you may prefer to use your own sign-in page. If so, then download, unzip, and use the Custom Sign-In API web application. By doing so, you configure this sample web application for the following use cases:

• New device login: A user signs in to Oracle Identity Cloud Service through your custom sign-in page. The user name and password is captured, and then the device is detected to be a new device based on the device's fingerprint.
• Social user registration: A user is using a social identity provider to register with Oracle Identity Cloud Service. The fingerprint of the user's device is captured so that it's passed, along with the user's social credentials, to the social identity provider so that the Access from an unknown device event is triggered.
• Social user login: This use case is similar to the Social user registration use case, but the user is using a social identity provider to sign in to Oracle Identity Cloud Service. This user is registered with Oracle Identity Cloud Service.

What Do You Need?

To accomplish the tasks described in this tutorial, make sure that you have:

• Completed the Customize the Oracle Identity Cloud Service Sign-In Page Using the Authentication API tutorial so that you have a custom Oracle Identity Cloud Service sign-in page.
• Downloaded and unzipped the Custom Sign-In API web application from the GitHub repository to a folder on your computer.
• Access to an Oracle Identity Cloud Service instance with rights as an identity domain administrator or security administrator to register applications and to verify that the changes made in this tutorial take effect.
• A basic knowledge of the JavaScript programming language to understand the code logic used in this tutorial.

About the device-fingerprint.js and signin.html Files

In this section of the tutorial, you learn about two files:

• device-fingerprint.js: Oracle Identity Cloud Service uses this JavaScript file to capture information about the device that the user is using to access Oracle Identity Cloud Service through the custom sign-in page. This information is sent back to Oracle Identity Cloud Service so that the Access from an unknown device event is triggered. You access this file from the Downloads page of the Identity Cloud Service console.
• signin.html: This HTML file is associated with the custom sign-in page. The version of this file that you downloaded references the device-fingerprint.js file.

1. Navigate to the folder on your computer where you unzipped the Custom Sign-In API web application from the GitHub repository.
2. Within this folder, navigate to the idm-samples/idcs-authn-api-signin-app/public/js directory.
3. In this directory, place the device-fingerprint.js file that you downloaded from the Downloads page. This file contains the getFingerprint() function that's used to retrieve information about the device that a user is using to access Oracle Identity Cloud Service.
4. Navigate to the idm-samples/idcs-authn-api-signin-app/public directory.
5. Using a text editor, open the signin.html file, and then search for the <script src="./js/loginApp.js"></script> line of code.
6. Below this line of code, enter the <script src="./js/device-fingerprint.js"></script> line of code.

   

   This file references the device-fingerprint.js file. When a user accesses Oracle Identity Cloud Service through the custom sign-in page, information about the user's device is captured and sent back to Oracle Identity Cloud Service so that the Access from an unknown device event is triggered.

7. Save your change to the signin.html file, and then close the file.

About the loginApp.js File (for New Device Login)

In this section of the tutorial, you learn about the loginApp.js file. This JavaScript file is associated with the behavior of users who are signing in to Oracle Identity Cloud Service through the custom sign-in page. The version of this file that you downloaded captures the user name and password, and detects whether the device that the user is using to access Oracle Identity Cloud Service is new, based on the fingerprint associated with the device.

1. Navigate to the idm-samples/idcs-authn-api-signin-app/public/js directory.
2. Using a text editor, open the loginApp.js file, and then search for the case 'PostCreds'; line of code.
3. Below this line of code, enter the following lines of code:

   var deviceInfo = getFingerprint();
   return {"username": document.getElementById("userid").value, "password": document.getElementById("password").value, "device": deviceInfo):
   

   

   In this file, the deviceInfo variable calls the getFingerprint() function of the device-fingerprint.js file to retrieve information about the user's device, so that it's passed, along with the user name and password, as part of the payload. If Oracle Identity Cloud Service determines that this device hasn’t been previously used to access the service, then the Access from an unknown device event is triggered.

4. Save your change to the loginApp.js file. Don't close this file because you'll be using it in the next section of this tutorial.

About the loginApp.js File (for Social User Registration)

A new Oracle Identity Cloud Service user must register with the service to be able to access it. After the registration is complete, if identity domain administrators or security administrators have added and activated social identity providers in Oracle Identity Cloud Service, then users sign in to Oracle Identity Cloud Service with their social credentials. This is social user registration.

If users don't already have accounts in Oracle Identity Cloud Service, then administrators can configure two types of registration for the social identity provider:

• Explicit registration: A user creates an account by using a registration page.
• Implicit registration: The provider uses the user’s social credentials to create an account for the user automatically.

The user registers, either by the user clicking the Submit button (for explicit registration) or by Oracle Identity Cloud Service performing this function (for implicit registration). Then, the loginApp.js file captures the user's social credentials, and detects that the device that the user is using to access Oracle Identity Cloud Service is new, based on the device's fingerprint.

1. In the loginApp.js file, search for the formDiv.querySelector("#social-submit-btn").onclick = function() and var data = {}; lines of code.
2. Below the var data = {}; line of code, enter the var deviceInfo = getFingerprint(); line of code.
3. Search for the dummy! api will break without it string of text.
4. Below this string of text, enter the data.device = deviceInfo; line of code.
   

   

   After the Submit button is clicked ("#social-submit-btn") to complete the registration process, the code flow in the loginApp.js file is triggered. The deviceInfo variable calls the getFingerprint() function of the device-fingerprint.js file to retrieve the device fingerprint so that it's passed, along with the user's social credentials, as part of the payload. Because this is a new user, the user's device hasn’t been previously used to access Oracle Identity Cloud Service. The Access from an unknown device event is triggered for the user.

5. Save your changes to the loginApp.js file. Don't close this file because you'll be using it in the next section of this tutorial.

About the loginApp.js and idcsAuthnSDK.js Files (for Social User Login)

This section of the tutorial is similar to the social user registration section, except that the user is using a social identity provider to sign in to Oracle Identity Cloud Service. This user is registered with Oracle Identity Cloud Service.

After the user uses their device and a social identity provider to access Oracle Identity Cloud Service, the fingerprint of the device is captured in the loginApp.js file, and is sent to the idcsAuthnSDK.js file. This JavaScript file then passes this fingerprint to the SSO SDK API. If the device hasn’t been previously used to access Oracle Identity Cloud Service, then the Access from an unknown device event is triggered for the user.

1. In the loginApp.js file, search for the btn.addEventListener('click', function (event) and var name = idp.idpName; lines of code.
2. Below the var name = idp.idpName; line of code, enter the var deviceInfo = getFingerprint(); line of code.
3. Search for the 'idpType': idp.idpType line of code.
4. Below this line of code, enter the 'device': deviceInfo line of code.

   

   After the user uses their device to click a social identity provider to sign in to Oracle Identity Cloud Service (btn.addEventListener('click', function (event)), the deviceInfo variable calls the getFingerprint() function of the device-fingerprint.js file to retrieve the device fingerprint so that it's passed, along with the social identity provider that the user clicked, as part of the payload (self.sdk.chooseIDP(payload);). This information is passed to the idcsAuthnSDK.js file.

5. Save your changes to the loginApp.js file, and then close the file.
6. Navigate to the idm-samples/idcs-authn-api-signin-app/public/js directory.
7. Using a text editor, open the idcsAuthnSDK.js file, and then search for the addInput(myForm, 'clientId', payload.clientId); line of code.
8. Below this line of code, enter the addInput(myForm, 'device', payload.device); line of code.

   

   In this file, the device fingerprint is captured (addInput(myForm, 'device', payload.device);) and passed to the SSO SDK API (myForm.action = app.baseUri + "/sso/v1/sdk/idp";) as part of the payload. Oracle Identity Cloud Service determines whether the device has been previously used to access the service. If it hasn't, then the Access from an unknown device event is triggered for the user.

9. Save your change to the idcsAuthnSDK.js file, and then close the file.
10. Restart the custom UI for the changes you made to all of the files in this tutorial to take effect.

Want to Learn More?

• Add a Social Identity Provider
• Integrate Social Networks with Oracle Identity Cloud Service