For developers one of the most visible API gateway operations is key management. But dear reader this is not your father’s key management – the kind laden with X.509, PKI, and baroque foofaraw that security teams had to beg developers to implement. This is 2013 and the keys are OAuth access keys! And developers are asking us for the keys too, so what should we do?
Before we answer that question, for those of you who are not programmers, let’s describe these “access keys” in a little detail. OAuth is a method for authorizing clients (end users and client applications) to use the third party APIs served by the API gateway. It is essentially how developers give access to consumers without consumers needing to share information such as user name and password. OAuth relies upon a trusted identity service to vouch for the client and pass an authorization token to the API, which in turn gives the client access. OAuth enables four parties (a user or consumer, a client application created by a third-party developer, the owner of the APIs, and an identity service provider such as Google or Facebook) to cooperate onto deliver services.
As we have discussed, developers are not much keener on the theoretical underpinnings of different identity protocols than the consumers who use their applications. They just want to get their users access to the application so they can move on to more ‘meaningful’ development tasks – like building the client application itself… This shifts the responsibility of identity and authorization onto security teams, which is a new position for them to be in: managing the process instead of cleaning up afterward. Rather than engaging toward the end of a project to conduct a vulnerability assessment, security teams may select identity protocols to be used, establish identity requirements, and guide developers through the process of building them into their applications. This is an unusual collaboration between developers and security – in both degree and kind. The role of the security team as leader for a portion of the development process sets them up as a true design and development partner.
Key setup & distribution
Setting up keys can be handled in several different ways, but the process is typically initiated through self-service features of the gateway (we told you it’s not your father’s PKI). The developer registers their application and client(s). The steps of the OAuth protocol dance vary by implementation, but the core generally includes:
- Developer account: A master account for the developer, which could span multiple clients and services
- Client ID: The key that identifies the consumer and grants access
- Client secret: How the consumer authenticates
- Client types: Gateways use these to distinguish between different clients such as iOS and Android
- Resource: The URLs, redirects and other services the client is requesting access to
Once this bootstrap process is complete – whatever variation your API gateway uses – the client application developer should have everything they need. Once the client has their authorization access token they are able to call the APIs and access data with their token. Each subsequent call to the APIs protected by the API gateway includes an OAuth access token.
The tokens are passed along with every call from the client app to the API so the API can make access control decisions. This brings up an important part of OAuth’s value proposition: the process of acquiring a token and using a token are kept separate. One implication is that the enterprise security architect must ensure that though these two independent processes – token issuance and token usage – are separate, their policy and governance models are consistent. Users should only be allowed access to the APIs they are authorized for, and not to see other APIs or other users’ data. The access rights requested at token issuance must match runtime behavior.
Key verification services
Developers may not be that interested in identity protocols but they are all interested in whether their code works. Distributed applications are notoriously difficult to debug, so anything fundamental to operations must be tested. Once access keys are issued and ready for use the API gateway should offer testing tools to ensure there are no surprises at runtime. The API provider should actively help validate the client code to protect their API! There are a number of considerations:
Ensure a production-like system is available for testing. Any networked application must deal with a myriad of issues such as ports, routing, and redirects. A token cannot simply be appended to access and refresh requests – each variant of API usage requires its own test cases.
Make simple tools available – many APIs include simple cURL scripts to test applications. For example: “curl https://example.com/API/myservice -H 'Authorization: your OAuth access token'” The gateway should include several scripts to validate client usage of the API.
Provide documentation and guidance for more testing and debug functionality as needed for the client environment.
Key lifecycle management
OAuth isn’t magic security dust, and using it doesn’t make an application secure. API developers and consumers need to be clear on safe handling of OAuth tokens across their entire lifecycle. Some rules are straightforward, such as always use TLS/SSL. But most are context dependent, such as secure storage for tokens and safe handling of redirects.
Two operations that generally require special attention in security policy are refresh and revocation. OAuth access tokens provide shorter-lived access but can create long-lived sessions through with refresh tokens. The refresh token is effectively a protection against an access token being replayed. So each consumer may have two different types of tokens. Security policy makers should align these policies and make use of the separation between shorter-lived access tokens and longer-lived refresh tokens. Policy is not as simple as “one and done”.
In addition to refreshing sessions, access revocation requires consideration. Token revocation may seem minor but anyone who has lost their mobile device can say with authority that it is nice to be able to log into twitter.com and turn off access to your lost mobile phone so its clients no longer offer access to your accounts with cached OAuth keys. Token revocation services provide invalidation for OAuth tokens and help enterprises deal with API consumers which violate policy or otherwise need the plug pulled.
Our next post will discuss API implementation.
Comments