Dossia OpenID Consumer Developer Guide

From Dossia Wiki

Jump to: navigation, search

Contents

What is the Dossia OpenID Server?

OpenID is an open, decentralized, free framework for user-centric digital identity. Dossia uses OpenID to allow Dossia partner websites to authenticate Dossia users on that partner's own website. This is accomplished without Dossia users revealing their usernames and/or passwords on the partner website. For our users, this provides a single login experience with only one identity (username and password) to manage. For our partners this provides a simple, secure and open way to authenticate Dossia users on their system. The OpenID server can provide user attributes to the partner website which facilitate the setup of accounts on partner websites (demographic attributes like first name, last name, date of birth etc.

In order to be consistant with the terminoligy used in the OpenID 2.0 specification, we will refer to the Dossia OpenID server as the “Dossia OP” or Dossia OpenID Provider. Partner web servers which use the Dossia OP will be referred to as an “OpenID RP” or Relying Party. This guide is intended to assist those developing an OpenID RP that uses the Dossia OP to authenticate users.

Before You Begin

Developers should be familiar with the OpenID 2.0 specification before attempting to develop with OpenID. This section includes reference materials that we have found helpful. It also includes instructions on setting up a partner account. Finally this section specifies the OpenID endpoints you will need in order to connect to the Dossia production and staging environments.

OpenID Reference Materials

Setting Up A Partner Account

Realm

Dossia acts as an OpenID provider only to approved partners. Before you apply to be a Dossia OpenID Relying Party, we will need you to provide an OpenID realm. This realm is a URL of the form "https://www.example.com/path".

Unsolicited Assertion URL

Dossia will allow users who are already authenticated on the Dossia system to send a positive authentication assertion to a Dossia OpenID Relying party, containing their OpenID. This is known as an "unsolicited assertion", and it greatly enhances the user experience. If you wish to take advantage of this you must supply an Unsolicited Assertion URL. (This is often, but not always, the same url that handles openid authentication responses). Handling unsolicited assertions is covered elsewhere in the document.

Return URLS specified in OpenID requests must be the same as, or a "sub-url" of the realm URL. For example if the realm you supply to Dossia was "https://www.example.com/exampleService" then the return url that handles OpenID responses could be "https://www.example.com/exampleService", or "https://www.example.com/exampleService/somePath.php" but not "https://www.example.com/anotherService" or "https://anotherServer.example.com/anotherService/somePath.php". All Dossia OpenID realm urls must begin with “https”.

When you supply your OpenID realm(s) to Dossia, Dossia will supply you with sample user accounts on our development and staging environments. These will allow you to test your OpenID RP functionality.


Requests to setup an OpenID Relying Party account should be emailed to apisupport@dossia.org. A sample email is shown below. 

To: apisupport@dossia.org
Subject: OpenID Setup Request

Please set up the following realms for OpenID authentication:

  Realm: https://server2.example.com/
  UnsolicitedAssertionURL: https://server1.example.com/return_url
  Environments: staging, development

  Realm: https://server2.example.com
  UnsolicitedAssertionURL: https://server1.example.com/return_url
  Environment: production


Typically partners will supply us with one or more production realm(s) and one or more development/staging realms.

The Dossia OpenID Endpoints

The following URLs begin the openid discovery and authentication process

Discover URLs for Dossia's OpenID OPs

Service URLs for Dossia's OpenID OPs

Getting Started

The easiest way to get started using Dossia OpenID is to download one of our sample applications. Sample applications are posted to the Dossia Developer Community Sample Code Forum.

Dossia OpenID Overview

The Dossia server which handles OpenID requests is called the Dossia OP (OpenID Provider). Web servers which use the Dossia OP to authenticate Dossia users are called OpenID RPs (Relying Parties).

Dossia OpenID requests can be either “direct requests” or “indirect requests.” Direct requests are made from the OpenID RP to the Dossia OpenID. They should be HTTPS POSTs. Indirect requests are made via HTTPS redirects through the user's browser.


The request modes defined in OpenID 2.0 are:

  • “associate”
  • “checkid_setup”
  • “checkid_immediate”
  • “check_authentication”


In addition to these OpenID “modes”, OpenID RPs can perform a “discovery” request.


The sequence diagram below shows a typical login sequence using OpenID.


File:Openid_sequence.png


Discovery

In OpenID, discovery begins when a user enters their OpenID URL at an OpenID RP. The OpenID RP performs a (direct) HTTP GET on the web page at this URL and parses it to discover the location of the OpenID RP.

The production OpenID server for Dossia will always be https://openid.dossia.org. Performing discovery on this url will tell your OpenID RP that the Dossia OpenID OP is located at https://openid.dossia.org/openID.action.

For the staging environment, the OpenID server is always https://staging-openid.dossia.org. Performing discovery on this url will tell your OpenID RP that the Dossia Staging OpenID OP is located at https://staging-openid.dossia.org/openID.action.


The following fragment shows the relevant code at https://openid.dossia.org. 

<head>
 …
 <link rel="openid.server" href="https://openid.dossia.org/openID.action"/>
 <link rel="openid2.provider" 
       href="https://openid.dossia.org/openID.action"/>
 <link rel="openid2.local_id"
       href="http://specs.openid.net/auth/2.0/identifier_select"/>
 …
</head>


The attribute openid2.local_id has the value http://specs.openid.net/auth/2.0/identifier_select. This means that the identity of the user will be selected at the OpenID server (when the user authenticates.


The discovery phase is not essential, and may be skipped. If you know you will be authenticating against the Dossia OP, we recommend you simply configure your code to simply use https://openid.dossia.org/openID.action.

Establishing an Association

Associations are a way of establishing secret keys, such that messages can be securely signed. Signing requests and verifying the signature of responses is essential in ensuring that a request came from the server it purports to have come from, and has not been tampered with.

Dossia requires all OpenID associations use SHA-256 encryption for establishing shared secrets and for signing responses. If you use an OpenID library, it should contain a method for generating association requests, along with implementing a Diffie Hellman key exchange.

An association request is a direct request from the OpenID RP to the Dossia OP. It must be sent via a HTTPS POST from the OpenID Relying Party web server to the Dossia OP service URL. The form names and values are shown below. 

openid.assoc_type:HMAC-SHA256
openid.session_type:DH-SHA256
openid.mode:associate
openid.ns:http://specs.openid.net/auth/2.0
openid.dh_consumer_public:{this is a public key generated dynamically by the OpenID RP}


An example association response from the Dossia OP is shown below. 

ns:http://specs.openid.net/auth/2.0
session_type:DH-SHA256
assoc_type:HMAC-SHA256
assoc_handle:1243284070208-1
expires_in:1800
dh_server_public:AKm66VF6rZWODuC9HJbNMfXKHK1qRuZRhancMo9QmuYMjM8nxAYhI/1/j3fHXgIi2aC02Yy6zQLLH01xWjDoguMWS+hXSwBxQPEBso0S32GAnOsIPgv99PKviKRCFAiPjbR9A52cgycs9/I6P/fKK7cu2d/94UEX7e4FWpbttljU
enc_mac_key:jVnhG1yoaZLqiiJ0dwLphza1GUwpU1FAXFlTsLAqZRI=

The response above indicates that the association expires in 30 minutes (1800 seconds).


Authentication Using checkid_setup

A checkid_setup request is the normal way in which an OpenID RP initiates user authentication with OpenID. This request is an indirect request, meaning it is implemented as an HTTPS redirect. An example checkid_setup request is shown below. 

openid.ns.ext1:http://openid.net/srv/ax/1.0
openid.ext1.type.employee-id:http://openid.dossia.org/participant/employee-id
openid.ext1.mode:fetch_request
openid.identity:http://specs.openid.net/auth/2.0/identifier_select
openid.return_to:http://localhost:8080/openidrp/consumerReturn.action
openid.ext1.required:employee-id
openid.realm:http://localhost:8080/openidrp
openid.claimed_id:http://openid.dossia.org/
openid.mode:checkid_setup
openid.ns:http://specs.openid.net/auth/2.0


An example response is shown below: 

openid.ns:http://specs.openid.net/auth/2.0
openid.op_endpoint:http://localhost/openid-server/openID.action
openid.claimed_id:http://openid.dossia.org/?65711fe8660047de8187d9b4d9d51595
openid.response_nonce:2009-05-25T23:35:06Z0
openid.mode:id_res
openid.identity:http://localhost:8084/authserver/?65711fe8660047de8187d9b4d9d51595
openid.return_to:http://localhost:8080/openidrp/consumerReturn.action
openid.assoc_handle:1243293913468-1
openid.signed:op_endpoint,claimed_id,identity,return_to,response_nonce,assoc_handle
openid.sig:+RKbukZlGs5UsiZFJlIzkwJGNIWhfHUlqz7iq6J9Nlc=


In the response we see the OpenID http://openid.dossia.org/?65711fe8660047de8187d9b4d9d51595

This is the final OpenID that you use to identify this user. Dossia assigns a unique ID for each user and partner. Thus, for example, for Dossia partner X, the user johndoe might be identified as 65711fe8660047de8187d9b4d9d51595, while for partner Y, the identifier will be different.


Handling an unsolicited assertion (aka OpenID SSO) from Dossia

Once a user has opted into (installed) your application, the Dossia PHA will provide a link allowing a user to SSO over to your application. When the user click's on that link, they will be redirected to the "Unsolicited assertion URL" you provided us. Handling an unsolicited assertion response is almost identical to handling an OpenID login response (discussed earlier). The only differences are

  1. Instead of the return_url, realm, attributes and tokens being initialized by your application from a checkid_setup request, they are initialized from configuration information on the Dossia OpenID Server.
  2. There is no association used to sign the response. Therefore your application should send a "check_authentication" call, as specified in the OpenID spec Verifying Directly with the OpenID Provider.

As you can see from the sequence diagram below, your server will simply receive an (unsolicited response), and verify it.

File:Unsolicited-assertion.png

Using the OpenID OAuth Extension

For web applications that use Dossia's Oauth/REST api to access a user's record, Dossia supports the OpenID OAuth Extension. This extension instructs Dossia to include a pre-approved Oauth Request token in any positive checkid_setup response. A pre-approved Oauth Request token can be converted into an access token without the user having to log into Dossia again. This provides a much more seamless integration between Dossia and your application. The extension can also be configured as part of an unsolicited assertion (aka OpenID SSO). To demonstrate how this extension improves the user experience let us look at an example application that uses OpenID for authentication, and Oauth for access to a user's Health record. In our sample use case, a new user initiates an SSO from the Dossia Dashboard to the example application. The example application requires access to the user's health record.

  • Use Case 1: (not using OpenID Oauth Extension)
    • New user clicks on "Example Application" link. User is redirected and authenticated on Example Application Link. Example Application does not have an Oauth token for this user. Example requests a request token for the user. Since user has not approved this request token, the user is redirected to the Dossia login page.
    • User enters their username and password, and accepts terms and conditions for the access token. Request token is converted into an access token. Application can now function.
  • Use Case 2: (using OpenID Oauth Extension)
    • New user clicks on "Example Application" link. User is redirected and authenticated on Example Application Link. Example Application converts pre-approved request token to an access token (without the user having to type in a username and password again). Application can now function.

Attributes Available via OpenID

The following demographic attributes are available to assist in registering users.


Opt In/Out Notification (beta)

This section is under development and is for review purposes only. The final implementation of this section may change. Some clients wish to be notified immediately if a person opts into or out of their application. These clients will supply a notification URL. This will be called by our server when a user installs or uninstalls their application. The contents of the notification message will be the same as the unsolicited assertion url. The only difference will be the addition of a new attribute

http://openid.dossia.org/participant/isInstalled which will have a value of 'true' or 'false'.

Sample Code

Dossia OpenID FAQ

Answers to frequently asked questions about OpenID are available at Dossia OpenID FAQ.

Retrieved from "http://docs.dossia.org/index.php/Dossia_OpenID_Consumer_Developer_Guide"
Personal tools