README.md

Page Detection with App Insights

Overview

This project performs page detection of common, uncustomized ADFS web pages, and then uploads telemetry about those pages to your Azure Application Insights datastore.

Note that this customization DOES NOT send any telemetry to the Microsoft ADFS team. All telemetry is sent to your datastore only.

This project also includes some useful analysis scripts you can run against your Application Insights datastore.

Requirements

This tool requires that you have an Azure Application Insights subscription.

Additionally, it is recommended that you have minimal web customization of the standard ADFS pages, as customization could throw off the page detection. Please note that customization referres to onload.js changes, not logo changes, illustration changes, etc.

Lastly, there is some page detection logic that relies on English strings in the pages. If you are presenting pages in languages other than English, you might need to make modifications to the JavaScript.

Getting Started

  1. Register for an Azure Application Insights subscription

  2. Download the onload.js in this repo locally, and update the instrumentationKey under GenerateAppInsightsObject to be your Application Insights API key

    (For more details, see Copy the instrumentation key)

  3. Replace the onload.js in your ADFS environment with the onload.js from this project. Alternatively, if you already have content in your onload.js, you should append our content to yours.

    Note: It is highly recommended that you minify your onload.js before including it in a production environment. There are many popular tools online for minifying JavaScript code. Two popular choices are minifier.org and JSCompress.

    (For more information, see Advanced ADFS Customization)

What Gets Tracked

The following pages are detected and tracked:

  • Forms Page - the username and password collection page
  • Auth Selection Page - the page served when MFA is required. This page lists MFA provider options
  • PFA Waiting Page - the page served when Phone Factor Authentication (PFA) is performed by the MultiFactorAuthenticationAdfsAdapter
  • Error Page - the ADFS or PFA error page

Analyzing the Data

To analyze your data, you will need to write analysis queries against your Azure Application Insights datastore. For more details, see Analytics.

Included in this project are a number of useful queries for tracking:

  • User prompting rate served by ADFS server
  • Login reliability of your ADFS server
  • Interactive completion rate of your ADFS server

Further Reading

The following documentation is useful for making changes to the onload.js code and the included queries.

Contributing (Special Note)

If you are contributing code, please be sure that you remove your instrumentation key from any code you put in a pull request. This project is public, and anyone on the Internet can see it.

For the full Contributing details, please see the root README.