Developing NS MedTracker – part 1
Authentication and Infrastructure
by Burag Cetinkaya
In Part 1, we will be developing the basic structure of Netsoft MedTracker and take a closer look at how HealthVault authentication works. Note that you can either follow the steps here or download the complete source code. You will also need to download the HealthVault SDK to complete Part 1.
Setting up the project
Before we start writing code, we need to configure our HealthVault-enabled application and do some infrastructure work. A HealthVault application essentially has two properties associated with it:
- An application ID assigned by HealthVault (more on this later).
- A certificate installed under IIS.
Both steps above can be configured using the HealthVault Application Manager tool that comes as part of the HealthVault SDK. For the purposes of the MedTracker application we will refer to the Netsoft USA Demos certificate and application ID. It is assumed that you will create an application ID and a certificate for your application. Shortly, we will go through the necessary steps to create a new certificate and register it with HealthVault. If you already have a certificate, you can skip to the next section.
Launch the HealthVault Application Manager and click on Create New Certificate button. You will be prompted to enter a name of your application. Pick a name that you would like and click the OK button.
Now that the certificate is created on your workstation, it needs to be uploaded to the HealthVault for processing. Using the HealthVault Application Manager, right click on the newly created application name and select "Upload Certificate".
You will be taken to Application Configuration Center where you will be ale to get the application ID associated with your application. Replace the web.config specified default application ID with this value.
We will then add some keys to the web.config in order to configure MedTracker to use the newly created certificate and point to the HealthVault service URLs. Please see the full content of the web.config file before moving forward for additional keys.
20 <appSettings>
21 <add key="ApplicationId" value="Netsoft Application ID" />
22 <add key="ShellUrl" value="https://account.healthvault-ppe.com/" />
23 <add key="HealthServiceUrl" value="https://platform.healthvault-ppe.com/platform/" />
24
25 <!-- when we call the SignOut() method on HealthServicePage, it redirects us to the page below -->
26 <add key="NonProductionActionUrlRedirectOverride" value="Redirect.aspx"/>
27
28 <!-- The redirect page (specified above) uses these keys below to redirect to different
29 pages based on the response from the shell -->
30 <add key="WCPage_ActionHome" value="default.aspx"/>
31 <add key="WCPage_ActionAppAuthSuccess" value="default.aspx"/>
32 <add key="WCPage_ActionSignOut" value="SignedOut.aspx" />
33 </appSettings>
Notice the -ppe suffix in the Shell and Health Service URLs. Using these keys, we will point our application to the development sandbox environment instead of production.
Now we need to add references to the Microsoft HealthVault SDK dlls.
HealthVault SDK provides us with the following functionality:
- Ensuring that the user is logged into HealthVault.
- Abstracting the HealthVault connection process.
- Abstracting item type serialization/deserialization from XML to .NET classes.
We will now add a second page to our application that will serve as the authenticated home page. We will name this file Medications.aspx. This page will utilize the HealthVault SDK and ensure that the current user is logged into HealthVault in order to view the page. To enable this functionality, we need to derive Medications.aspx from HealthServicePage, instead of System.UI.Page.
13 using Microsoft.Health.Web;
14
15 public partial class Medications : HealthServicePage
16 {
17 protected void Page_Load(object sender, EventArgs e)
18 {
Now we need to decide on what kind of authentication mechanism we want to use for MedTracker. In order for MedTracker to store/retrieve HealthVault information on behalf of a user, the user needs to give necessary permissions to the application. Application permissions are set through the HealthVault shell (a set of web pages hosted at healthvault.com).
An application can use two connection modes when connecting to HealthVault in order to access information for a user:
In live mode, the user needs to be presently logged into HealthVault through the browser. The user receives a token from the HealthVault shell that has an expiration date set on it. After the token is expired or the user closes the browser, the process needs to be repeated.
A health dashboard application that aggregates health data from different sources and displays it on a web page per the user’s request would use the live access mode since the user is already present.
With offline mode, after the user sets necessary permissions for an application, connections can be made from the application to HealthVault on behalf of the user without requiring the user to be logged into HealthVault.
A weight monitoring application that periodically pushes information to HealthVault based on a nightly schedule would use the offline access mode.
For the purposes of the MedTracker demo, we will be using live mode.
How does authentication work?
We derived the Medications page from HealthServicePage instead of the generic Page class. Pages that derive from HealthServicePage have the OnPreLoad event look into the URL to receive a token or read the authentication information from a cookie. If the user is not authenticated with HealthVault, a redirect will be issued to the browser leaving your site to go to the HealthVault shell, where authentication will occur. Once authentication is complete, the user will be redirected back to a page indicated in the web.config based on the action that has been taken in HealthVault (successful authentication, etc). For example after a user successfully logs into HealthVault, she gets redirected to the pre-defined “gateway page.” Pre-defined in the development environment means a web.config entry:
26 <add key="NonProductionActionUrlRedirectOverride" value="Redirect.aspx"/>
Pre-defined in the production environment is a hard-coded URL on the HealthVault side that you supply as part of your application’s registration process (See the Go-Live guide). The gateway page is responsible for redirecting the user to different pages within your web application based on the HealthVault action. For example, if the user logs into HealthVault successfully the Gateway page will be called with a specific query string. It is then the gateway page’s responsibility to redirect the user to the correct page. Here is a list of different action pages you will need:
- Home
- Eula
- Help
- AppAuthReject
- AppAuthSuccess
- SelectedRecordChanged
- ShareRecordSuccess
- ShareRecordFailed
- Privacy
- SignOut
You can find more information on the semantics of each action URL at MSDN HealthVault Reference Page
Fortunately, the HealthVault SDK already comes with a built in page that reads web.config values and redirects the user to the appropriate page based on the action. All you need to do is to use the HealthServiceActionPage or a page that derives from it. NS MedTracker uses a page called Redirect.aspx that acts as a gateway. It looks like the following;:
13 using Microsoft.Health.Web;
14
15 public partial class Redirect : HealthServiceActionPage
16 {
Below is a diagram summarizing the major steps of the authentication process.
Click on the thumbnail for larger image.
You will notice that the first time you run the application and sign into HealthVault, you will be prompted to give access to the Netsoft USA Demos application. How does HealthVault know that authentication should be given to Netsoft USA Demos application? Before we go forward there are a couple of things to keep in mind:
- HealthVault has the public key of the certificate that our application is using.
- IIS has access to the private key of the certificate.
The web.config keys that we have previously set up come into play here. When the application tries to communicate with the HealthVault, it creates a WebApplicationConnection, which in turn takes an application ID and identifies the application to HealthVault. After authentication is complete, HealthVault encrypts the data using the public key associated with the application ID. After the user comes back to the application, the SDK uses the certificate to decrypt the authentication token and the user is authenticated.
Note: If there is a problem with the certificate (e.g, IIS does not have proper rights to read the certificate) you will see a .NET cryptography exception. Make sure that the certificate is installed, and IIS has necessary rights to the certificate.
Download the source code associated with part 1 here. Keep in mind that each article in the series builds on the previous one. If you would like to download the complete solution please see part 3.
Continue on to part 2 of this series.