Health Intersections FHIR Server login documentation

OAuth documentation for Health Intersections FHIR Server

The server uses OAuth to secure access. You must login using OAuth, through one of the following service providers:

• Google
• Facebook

(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 the 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

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

The parameters to the auth-login call depend on the service provider.

• facebook: the parameter is access_token=[access token returned from facebook]
  • the access token must have the privilege to access the user's profile (HL7Connect will call https://graph.facebook.com/me?access_token=...)
• Google: the parameters are id_token=[id token returned from google as part of login]&id=[google id from https://www.googleapis.com/plus/v1/people/me?access_token=]&name=[displayName from same place]
  • the google approach is still under review

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)