Dossia OAuth Developer Guide

From Dossia Wiki

Jump to: navigation, search

Contents

What is OAuth?

OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications. Dossia uses the OAuth protocol for authenticating applications accessing Dossia API services. This document describes Dossia's implementation of OAuth with instructions on how to use it.

  • For more information about OAuth, we encourage you to read the OAuth Web Site.
  • Dossia has implemented the OAuth 1.0 protocol. Excellent documentation on OAuth is available on the OAuth Web Site at http://oauth.net/core/1.0.
  • We would strongly advise developers to make use of existing OAuth implementation libraries. OAuth maintains a list of libraries at http://oauth.net/code.

Authentication

All Personally Controlled Health Records (PCHR) API calls are authenticated with OAuth. Only Dossia registered applications can access the Dossia API via OAuth. The OAuth protocol protects our users by not exposing their usernames and passwords to third party applications and provides a security token-based solution for allowing users to control who can access their personal health information.

The only way a Dossia API client can successfully make an API call and read or write data is if the client has obtained an OAuth access token. Should a user choose to prevent an application from accessing their data they can revoke access at any time to that particular application by simply logging into their Dossia account and removing the applications share from their account. This process will revoke the token and API calls will not succeed.

Please note that once a Request token is generated it is valid for 30 minutes only. Access tokens do not expire, however a user may invalidate it by revoking access (in which case a HTTP 401 error status will be returned).

Registering Your Application

Dossia follows stringent guidelines with regard to which applications and organizations will be able to access the Dossia API. To be able to make OAuth requests to our API you will need to obtain a consumer key and secret. Organizations participating in Dossia's partner program may request OAuth a consumer key and secret.

Requests to obtain a consumer key and secret should be be emailed to apisupport@dossia.org.

Please include the following information in your email.

  • Application Name - Marketing name of your application Web Site.
  • Company Logo - Your official corporate logo to fit within a space 100 pixels wide by 40 pixels high. Acceptable file formats are PNG, GIF, and JPEG.
  • Company Name - Your consumer brand.
  • Corporate Web site - A link to the home page of your Web Site.
  • Web Site Name - The name of the application Web site.
  • Web Site Address - A link to the home page of the application Web site.
  • Web Site Description - A short description of the application Web Site. This description should be limited to 30 words.
  • Web Site Screen Shots - Some sample screen shots of the application Web Site with a short five-word descriptive caption for each. Should be limited to three screen shots and should be in full color and fit within a space 150 pixels wide by 100 pixels high. Acceptable file formats are PNG, GIF, and JPEG.
  • License Agreement - A link to the legal terms that appear on the application Web Site profile page. This URL should link to the terms on your site that applies to your application.
  • Privacy Statement - A link to the Privacy Statement that appears on the application Web site profile page. This URL should link to the privacy statement on your site that applies to your application.
  • Detailed information - More detailed information and links about the application can appear on the Web Site profile page. The information should be relevant to the benefits of how the Web site works with Dossia, and should be limited to 300 words.
  • Customer Support Contact Information - Support contact information (phone/e-mail/URL) that Dossia Customer Support can refer customers to when appropriate.


A sample email is shown below. 

To: apisupport@dossia.org
Subject: OAuth Consumer Key and Key Request

Please set up OAuth consumer keys and secrets for the following environments:
www.testapp.company.com
  Environments: staging, development, production
Application Name-  Marketing name of your application Web Site.

Company Logo - 

Company name - 

Corporate Web Site -  

Web Site Name -    

Web Site Address -   

Web Site Description - 
  
Web Site Screen Shots - 
 
License Agreement -   

Privacy Statement -  
 
Detailed information -  

Customer Support Contact Information -

In response, Dossia will provide a key and secret for the requested environments. Each environment will have a different key and secret. Please take measures to keep both the key and the secret secure.

Dossia OAuth URL Endpoints

The following URL endpoints are available from Dossia for development, staging and production environments.

Each environment advertises four endpoints.

  • request - returns a request token.
  • authorize - is used for authorizing the user.
  • access - returns an access token.
  • ping.jsp - is implemented as a convenience for monitoring purposes and returning the server time.

Development 

https://dev-oauth.dossia.org/authserver/request_token
https://dev-oauth.dossia.org/authserver/authorize
https://dev-oauth.dossia.org/authserver/access_token
https://dev-oauth.dossia.org/dossia-restful-api/ping.jsp

Staging 

https://staging-oauth.dossia.org/authserver/request_token
https://staging-oauth.dossia.org/authserver/authorize
https://staging-oauth.dossia.org/authserver/access_token
https://staging-oauth.dossia.org/dossia-restful-api/ping.jsp

Production 

https://oauth.dossia.org/authserver/request_token
https://oauth.dossia.org/authserver/authorize
https://oauth.dossia.org/authserver/access_token
https://oauth.dossia.org/dossia-restful-api/ping.jsp

OAuth Parameters

Below is a summary of the parameters used in Dossia's OAuth implementation. The Dossia OAuth authentication workflow expects the standard OAuth parameters. In all instances, please supply the parameters in the HTTP Authentication Header, separating them with commas. An example is supplied below 

Authentication : OAuth
oauth_consumer_key="demoConsumerKey"
oauth_nonce="623689630650334",
oauth_timestamp="1242937422",
oauth_signature="VPcIhoSC13NwNodtdUTpbLawF9M=",
oauth_token="7fae057bfc6f973bf96d722997112700",
oauth_signature_method="HMAC-SHA1",
oauth_version="1.0"

The oauth_token and oauth_token_secret are essentially a username and password, as are the consumer_key and consumer secret. Third party applications should protect these as strongly as possible.

  • oauth_callback - A URL and any associated query parameters to call back to your application's web site once the user has authorized or refused access.
  • oauth_nonce - A randomly-generated string of characters that, once validated help to prevent replay attacks.
  • oauth_signature_method - The cryptographic method all Dossia OAuth clients will use to sign requests. Always send HMAC-SHA1, in upper-case letters.
  • oauth_version - The OAuth protocol version being used. Always send 1.0 unless directed by Dossia in the future to use a different version.
  • oauth_timestamp - The number of seconds elapsed since midnight, 1 January 1970 using UTC. Please ensure that the time stamp is accurate to within 15 minutes of Dossia's server timer. If you are having problems with times try https://dev-oauth.dossia.org/v2.0/dossia-restful-api/ping.jsp to find the time the server is using.
  • oauth_token - The applicable OAuth token
  • oauth_consumer_key - The Dossia supplied key.
  • oauth_token_secret - Dossia generates a secret to be associated with a token with Request and Access token generation. This secret should be kept by the consumer and used when generating the oauth_signature.
  • oauth_token_signature - The signature is made up by creating a base string containing the request type, the request URL and parameters (sorted into order) and then a digest value is generated. If you are generating your own code for this and not using an existing OAuth library the OAuth specification should be consulted, see http://oauth.net/core/1.0/#sig_base_example.

The Dossia OAuth Implementation

Below is a diagram showing the call sequence between Dossia's OAuth server and a consuming application. It is important to understand that Dossia uses OAuth's three legged implementation in all cases.

File:Oauth_dance.png

Step A - Obtaining a Request Token

The user is logged into a Consumer PHA Application The user initiates a request to allow the Consumer to access medical information in their Dossia account. The Consumer application performs a server to server call (via HTTP POST to the request URL) and requests an OAuth Request Token from Dossia with the following parameters in the HTTP authorization header:

  • oauth_consumer_key: demoConsumerKey
  • oauth_nonce: 622988456550902
  • oauth_timestamp: 1242936721
  • oauth_signature: 1tcvh7P9v37foaZevhQLPVJdyJA=
  • oauth_signature_method: HMAC-SHA1
  • oauth_version: 1.0

Step B - Dossia Supplies a Request Token

Dossia validates the request and returns a request token. Dossia returns:

  • oauth_token_secret: f4372c7e7c05fa5e60af46d902328884
  • oauth_token: 512eb7cf025289d786df1967f892fba3

Step C - User Browser Session Redirected to Dossia

Dossia directs the user's browser to the Dossia OAuth authentication URL and provides:

  • oauth_token: 512eb7cf025289d786df1967f892fba3
  • oauth_callback: http://localhost:8080/democonsumer/OAuth/Callback?consumer=consumer1

Dossia then redirects the user to authenticate themselves. As part of authentication the server displays to the user the application that is requesting access and the type of data they will access. The user authenticates with their username and password. A further screen may ask the user to acknowledge share agreements between themselves and the Consumer application if a share agreement isn't in place already.

Step D - Dossia Supplies an Authorization Token

Upon successful authentication Dossia grants an authorization token associating the user with the Consumer application. The user browser session is redirected to the Consumer application. Dossia then returns:

  • oauth_token: 512eb7cf025289d786df1967f892fba3

Step E - Consumer Application Requests Access Token

The Consumer application performs a server to server call to Dossia via HTTP Post to the Dossia access URL to obtain an access token with:

  • oauth_consumer_key: demoConsumerKey
  • oauth_nonce: 623411049835454
  • oauth_timestamp: 1242937144
  • oauth_signature: Q2UUx4k4tQowpE76MCjcVxeAc/Q=
  • oauth_signature_method: HMAC-SHA1
  • oauth_token: 512eb7cf025289d786df1967f892fba3
  • oauth_version: 1.0

Step F - Dossia Grants Access Token

Dossia validates the request and ensures that user has authorized access. If all is well Dossia swaps the authorization token for an access token and sends the following back in response:

  • oauth_token_secret: 8a20e50ff45a83b3547b48fb60ed3b43
  • oauth_token: 7fae057bfc6f973bf96d722997112700

Step G - Consumer Application Starts Accessing the Dossia API

The Consumer application accesses the Dossia API. Dossia validates the request and ensures the we only provide data the application is authorized to access.

  • oauth_consumer_key: demoConsumerKey
  • oauth_nonce: 623689630650334
  • oauth_timestamp: 1242937422
  • oauth_signature: VPcIhoSC13NwNodtdUTpbLawF9M=
  • oauth_token: 7fae057bfc6f973bf96d722997112700
  • oauth_signature_method: HMAC-SHA1
  • oauth_version: 1.0


The Dossia API returns the following HTTP status codes for every request:

  • 200: Ok.
  • 302: User redirected back to Consumer application.
  • 400: Parameters are absent or supplied ones are invalid.
  • 401: Token parameters are invalid. A user may have revoked access.
  • 500: Internal Server Error
  • 502: Bad Gateway: Returned if Dossia API is down or being upgraded.
  • 503: Service Unavailable: User declined access, or the consumer key is invalid.
Retrieved from "http://docs.dossia.org/index.php/Dossia_OAuth_Developer_Guide"
Personal tools