A simple OAuth client

We’ve talked about OAuth in a few posts now, so I thought it might be a good idea to try some of this out for real. (My other motivation is that we’re adding OAuth to Blaze, so I promised Richard I’d have a client for when he’s ready for testing).

I decided to start with a simple web based client and see how far I got.

From a technology perspective, Javascript and Node.js is my preferred language, so I created a simple node server that is going to act as my OAuth ‘client’ which I can then use to call different OAuth servers. The overall architecture looks a bit like this:

A pretty basic web application, which serves up HTML pages to the browser, and communicates separately via HTTPS (of course!) to the OAuth servers. Because it’s a ‘secure’ application (the code runs on the server and not in the users browser)  it can use the ‘authorization code’ flow (or grant).

For my library I chose to use the node module ‘simple-outh2’ which exposes simple methods to make the required OAuth calls.

The first experiment is against Google. Google uses OAuth2 to authorize access to its services – in effect Google hosts both Authorization and Resource servers in the OAuth2 model, so should be quite straight forward.

First step is to establish credentials that the client can use to Authenticate against the Authorization Server (ie the client ID and client secret), which I got from the Developer website.

Then the app is quite simple:

var request = require('request');   //https://github.com/mikeal/request
var path = require('path');
var express = require('express'),
    app = express();

app.use(express.cookieParser());
app.use(express.session({secret: '1234567890QWERTY'}));
app.use(express.static(path.join(__dirname, 'public')));

var OAuth2;

var credentialsGoogle = {
    clientID: "<myclientid>",
    clientSecret: "<mysecret>",
    'site': 'https://accounts.google.com/o/oauth2/',
    'authorizationPath' : 'auth',
    'tokenPath' : 'token'
};

// Initial call redirecting to the Auth Server
app.get('/auth', function (req, res) {
    OAuth2 = require('simple-oauth2')(credentialsGoogle);
    authorization_uri = OAuth2.AuthCode.authorizeURL({
        redirect_uri: 'http://localhost:3001/callback',
        scope: 'openid email https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/tasks',
        state: '3(#0/!~',
        access_type: "offline"      //causes google to return a refresh token
    });

    res.redirect(authorization_uri);
});

// Callback endpoint parsing the authorization token and asking for the access token
app.get('/callback', function (req, res) {
    var code = req.query.code;

    OAuth2.AuthCode.getToken({
        code: code,
        redirect_uri: 'http://localhost:3001/callback'
    }, saveToken);

    function saveToken(error, result) {
        if (error) {
            console.log('Access Token Error', error.message, error);
            res.json({'Access Token Error': error.message});
        } else {
            //see what we've got...
            console.log(result);
            //this adds the expiry time to the token by adding the validity time to the token
            token = OAuth2.AccessToken.create(result);
            //save the response back from the token endpoint in a session
            req.session.token = result;

            //perform the res of the processing now that we have an Access Token
            gotToken(req,res);
        }
    }

    //Now the token has been received and saved in the session, return the next page for processing
    function gotToken(req, res) {
        res.sendfile(__dirname +"/public/main.html");
    };

});

//get the lists for the current user...
app.get("/tasks", function (req, res) {
    //Need a token to access the google services
    if (req.session.token) {
        var AT = req.session.token["access_token"];
        var url = "https://www.googleapis.com/tasks/v1/users/@me/lists";

        var options = {
            method: "GET",
            headers: {
                "content-type": "application/json+fhir",
                "authorization": "Bearer " + AT
            },
            rejectUnauthorized: false,      //to allow self-signed cetificates
            uri: url
        };

        request(options, function (error, response, body) {
            res.json(body);
        });
    } else {
        res.json({err:"Not logged in"});
    }

});

app.listen(3001);

console.log("OAuth Client started on port 3001");

1. The flow starts by calling the /auth endpoint – line 21 above – (I had a simple <a> tag in the front page). This initialises the OAuth2 object with the required credentials – and the location of the Authorization and Token endpoints, and then re-directs to Authorization Server with the required parameters (like scope, state and others). You can find the details on the Google site.
2. Google then serves up a login page showing what scope you are after (eg accessing google drive and tasks) and the user logs in and authenticates the request. (If you’re logged in to google services separately it remembers who you are – which can be a bit disconcerting at first).
3. Assuming all goes well, then the browser will eventually be redirected back to the local callback endpoint (http://localhost:3001/callback – line 34 in the example above) which extracts the Authorization code from the reply and requests an Authorization Token from Google.
4. Once that’s done we save the token (actually the whole response from the Token request) and serve up another HTML page.
5. Now, the user can access the Google resources – an example is the /task endpoint (line 67) which will get the task lists for the current user.

Interestingly, the access_type value of ‘offline’ in line 27 above is supposed to cause Google to include a Refresh Token in its response – which doesn’t seem to be happening for me, so I need to look into that. It means that when the Access Token expires, then the user should have to re-authenticate – though that didn’t seem to be happening. It may be that Google is doing something clever on the backend…

Oh, and if you look at the response that comes back from the server when you get a Authorization Token, you’ll see an id_token as well. Because we put ‘openid’ in the scope property, Google will also implement OpenId Connect and return Identity data as well.

So, as you can see, the library abstracts much of the complexity of OAuth away – and I presume that  the libraries in other languages act in a similar fashion.

But – this is a rather simple flow where both Authorization and Resource servers are served up by the same app – which can then do all sorts of clever things on the back end. What happens when they are on different servers?

We’ll look in to that soon…

FHIR: Securing an ecosystem

In our previous discussions on OAuth2 and OpenID Connect, we’ve talked about how the Authorization Server can authenticate a user, and provide an ‘Access Token’ that a Resource Server (e.g. a FHIR server) can use as a basis of deciding what information it can supply and what services it will allow. (As an aside, a reminder that the FHIR spec does talk about how this could be implemented – and also points out the IHE IUA profile (formal spec) as work in this area that is worth following).

Things are – relatively – straightforward when each server supports its own authentication, but gets a lot more complex when you try to support an ‘ecosystem’ of different servers. Let’s have a look at a couple of the issues:

• How does a Resource Server know that a particular Access Token is valid (both that it’s a valid token and hasn’t expired)
• How can the Authorization server pass the ‘scope’ of access to the Resource Server (where the scope is what the patient – also called the Resource Owner – has agreed to)

To provide a backdrop for our discussion lets provide a picture of a simple ecosystem – i.e. where there are multiple separate servers performing the various roles.

To keep things (relatively) simple, we’re going to assume that we want a single Authorization Server for our ecosystem. In fact, this is kind of like the IHE XDS Affinity domain concept, where you have:

 “a group of healthcare enterprises that have agreed to work together using a common set of policies and share a common infrastructure”

The difference being that the affinity domain has a single Registry – in our case we have a single Authorization Server. It isn’t always going to work out this way, but it’s a good starting point. (btw this picture comes from a presentation I’m giving to our National Standards Organization this week to show how these standards could work together in New Zealand).

Here’s our ecosystem:

So we have:

• An Authorization Server backed up by some databases for identifying patients and providers (This is so that the Authorization Server can also serve up Identity (Patient and Provider) – as we talked about last time. It’s not significant in the context of this discussion).
• A FHIR Profile and ValueSet registry. This is a FHIR based ecosystem, and we’re bound to want to define profiles, ValueSets and extensions. Of course, we will very likely use other registries as well, especially for the HL7 defined extensions, but one of our own is likely to be required.
• A Record Locator Service. This is serving the role of an XDS Registry and holds DocumentReference resources that can be queried as we’ve previously discussed.
• A couple of Resource Servers, one directly holding resources  and the other ‘proxying’ to an existing Medical Records system.

Trusting the Access Token.

The question is simple. When one of the Resource Servers gets an Access Token, how does it know it’s valid and how does it know what scope of disclosure the User (Resource Owner) has agreed to?

When the Authorization Server and the Resource Server are the same application, this is straight forward – in the process of issuing the Access Token, the Authorization Server can save the details in a local cache which it can reference when the Resource Server receives it in a request. But when the Token needs to be used by multiple different servers it becomes a lot harder.

A couple of options come to mind (and I’m sure there are others of course).

• The Authorization Server could make its cache of valid Tokens available to Resource Servers via a secure ‘back channel’ of some sort. (e.g. a Redis server holding valid tokens in memory keyed by the Token with the expiry set to the token expiry). When the Resource Server receives a request it queries the cache to confirm validity and retrieve scope information)
• The Access Token could actually be a more complex structure than a simple Bearer Token – for example it could be a JWT (JSON Web Token) that contains the expiry time and the scope and signed by the Authorization Server. This would require that the Resource Servers have the Authorization Server’s public key – but as there are unlikely to be that many Resource Servers, this probably isn’t a big problem.

Which to choose (or some other)? Well, that will be up to the implementation (or the agreements in the “Affinity Domain”). In either case, the bulk of the complexity is with the server rather than the client – which is where we want it to be. (In the diagram above, the dotted lines represent this relationship – whether a direct query or indirect via the key).

Defining the scope.

We’ve glossed over this a bit in previous discussions.

When the user initially authenticates to the Authorization Server, they can supply the details of what information they are allowing the application to retrieve from the Resource Server/s on their behalf. This is called the ‘scope’ of the request and is defined in the OAuth2 spec as follows:

The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.  The strings are defined by the authorization server.  If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope.

So, we need to decide what is the level of access granularity that we want to support, how we’re going to represent that and then make sure that all participants in our ecosystem support them. No small task as there is no agreed standard for this.

Some possibilities from Grahame:

• Read any data
• Read any data not labelled confidential
• Read/write
  • Medications
  • Allergies
  • Conditions
  • Other clinical

But you can see that this is going to provide some thought. (Incidentally, there are a number of people looking into this – if you’re interested then drop me a line).

It should also be apparent why having a single Authorization Server does simplify things. In principle there is no reason why you can’t have more than one – but preferably they will all need to support the specific implementation requirements – such as the type of Access Token and the codes used for scope. There are doubtless ways of accommodating ones that can’t, but it does add complexity – and therefore risk – to the overall solution.

I have to say I kind of like the analogy with these questions and the IHE Affinity Domain concept. Although there will likely be some standardization in the future, there are always going to be differences in specific implementations, so this concept is a nice way of wrapping all the specific details up for a specific implementation (or, in the case of New Zealand – maybe the country!).