Device ID

Objective

This guide provides instructions on how to enable Volterra/Shape Device Identifier protection and apply the Device ID to your applications using VoltConsole. For more information on Device ID, see About Device ID.

Using the instructions provided in this guide, you can enable Device ID from VoltConsole, obtain the Javascript from the enablement method, apply it to your application, and monitor the information collected by the Device ID using various dashboard views in VoltConsole.


Prerequisites

Note: If you do not have an account, see Create a Volterra Account.

  • A valid BIG-IP or NGINX subscription in case deploying with BIG-IP or NGINX.

Protect Your Application with Device ID

Protecting your applications with the Device ID requires you to first enable it in VoltConsole, obtain the JS, and add it your application. Enabling Device ID in VoltConsole can be done in any one of the following ways:

  • Using Javascript snippet
  • Using BIG-IP iApp
  • Using NGINX

Perform the steps in the follwing sections to enable the Device ID in VoltConsole.

Deploy Device ID with a JavaScript Snippet

Do the following to deploy Device ID with a JavaScript snippet:

Step 1: Log into VoltConsole and enable Device ID.
  • In the System namespace, click Shape Device ID -> Overview in the left-hand menu.

did nav
Figure: Navigate to Device ID Page

Note: Click on the System icon on the namespace selector to change to system namespace.

  • On the Dashboard view, you should see a Shape Device ID tile. Click on Enable Device ID.

enable did
Figure: Enable Device ID

  • After clicking on the Enable Device ID button, a new tile should appear: Shape Device ID is enabled. Click on Add Application.

did add app
Figure: Device ID Enabled

Note: In case the Device ID is already enabled, the dashboard view shows Shape Device ID is enabled tile.

Step 2: Generate javascript snippet for your application.
  • In the Add Application pane, select JS Tag as your JS injection method.

vc add app
Figure: Select JS Injection Method

  • Click Next. Instructions for enabling Device ID with the JS snippet appear in the pane.

did jstag
Figure: Java Script Method Instructions

  • Follow the instructions for enabling Device ID with the JS snippet, and click Done when finished.

Deploy Device ID with the BIG-IP

Deploy Device ID with the BIG-IP by creating a BIG-IP iApp. Follow the steps below:

Step 1: Log into VoltConsole and enable Device ID.
  • In the System namespace, click Shape Device ID -> Overview in the left-hand menu.

did nav
Figure: Navigate to Device ID Page

Note: Click on the System icon on the namespace selector to change to system namespace.

  • On the Dashboard view, you should see a Shape Device ID tile. Click on Enable Device ID.

enable did
Figure: Enable Device ID

  • After clicking on the Enable Device ID button, a new tile should appear: Shape Device ID is enabled. Click on Add Application.

did add app
Figure: Device ID Enabled

Note: In case the Device ID is already enabled, the dashboard view shows Shape Device ID is enabled tile.

Step 2: Start BIG-IP injection for your application.
  • In the Add Application pane, select BIG-IP iApp as your JS injection method.

vc add app
Figure: Select JS Injection Method

  • Click Next. Instructions for enabling Device ID with BIG-IP iApp appear in the pane.

did bip
Figure: BIG-IP iApp Method

  • Click Download Template in the Step 2 of the displayed instructions. Download the .zip file containing the Device ID iApp template and extract the contents of the .zip file.
  • Follow the instructions for enabling Device ID with the BIG-IP iApp.
Step 3: Add the template and the JS URL into BIG-IP iApp.
  • Log into your BIG-IP account.
  • In the Main tab in the BIG-IP, go to iApps>Templates>Templates.

bip iapp templs
Figure: BIG-IP iApp Templates

  • Click Import. The Template Properties screen appears.
  • In the Template Properties screen, click Choose File, select the Device ID iApp template that you downloaded, and then click Upload. You should now see the template you selected in the Template List.
  • In the Main tab in the BIG-IP, go to iApps>Application Services>Applications.
  • Click Create.

create bip appsrv
Figure: Create BIG-IP Application

  • A new application service screen appears.
  • Assign a name to the iApp.
  • From the Template list, select the imported Device ID iApp template. The Device ID iApp template configuration settings appear.

bip template
Figure: BIG-IP Application Configuration

  • In the Volterra portal, at step 4 in the instructions, copy the link.
  • In the BIG-IP portal, paste the link at JS URL.
  • At Application’s Virtual Server(s) to Protect, select your web application’s virtual server(s).
  • Click Finished.
  • In the Volterra portal, click Done.

Note: The following apply:

  • Selecting at least one virtual server is mandatory. Your iApp will not run if it is not assigned to at least one virtual server.
  • The virtual server(s) you select here must have an HTTP profile attached to it. If you select a virtual server that does not have an HTTP profile attached to it, you will not be able to complete iApp configuration.
  • Every virtual server you select here must have a default pool attached to it.
  • If you choose more than one virtual server here, they must all be the same type, either all HTTP or all HTTPS. To use virtual servers of different types, create an iApp for each type.
  • The iApp must be deployed on the same partition as the virtual server(s) you select here.
Step 4: Complete enabling Device ID using BIG-IP iApp method.

Go back to VoltConsole and click Done in the BIG-IP iApp method pane.


Deploy Device ID with NGINX

Do the following to deploy Device ID with NGINX method:

Step 1: Log into VoltConsole and enable Device ID.
  • In the System namespace, click Shape Device ID -> Overview in the left-hand menu.

did nav
Figure: Navigate to Device ID Page

Note: Click on the System icon on the namespace selector to change to system namespace.

  • On the Dashboard view, you should see a Shape Device ID tile. Click on Enable Device ID.

enable did
Figure: Enable Device ID

  • After clicking on the Enable Device ID button, a new tile should appear: Shape Device ID is enabled. Click on Add Application.

did add app
Figure: Device ID Enabled

Note: In case the Device ID is already enabled, the dashboard view shows Shape Device ID is enabled tile.

Step 2: Start enabling Device ID for your application using NGINX.
  • In the Add Application pane, select NGINX as your JS injection method.

vc add app
Figure: Select JS Injection Method

  • Click Next. Instructions for enabling Device ID with the NGINX method appear in the pane.
  • Follow the instructions for enabling Device ID with the NGINX method.
Step 3: Perform NGINX configuration with the script tag.
  • Open your NGINX configuration file, usually located at:
/etc/nginx/conf.d/app_conf_file_name.conf
  • Create an upstream directive under the HTTP directive by copying the following code to your configuration file:
upstream safe {
   server dip.zeronaught.com:443;
}
  • Create a Location directive for the Device ID JS endpoints under your application server directive by copying the following code to your configuration file:
# Route the request to F5
location /__imp_apg__/api/ {
   proxy_pass https://safe;
}

location /__imp_apg__/js {
   proxy_pass https://safe;
}
Step 4: Add the JS to your application.

Copy the Device ID JS from Step 2 of instructions in VoltConsole. Inject it into the web pages of your application according to one of the following options:

  • Inject the Device ID JS in all web pages in your application: Copy the following line under your application server directive.
`sub_filter '</head>' '<script id="_imp_apg_dip_" imp_apg_cid="f5cs-a_aaKyi_Qttl-03c9cf14" type="text/javascript" src="/__imp_apg__/js/f5cs-a_aaKyi_Qttl-03c9cf14.js" async ></script></head>';`
  • Inject the Device ID JS in specific web pages only: If the application path is already defined as a location directive, copy the following line to the relevant location:
`sub_filter '</head>' '<script id="_imp_apg_dip_" imp_apg_cid="f5cs-a_aaKyi_Qttl-03c9cf14" type="text/javascript" src="/__imp_apg__/js/f5cs-a_aaKyi_Qttl-03c9cf14.js" async ></script></head>';`
  • Inject the Device ID JS in specific web pages only: If the Location directive is not defined in your configuration file, copy the following code to your server directive:
 # Inject Device ID JavaScript to specific path
 location /<specific_path> {
 sub_filter '</head>' '<script id="_imp_apg_dip_"  imp_apg_cid="f5cs-a_aaKyi_Qttl-03c9cf14"   type="text/javascript" src="/__imp_apg__/js/f5cs-a_aaKyi_Qttl-03c9cf14.js" async ></script></ head>';
 }

Repeat this step for each required injection path.

  • Inject the Device ID JS to all web pages, except for specific pages: To inject by default in all web pages, copy the injection line to your root location directive. If a root location directive is not defined, create one like this:
location /exclude_example {
 }

Note: If the path directive already exists, do nothing.

  • Save the .conf file and reload NGINX.
Step 5: Complete enabling Device ID using NGINX method.

Go back to VoltConsole and click Done in the NGINX method pane.


Advanced Configuration Options for Device ID iApp

Note: This configuration method is for customers with BIG-IP/iApp.

After you have deployed Shape Device ID on your web application using the BIG-IP iApp, you may want to fine tune the iApp configuration to better suit your system needs. These instructions present some advanced configuration options for the Device ID iApp template in the BIG-IP.

To configure the Device ID iApp template in the BIG-IP:

  • In the Main tab in the BIG-IP, go to iApps>Application Services>Applications and select your iApp from the list.
  • Click the Reconfigure tab (see below).

bip iapp recfg
Figure: BIG-IP iApp Reconfigure

The Device ID iApp template configuration settings appear.

  • At Configuration Level, select Advanced.

  • In the JS Injection Configuration section:

    • Location for JS Injection: From the drop-down list, select a location in the HTML code of your webpage for the JS injection.
    • Script Attribute: Choose an attribute that is added at the end of the injected JS, either Async Defer, Async, Sync or Defer. This attribute determines how the JavaScript is loaded and executed.
    • Inject JS in Specific Webpages Only: Select Yes to inject the JS in specific web pages of your web application. Select No to inject the JS in all web pages of your web application.
    • JS Injection Paths: If Inject JS in Specific Webpages Only = Yes, enter here the relative paths of the webpages in your application to receive the JS injections.
    • Exclude JS Injection from Specific Webpages: Select Yes to exclude the JS injection from specific web pages in your web application.
    • JS Excluded Paths: If Exclude JS Injection from Specific Webpages = Yes, enter here the relative paths of the web pages in your application that the JS injections should be excluded from.

  • In the Pool Configuration section:

    • Cookie Persistence for the Service Pool: Select Enable if, after initial load balancing, you want HTTP requests of the same session always sent to the same pool member in the Service Pool. Select Disable if you want the BIG-IP to perform standard load balancing.
    • Domain: If you entered a relative path in JS URL, enter a domain to receive HTTP requests or use the default value. If you used a full path, the domain of the full path is automatically used. * Add HTTP Health Check: Choose whether to perform the HTTP Health Check on the entire pool. The HTTP Health Check is performed in intervals of 5 seconds. If you activate the health check, the following related settings are displayed:
    • Liveness Path: The path to the site where the health check will be performed on the entire pool.
    • Port: The port on which the health check is performed.
    • Response Code: Enter the code that will indicate a successful health check result in the response from the site that was checked.

  • In the Advanced Features section:

    • Add Connecting IP to Headers: Select Yes to add the connecting IP to the XFF header and to add an Analytic Header that includes the connecting IP.

Note: If an HTTP profile attached to one of the web application’s virtual servers has an XFF header added to it and this setting is set to Yes, requests will show duplicate client IPs in the XFF headers. To avoid this situation, either remove the XFF header from the HTTP profile or set this setting to No.

  • Choose a Parent Server-Side SSL Profile for the Service Pool: Select an SSL profile (or use the default) that will be attached to a new virtual server for routing traffic to the Service pool.
  • Encrypting Virtual Server IP: A default IP is assigned. If you have a virtual server already configured to this IP, assign a different IP here.
  • Use SNI: Select Yes to use Server Name Indication (SNI) for pool members. Enable Debug: Select Yes to enable debug logs.

Note: Selecting an SSL profile here is mandatory, and only one SSL profile can be selected.

  • Click Finished.

Note: Refer to the Deploying the Analytics Products iApp Template in the F5® BIG-IP® System document for more information on comprehensive BIG-IP iApp deployment and configuration options.


Verify Device ID Deployment

After onboarding your application with Device ID, it is a good idea to test that the deployment was successful. To determine whether the deployment was successful, you need to check for two things on the web pages of your application:

  • Is the Device ID JS called from the web page?
  • Does the web page contain the _imp_apg_r cookie?

If the answer to both questions above is yes, then deployment was successful.

Follow these steps to check that deployment was successful:

  1. For every web page that received the Device ID JS injection, open the page in a web browser.

    Note: If you used a tag management system to inject the Device ID JS on your web pages, skip the next step and proceed to step 3.

  2. Check that the page source contains the Device ID JS.

    Note: For web pages in your application that do not require a user login to access them, there is an alternative way to check if the web page contains the Device ID JS during the deployment procedure. Paste the web page URL and click Test JS Injection in the VoltConsole application method pane.

  3. Check that the page contains the impapg_r cookie.

View Data in Device ID Dashboard

The Shape Device ID dashboard presents different views into the data collected by Device ID. Data is presented through various graphical widgets. These widgets provide you with information around how devices are interacting with your applications and show potential indications of suspicious activity.

Time-Period for Data Display

Choose a time-period for displaying data: Last 24 hours, Last 7 days, or Last 30 days.

Unique Devices over Time

This widget displays the number of unique devices that accessed your applications during the selected time-period. This information is useful since an unexpected large number of unique devices accessing your applications in a short period of time can be an indication of malicious activity.

New vs. Returning Devices over Time

This widget displays the number of new devices (first-time accessing your applications) versus the number of returning devices (devices that have accessed your applications at least once in the past) for the selected time-period. This information is useful since an unexpected large number of new devices accessing your applications in a short period of time can be an indication of malicious activity.

Devices per Device Age

This widget displays the number of devices according to the device age for all the devices that accessed your applications during the selected time-period. The age of a device is determined by the amount of time that has passed since the device was first identified.

The red, dashed, vertical line indicates the average age of all devices that accessed your applications during the selected time-period.

Devices per Session Length

This widget displays the number of devices according to the session length of the device for all the devices that accessed your applications during the selected time-period. Session length is determined according to how long a device was connected to your application. This information is useful since a large number of devices with a short or long session length can be an indication of malicious activity.

The red, dashed, vertical line indicates the average session length of all devices that accessed your applications during the selected time-period.

Devices per Country

This widget displays the number of devices per country that accessed your applications during the selected time-period. To view the number of devices for a given country, hover over a country with the mouse and the number is displayed.

ASNs per Device

This widget displays the number of devices with a certain number of Autonomous System Numbers (ASNs) for all the devices that accessed your applications during the selected time-period. This information is useful since a large number of ASNs for a device can be an indication of malicious activity.

User Agents per Device

This widget displays the number of devices with a certain number of User Agents for all the devices that accessed your applications during the selected time-period. This information is useful since a large number of User Agents for a device can be an indication of malicious activity