View source for 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

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)