Device ID

Objective

This guide provides instructions on how to enable Shape Device ID and apply it on 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 and apply it to your application, and monitor the data collected by 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.

Enable Device ID

Device ID can be enabled VoltConsole according to one of the following methods:

  • Using a JavaScript tag
  • Using a BIG-IP iApp
  • Using NGINX
  • Using CloudFront

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

Deploy Device ID with a JavaScript Tag

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

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 a JavaScript tag 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 tag appear in the pane.

did jstag
Figure: Java Script Method Instructions

  • Follow the instructions for enabling Device ID with the JS tag, 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: Select BIG-IP iApp for the JS injection method.
  • 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 Step 2 of the displayed instructions. Download the .zip file containing the Device ID iApp template and extract the contents of the .zip file.
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. A new application service screen appears.

create bip appsrv
Figure: Create BIG-IP Application

  • 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).

    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.
    • The iApp must be deployed on the same partition as the virtual server(s) you select here.
  • Click Finished.
  • In the Volterra portal, click Done.

Step 4: Complete enabling Device ID in VoltConsole.

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.
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 a Location directive for the Device ID JS endpoints under your application server directive by copying the following code to your configuration file:
location /__imp_apg__/ {
proxy_ssl_server_name on;
proxy_pass https://us.gimp.zeronaught.com;
}
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:

Note: NGINX injects the Device ID+ JS for the HTML MIME type only. If you want to inject the XHTML MIME type, you should use the following command:

`subs_filter_types text/html application/xhtml;`
  • 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>';`

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 / {
 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>';
}

To exclude the injection from a specific web page, define an empty directive for the path you want to exclude 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 in VoltConsole.

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


Deploy Device ID with CloudFront

Perform the following steps to deploy Device ID with CloudFront.

Step 1: Log into VoltConsole and enable Device ID.
  • In the System tab, 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 tab selector to change to system tab.

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

enable did
Figure: Enable Device ID

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

did add app
Figure: Device ID Enabled

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

Step 2: Generate a JavaScript tag 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 tag appear in the pane.

did jstag
Figure: Java Script Method Instructions

  • At step 2 in the instructions, copy the JS tag.
Step 3: Prepare the JS tag for insertion on the web pages of your application.
  • Remove the domain name from the JS tag you received in VoltConsole. For example, if you received the following JS tag in VoltConsole:
<script async defer src="https://us.gimp.zeronaught.com/__imp_apg__/js/volt-volterra_gmoxuqwg-002e303d.js" id="_imp_apg_dip_" 
_imp_apg_cid_="volt-volterra_gmoxuqwg-002e303d" _imp_apg_api_domain_="https://us.gimp.zeronaught.com"></script>

Remove the domain name us.gimp.zeronaught.com in the two places that it appears in the tag.

  • Paste the domain name of your application in the JS tag. For example, if the domain name of your application is f5.com, you paste it twice in the JS tag above like this:
<script async defer src="https://f5.com/__imp_apg__/js/volt-volterra_gmoxuqwg-002e303d.js" id="_imp_apg_dip_" 
_imp_apg_cid_="volt-volterra_gmoxuqwg-002e303d" _imp_apg_api_domain_="https://f5.com"></script>
  • Insert the updated JS tag between the <head> and </head> tags in all the web pages of your application.
Step 4: Configure Device ID in CloudFront.
  • In CloudFront, go to the Distribution of your web application.
  • Click the Origins tab and click Create Origin.
  • For Origin domain, enter the domain of your web application.
  • For Protocol, select HTTPS only.
  • Click Create origin.
  • Click the Behaviors tab and click Create behavior.
  • For Path pattern, enter /__imp_apg__/*
  • At Origin and origin groups, select the origin that you previously created.
  • At Viewer protocol policy, select Redirect HTTP to HTTPS.
  • At Allowed HTTP methods, select GET, HEAD, PUT, POST, PATCH, DELETE.
  • At Cache key and origin requests, select Legacy cache settings and then select the following:

    • Headers = All
    • Query strings = All
    • Cookies = All
  • Click Create behavior.
Step 5: Complete enabling Device ID in VoltConsole.

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


Advanced Configuration Options for the Device ID 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.

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

    • 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.
  • Click Finished.

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


For users of the Device ID/NGINX integration, it is possible to parse the Device ID cookie values (for the residue-based identifier and the attribute-based identifier) in NGINX before they are available in the upstream server. These parsed cookie values can be used to enrich access logs, or for other purposes, before sending the HTTP request to the upstream server.

  export default { diA, diB }

  var imp_apg = { diA: "-", diB: "-" };

  function getIdentifier(diCookie, idType) {
     try {
         if (typeof(diCookie) != "undefined") {
            imp_apg = JSON.parse(decodeURIComponent(diCookie));
            return imp_apg[idType];
         }
     } catch(e) {
         ngx.log(ngx.ERR, `ERROR decoding Device ID+ cookie: ${e}`);
     }
     return '-';
  }

  function diA(r) {
     return imp_apg.diA === "-" ? getIdentifier(r.variables.cookie__imp_apg_r_, "diA"): imp_apg.diA;
  }

  function diB(r) {
     return imp_apg.diB === "-" ? getIdentifier(r.variables.cookie__imp_apg_r_, "diB"): imp_apg.diB;
  }
  • At this point you have defined the logic for parsing values for the residue-based identifier (diA) and the attribute-based identifier (diB). You can use these parsed values in the NGINX Plus configuration file to enrich your access log with the cookie values, or for other purposes. To enrich the access log with the Device ID identifiers, add the following configuration to your NGINX Plus configuration file:
  js_import /etc/nginx/deviceid.js;
  js_set $dia deviceid.diA;
  js_set $dib deviceid.diB;

  log_format deviceid '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" $dia $dib';

  server {
    #...
    access_log /var/log/nginx/access.log deviceid;
  }
  • Reload NGINX Plus with the following command: nginx -t && nginx -s reload
  • Send a request to your Device ID enabled web site or application.
  • Check the access log to verify that the Device ID cookie values were logged.

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 _imp_apg_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