Health Intersections FHIR Server login documentation

OAuth documentation for Health Intersections FHIR Server

The server requires a login. You can login directly, or use OAuth.

Even if you don't login to the server, the server will automatically create a session, and if it can find a user resource with the provider URI "http://healthintersections.com.au/fhir/user/implicit" and a login name which is the IP the server see you as (after correcting for NAT, etc - you can get that from the FHIR status page from the server, top right), then it associates the user resource with the session.

For User resource document, see below

Session Limitations

Is the session is associated with a user resource, and the user resource lists one or more patients, the session will only be able to access resources in the patient compartments listed.

Direct Login

You can login directly to the server. If you are using a browser, you get a form that takes a login / password. When this form is submitted, the server attempts to find a user resource with no provider, and a login as specified. if it finds one, and the SHA256 hash of the password matches, then a session is created using the user resource as outlined above.

From a program, you can login automatically, by posting like this:

POST /svc/secure/fhir/login HTTP/1.1
Content-Length: 42
Content-Type: application/x-www-form-urlencoded

login=GrahameGrieve&password=TestPassword1

OAuth

The server can use OAuth to authenticate users through one of the following service providers:

• Google
• Facebook
• HL7 (this isn't quite OAuth but it looks pretty similar)

(to request others, ask Grahame)

Notes

• the server will ask for re-authentication when the OAuth login expires, or when it is restarted.
• the server only uses your id and your name, though it may sound as if it's asking for more details (I'm still trying to figure out how to ask for less and still get your name)
• at the moment, the only thing the OAuth login is used for is to use the users name for audit logging purposes (atom author, and in the security log event). The resource space may be compartmented in the future
• If there's an existing FHIR User resource with a matching provider number and id, then the user will automatically be associated with the session. Provider identifiers:
  • http://www.facebook.com
  • http://www.google.com
  • http://www.hl7.org
  • The id is the master identifier from the google / facebook / hl7. You might need to look at the security events created by your login to figure out what the id is.

Logging in through a browser

If you are using the web interface through your browser, you will simply be asked to login using the classic web method. There's no further documentation to add

Using OAuth in an application

The FHIR API isn't a user-focused API - its for use in the background behind the service. The simple case is where the application needs to authenticate the user to the FHIR server. You will need to able to host a browser as part of your process. The sequence of steps goes like this:

• make a request to the FHIR server
• get back a 401 error with an IssueReport
• the issue report will have one or more extensions providing url references to the login pages for various providers.
• pick one (at the moment, you have to figure out who the provider is by reading the domain from the url) (or get the user to pick one)
• show the user a browser pointed at the url of interest, and they walk through the login process)
• alternatively, when you get a 401 error, bring up a browser, and repeat the same request as originally made, but with an accept: text/html header)
• once the OAuth process is complete, you get redirected back to healthintersections.com.au for the Authorising request
• the Authorising request will be processed by the Health Intersections server, and then a redirect issued. You can let the browser handle the Authorising request, and capture the redirect, or you can capture the first and do the Authorising request directly from your code
• the response to the Authorising request includes a cookie by the name of fhirSessionCookie which must be included for all authorised calls.
• you need a user/browser session to handle the dialog between the user and the identification service provider

Real World Cases

Unfortunately the simple case above isn't very real world. The user isn't generally interested in the FHIR server at all. So the question is how to log user into the server without involving them directly.

The Health Intersections server supports two different scenarios:

• Front-end OAuth
• no OAuth in the picture

Using FHIR at the backend with OAuth at the front

In this scenario, the application the user is interacting with authenticates and authorises the user using one of the OAuth service providers above, and shares the authentication details with the Health Intersections Server.

In principle, the sequence goes like this:

• application logs user in using OAuth, and gets an access_token
• application calls http(s)://hl7connect.healthintersections.com.au/svc/secure/fhir/auth-login?[parameters]
• the health intersections server checks the token and returns the cookie as above

Parameters to the auth-login call:

• provider=[facebook|google]
• access_token=[token] as generated by OAuth
• id_token= (in the case of google)
• expires=[] expires in seconds (as provided by OAuth)

Notes:

• this means that the health intersections server gets the same access as the source application, but all it will do is query for id, name, and email address
• since the information that the Health Intersections server handles is publically available, it is happy to accept the access_token on the non-SSL channel. But if the token is a real token (likely) you might not want to send it on a non-secure login
• If no expires= is provider, the health intersections server will time out the session as specified. if no value is provided, the session is good for 30min

Logging in without using OAuth

In this scenario, the application the user is interacting with authenticates and authorises the user directly to the health intersections server.

In principle, the sequence goes like this:

• application logs user in however it wants
• application calls http(s)://hl7connect.healthintersections.com.au/svc/secure/fhir/auth-login?[parameters]
• the health intersections server checks the token and returns the cookie as above

The parameters to the auth-login call:

• id=[] - a consistent id that identifies this user consistently
• name=[] - the current display name for the user
• appid=[] - an agreed value (contact Grahame)

User Resource

This is a custom extension supported by HL7Connect to allow users to define a user and associate the user with one or more patient compartments. Here's an example User resource (XML):

 <User xmlns="http://hl7.org/fhir">
   <text>
     <status value="generated"/>

Internal User Grahame Grieve has patient-level access to some specific patient compartments

   </text>

   <name> 
     <text value="Grahame Grieve"/>
   </name>
   <login value="GrahameGrieve"/> 

   <password value="c669ebcc10ad2fdc08b5f688d0638f07905040d49e3fbfdc498775b3a2ea67f4"/> 

   <level value="patient"/> 

   <patient>
     <type value="Patient"/>
     <reference value="patient/@example"/>
   </patient>
 </User>