We’ve recently written a number of blog posts on APIs covering the basic areas like making use of HTTP, URIs, JSON and CSV, as well as on the topic of more complex subjects like how to iterate.
There are further API subjects we’ve yet to cover though, like how does the server ensure the client is who it claims to be. In this post we’ll explore some of the ways we can help the client prove its identity.
Why you need to authenticate
There’s a number of reasons why your service may need to consider authentication approaches. You may want to identify clients for purposes of:
- rate limiting/throttling
- auditing
- billing
- authorisation
Your purpose will dictate security requirements for your authentication solution. For example, when identifying clients for rate limiting purposes, you’ll have less incentive to regularly refresh user tokens since a token getting into the wrong hands is unlikely to threaten your service. In many cases, particularly those around open data, you’ll want to avoid authentication altogether to maximise use.
This post focuses on authenticating for authorisation purposes as opposed to authentication for rate limiting, auditing and billing because that’s our most common use case at the moment within the Government Digital Service (GDS).
OAuth 2
At GDS we tend to use the open authorisation standard OAuth2 as a means to authenticate unless the severity of threats to the API calls for a different method.
OAuth2 is an authorisation framework that lets applications get limited access to user accounts on an HTTP service. The service gives each registered application an OAuth2 Bearer Token, which can be used to make API requests on the application’s own behalf (the token is not tied to a specific individual).
For example GOV.UK Pay uses these OAuth2 HTTP Bearer Tokens. When making API calls, users will need to add their token to the "authorisation" HTTP header, as described in the GOV.UK Pay documentation.
Doing OAuth2 well
The major drawback of OAuth2 is that the tokens are often long lived, and the same ones can often provide access to multiple resources. This leads to vulnerabilities because if an attacker steals a token, they can do anything a user can do. Tokens can be stolen from the servers, or from the intermediary network security devices that proxy the Transport Level Security (TLS) - these are common in government departments.
So when using OAuth2 for authentication it’s important to do it well, for example by ensuring the access tokens refresh regularly. This is where refresh tokens come in, which carry the necessary information for the application user to get a new access token from the authorisation server. The user will find they have to use a refresh token whenever their access token has expired or if they need access to a new resource.
The challenge of refreshing tokens is that it can be hard for development teams to justify the time it takes to generate these new tokens to product managers. This means refresh tokens are commonly left unimplemented but it’s important for development teams to convey their importance in order to fully secure a service.
Also, sometimes people don’t realise how important these tokens are. When providing an OAuth2 secure API, remind your users to treat the tokens as sensitively as they would any passwords. You can also make sure the tokens you provide have the narrowest permissions possible (in terms of what users can do with their token). Narrowing the permissions means there’s a much lower risk to your API if they are lost by users or compromised.
There’s other steps your service can take to make your use of OAuth2 more secure. You need to monitor your APIs for unusual behaviour just like you’d closely monitor any website. So you need to look out for things like changes in IP addresses or clients using APIs at unusual times of day. The cleanliness of your API security practices is only as good as your day-to-day security protocols.
If you have assessed the risk of token interception to your service and you have decided the risk is not something you can take then it’s worth considering other authentication options.
Other authentication options
Having assessed the risk of token interception to the Notify API, we realised we wanted to try an approach that didn’t use even regularly refreshed Bearer Tokens. We experimented with a range of different options as described in this blog post. The post mentions some of the trade offs we’ve had to make when using other authentication approaches.
While exploring these other options we continue to track the progression of the proof-of-possession security mechanism that the Internet Engineering Task Force’s (IETF) OAuth Working Group has focussed on. When using JSON Web Tokens (JWT), a client can cryptographically confirm their receipt of a token without sending anything over a network. The OAuth Working Group aims to bring this additional security protection to OAuth2. This increased focus on standards by the international community is likely to improve our authentication options in the future.
Over to you
We’re interested to hear what others are doing in this area of authentication, particularly when it comes to authorisation. Whether you’re part of the government, industry, a standards body or just interested in the subject, please get in touch by leaving a comment in the section below or by visiting our standards discussion site on GitHub
We know that we can't do this alone. Your contributions are vital to helping us make the right choices. We're building guidance fit for the 21st century and we need input from smart, creative, and technically astute people. There is also value in working together and coordinating our activities so we can influence technology standards and the work of bodies such as the IETF.
You can follow David on Twitter, sign up now for email updates from this blog or subscribe to the feed.
If this sounds like a good place to work, take a look at Working for GDS - we're usually in search of talented people to come and join the team.
