Drug Profile Interoperability Project

Lightweight Open Framework Leavebehind Document

Accessing Protected Resources

Table of Contents

• Problem
• Proposed Solution
• OAuth
• What OAuth Is Not
• Why OAuth Was Used
• Domain Standards and Technologies
  • Continuity of Care Record (CCR)
  • National Drug Code (NDC)
• The Particulars of Our Use Case
• Consumer Considerations
  • Issues
  • Exception Handling
• Provider Considerations
• Flow Overview (Screenshots)

Problem

Securely share data between two websites without either system knowing the user creditials for the other system.
Top

Proposed Solution

Use the OAuth protocol.
Top

OAuth

OAuth, as described on www.oauth.net:

The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. More generally, OAuth creates a freely-implementable and generic methodology for API authentication.

The inner workings of OAuth can be fully discovered at the website above and won't be discussed in full detail here. For our purposes it is sufficient to understand that the OAuth spec covers an initial token exchange that is started by the Consumer that requires the user to login to the Service Provider's website where they will grant permission to the Consumer to access their data/service. Once the user confirms that they want to grant access, the Service Provider system gives the Consumer an access token. The access token can have an expiration on it but in our example here all access tokens are valid until explicitly revoked.

Once the Consumer has an access token in its possession it can then use that token to query the Service Provider for user specific data or to execute a service on that user's behalf.

Here is a flow of the OAuth request token and access token exchange:

Top

What OAuth Is Not

OAuth is not a Single Sign On (SSO) implementation between two websites. OAuth enables access to very specific services to be granted from one system to the other. The communication established is not two-way. However, nothing prevents a system from being a Service Provider and a Consumer but two separate access tokens would need to be exchanged for the two-way communication. Again this is not an SSO implementation so this does not allow a user to jump between two websites without authenticating with both.
Top

Why OAuth Was Used

As an open source spec it has gone through much due-dilegence and will more than likely be more secure and easily adopted by other Service Providers than any home grown solution would. The OAuth site offers fairly functional code in java, .net and other languages of sample implementations of both an OAuth Service Provider and Consumer. Working with a relatively short time frame also made coding a custom solution unrealistic. We also found that other service providers are already using OAuth so future integrations with them will be more straight forward and predictable.
Top

Domain Standards and Technologies

Continuity of Care Record (CCR)

Once an access token is securely exchanged between DestinationRx and PharmaSURVEYOR data can then be exchanged. The requested data is returned in an XML standard known as Continuity of Care Record (CCR). Details about the standard can be found at www.ccrstandard.com. We've also provided a sample of the CCR exchanged here.
Top

National Drug Code (NDC)

For the transfer of medications within the CCR XML document we've standardized on using the National Drug Code (NDC) coding system to translate between Data Provider and Consumer drug namespaces. This coding system is public/free. More information can be found at the official NDC site: www.fda.gov/cder/ndc/database/.
Top

The Particulars of Our Use Case

Our goal was to enable an individual to securely transfer their medications from their DestinationRx Medicine Cabinet into a PharmaSURVEYOR Regimen Survey. In this example DestinationRx is the Service Provider and PharmaSURVEYOR is the Consumer. After a user has granted permission to PharmaSURVEYOR to access their DestinationRx Medicine Cabinet they can on subsequent visits request a Regimen Survey of their DestinationRx Medicine Cabinet medications without logging into DestinationRx. At this time the access token only gives PharmaSURVEYOR access to the user's medications but could in the future grant access to other data or services or a different access token could be required for each data/service granted access to. Best practices for token/services managment would be a good expansion for this document once someone has implemented accessing mulitple services and datas.

The access tokens provided by DestinationRx are long lived. The user should have the ability to revoke the token from the PharmaSURVEYOR or DestinationRx websites.

Once the access token is exchanged PharmaSURVEYOR can then request the user's medications. DestinationRx returns the medications in the CCR XML format. PharmaSURVEYOR stores the XML in Oracle and then uses Oracle's built in XQuery functionality to parse the XML and then uses the parsed data as input to a Regimen Survey.
Top

Consumer Considerations

PharmaSURVEYOR started by using the Java (1.5) sample implementation found on the OAuth website. It runs on Tomcat 6. Development work was initially done on a Windows Vista machine and now is deployed on Redhat Linux. It is all platform independant and should work equally well on older Windows boxes as well as Macs, Solaris and other Unix varies that offer a Java 1.5 JVM. Java, Tomcat and the OAuth samples are all free and thus provide a very low cost of entry. In our particluar implementation we are storing the access token in an Oracle 10gR2 database. Our java data access is provided via Hibernate 3 (also free). The OAuth process also requires the creation of a private/public key which was done using openssl on Redhat. PharmaSURVEYOR uses Oracle 10gR2 as its CCR data store and makes use of its built in XMLQuery (XQuery) functionality for parsing the CCR document received from DestinationRx.

Issues

• Requests (both for initial token exchange as well as data/service request) should be able to handle redirects from the Service Provider. The sample code from OAuth does not handle this. Usually the Service Provider will return a 301 (permanently moved) status code with a new location. Your Consumer should be able to handle this redirect without any input from the user.
• The OAuth spec allows a Service Provider to receive OAuth specific parameters (in both the initial token exchange and the data/service requests) to be either specified as URL parameters (or post parameters) or to be specified in the request header. You'll want to confirm with your Service Provider which they prefer. In PharmaSURVEYOR's case Google Health wants the parameters in the header and DestinationRx pulls them out of URL parameters. You should implement your Consumer such that it can do either. The sample code provided by OAuth always puts them in the URL and not in the header. You'll have to extend the code to also get them in the header. It's also important to not put them in both the URL and the header for any given request, such an implementation breaks with Google Health and should probably generally be avoided.
• When storing the CCR XML document in a Oracle database column of XMLTYPE, it is necessary to declare the default element namespace when using Oracle's XQuery functionality to query the document. Failure to declare the default element namespace will result in no data returned by the query. This is not obvious in Oracle's documentation. For the sample CCR XML posted here, an example of querying the document stored in Oracle table.column named CCR_DATA.CCR_XML to retrieve the element for those medications coded with the NDC Coding System would be:

  SELECT XMLQuery('declare default element namespace "urn:astm-org:CCR"; (: :)
  for $i in /ContinuityOfCareRecord/Body/Medications/Medication/Product/ProductName/Code
  where $i/CodingSystem eq "NDC"
  return $i/Value'
  PASSING CCR_XML RETURNING CONTENT)
  FROM CCR_DATA ;

  Note that '(: :)' is used to stop the SQL*PLUS interpreter from treating the ';' as the end of the SQL Statement.

Top

Exception Handling

There are three main types of Exceptions handled by the Consumer:

1. Error in the OAuth process. These errors should be very rare in production, but it is possible that a user could have an expired or invalid access token associated with their account. If this happens the user is notified that the accounts are no longer linked and offered a link to restablish the linking between the two accounts.
2. No drugs received because although a valid access token was exchanged, the user chose not to share their medication information with PharmaSURVEYOR. In this case the user is told that they have not granted PharmaSURVEYOR access to their medications and provides a link back to DestinationRx where they could change that permission if desired.
3. Successful exchange of the CCR document, but problems with the medications received. This could include the medications received from DestinationRx not mapping into PharmaSURVEYOR's drug space, medications providing in coding system format other than NDC, more drugs than can be ran in a PharmaSURVEYOR Regimen Survey being received, or duplicate drugs being received. In any of these cases the user is presented with a screen explaining the details of the problem and the ability to edit their medication list prior to running the Regimen Survey.

Top

Provider Considerations

As provider, primary consideration was paid to user data privacy. Because of the nature of OAuth, and our existing site authentication structure, DestinationRX had to make some structural permissions modifications to accommodate varying points of entry from the consuming organization to accommodate various states of authentication. Some decisions we made were:

1. Requests made during existing authenticated sessions were assumed to be from the authenticated user.
2. Requests made without an existing authenticated session required independent login within the request stream.
3. Traffic to consuming site originating from providing site is unidentified with respect to consuming site. As such, there exists the possibility of a one-to-many relationship between a user account on the Provider account and the Consuming site.

Top

Flow Overview (Screenshots)

1) View Partners at PharmaSURVEYOR:

2) Click on "Link Accounts and Survey My Meds" for DestinationRx which takes the user to the DestinationRx Login Screen:

3) After logging in choose to share medications list and click button to Link:

4) User is taken back to the PharmaSURVEYOR site with the user's medications from their DestinationRx Medicine Cabinet:


Top