Delving into SMART

While FHIR is not a security standard ‘per se’, there are numerous references in the spec to security related matters – including a specific module in the specification. One of the recommendations made is about SMART – a defined way to use the OAuth2 Authorization framework in FHIR. I recently gave a webinar on SMART, and part of the feedback was that it wasn’t enough detail for a developer to implement a solution – while this wasn’t really the focus of the presentation, it did make me realize that there will be a lot of interest in this from developers, so thought it might be useful to develop a SMART application – and call out the significant parts as we go.

I’m going to develop 2 applications.

• The first one (and the focus of the first few posts) is a SMART client that can talk to (hopefully) any SMART compliant server.
• Then – a ‘proxy’ server (kind of like a very simple API Manager) that exposes a SMART interface to a back end server (or database)

As always, the focus will be on showing people how things work (and learning the details myself) rather than building a production ready app. But I think that the client will also be useful to developers of SMART servers – or SMART compliant interfaces to existing data stores  – which is going to be a common use case.

There’s an instance running on the web that you can use for servers that are publicly addressable, but the code is fully open source and downloadable from github, so you can just install it locally for testing purposes if you want to. We’ll go into the details of the app in a subsequent post, but it’s basically just a nodejs application and doesn’t need any local databases, so just clone the repository into a local folder, and execute the local server called smartClientServer. Eg

chmod +x smartClientServer.js
./smartClientServer.js

Should do it.

Let’s start by taking a look at how the client works. Navigate to https://clinfhir.com/smartClient.html (note that this is https – ie an encrypted connection. For those interesting in such things I used letsencrypt to generate the SSL keys).

You should get a screen like this one:

To the left is the panel where you select the server you wish to call, and the right is an iframe currently showing some documentation.

The configuration data for the currently selected server is shown as a json object just below the server selector on the left – you can see it in more user friendly form (and edit / add others) by clicking on the Edit server list link to the upper right. Configurations you add are saved in the browser cache, which means that, strictly, it is not a ‘confidential’ client, which needs to be able to save this type of data in a protected place like the server. However, this approach is simpler than managing a server side database and should be OK for an educational/testing app…

By default there is a single server configured in the app – this is pointing to a SMART sandbox server defined by the SMART project at http://launch.smarthealthit.org This is a test site that allows you to configure a simple SMART server (albeit one with limited configuration options) and then access that server simply by navigating to a specific url. It also allows you to simulate various error conditions – which is quite useful when building a client. (Note that the callback url will always be localserver]/callback.)

To actually connect to the server, click the Login button alongside the selected server. This will start the OAuth2 ‘handshake’. As this proceeds, you will see various status messages in the left pane, and also forms will appear in the iframe.

Here’s a screenshot of getting to the login screen of the SMART server:

And this is the screen after a successful login:

(Note the messages in the left hand side).

Once you’re here, you can make any FHIR query that you’re authorized to make and the results will be shown in the query screen. Here’s an example of querying for all patient resources:

The process of negotiating access to the server uses the ‘scopes’ – we’ll talk more about that in later posts.

You may have noticed a tab labelled ‘Tokens’ in the query screen. This will show the response from the Authorization server  and the various tokens it returned. Again, we’ll talk more about these in  later posts

So feel free to have a play with the app – and let me know how you get on! I’ve not been able to test it on many servers, so I’m sure there are issues to address. If you do connect it to a server that is more rigorous, you’ll need to make sure that the configuration is correct.

The server will want to know:

• A client Id. You can use whatever you want – just make sure it is the same as the one you add in the app. In some cases the server might specify this.
• The callback url. For the web version this must be: https://clinfhir.com/callback
• If there is an option, then select the ‘confidential’ one.

It will then create for you a secret.

All of these will need to be added to the app as shown in the screen shot below:

And remember that the above configuration is just to convince the Authorization server that the app is kosher – you’ll still need a login of some sort to the Auth server (The second tab lets you store these for reference, but you’ll still need to enter them yourself.)

One ‘gotcha’ I have noted in that some servers include ‘X-Frame-Options’ in the header in their login form – meaning that the login can’t be shown in an iframe. There are good reason for this – though it is inconvenient as the browser will load a new tab which breaks the login (or at least stops the ability to report back on progress). One work around is to install a chrome plugin:

https://chrome.google.com/webstore/detail/ignore-x-frame-headers/gleekbfjekiniecknbkamfmkohkpodhe/related

which will cause the browser to ignore the header (actually it strips it out before the browser gets to it). This does seem to work – and should be OK for development I think…

Oh and only have a single tab open to the app at a time. The feedback in the left pane (which uses web sockets) is tied to the client IP address on the local server – if you open another tab then the connection will switch to that one…

The app is in github at – https://github.com/davidhay25/smartClient if you want to download it for yourself. I expect many changes coming up – I do want to work on the query capabilities in particular…

In the next post we’ll dive into the technical details of the app – and show how it manages the various calls required during the oauth2 handshake. After that, we’ll be able to start thinking about the server.