When to Use OAuth »

In our daily talks with customers about their APIs, OAuth has become a major consideration. It's quickly replacing the various proprietary "authentication token" schemes used by early APIs (such as the Amazon Web Services APIs) with a flexible standard; and it solves for new use cases emerging from mashups and Web 2.0. Still, there is a lot of confusion about OAuth out there.

Based on the current state of the technology, we know that there are different API use cases. Depending on your security needs, sometimes OAuth is the only security technology an API can realistically support. In others cases, it may be overkill, or something to add alongside another scheme.

OAuth Overkill?        

OAuth is overkill for an API that doesn't require strong authentication. Many "catalog" and "search" APIs that access public data fall into this category. The goal of an API like this is to gain adoption. There's no reason for such an API to require individual users to authenticate to retrieve information from a product catalog, or search public data. (Unless, of course, your API's business model revolves around data that is so valuable that you can get away with charging for every data access. In today's world, that's not common.) A simple API key, however, is a great idea for these kinds of APIs, integrated into your API analytics so you and your developers can see what's going on.

The Case for OAuth

OAuth is the only realistic choice for a web application that itself uses another web application's API on behalf of the user. For instance, consider a web application that integrates with Twitter. (Perhaps it's a geolocation app like Foursquare that offers the ability to tweet where you are and what you're doing.) Today, it is unacceptable for such a web application to store its users' Twitter passwords. OAuth was designed precisely for this use case -- it gives the web app a secure way to get an access token for Twitter, which the user can revoke at any time, without ever revealing that Twitter password to the web app.

Basic Auth- Still Important

In most cases OAuth should be one of two or three security choices for most APIs. Again, consider Twitter. It makes perfect sense for OAuth to be used by other web apps as a way to access Twitter. But Twitter has long supported "Basic" HTTP authentication as well, using a username and a password. While this is bad news for a web application client, for a mobile or a desktop client that is used by an individual user, it's just fine as long as the client takes some care with the password.

And importantly, Basic authentication is easy. If your API requires secure authentication, and you want it to be easy to integrate and test, then offering Basic authentication means that the barrier to entry is low.

Now, once the decision to use OAuth has been made, the question is whether to use the current version 1.0a, or the still-under-development OAuth 2.0. We'll talk about that next.

When to Use OAuth »

In our daily talks with customers about their APIs, OAuth has become a major consideration. It's quickly replacing the various proprietary "authentication token" schemes used by early APIs (such as the Amazon Web Services APIs) with a flexible standard; and it solves for new use cases emerging from mashups and Web 2.0. Still, there is a lot of confusion about OAuth out there.

Based on the current state of the technology, we know that there are different API use cases. Depending on your security needs, sometimes OAuth is the only security technology an API can realistically support. In others cases, it may be overkill, or something to add alongside another scheme.

OAuth Overkill?        

OAuth is overkill for an API that doesn't require strong authentication. Many "catalog" and "search" APIs that access public data fall into this category. The goal of an API like this is to gain adoption. There's no reason for such an API to require individual users to authenticate to retrieve information from a product catalog, or search public data. (Unless, of course, your API's business model revolves around data that is so valuable that you can get away with charging for every data access. In today's world, that's not common.) A simple API key, however, is a great idea for these kinds of APIs, integrated into your API analytics so you and your developers can see what's going on.

The Case for OAuth

OAuth is the only realistic choice for a web application that itself uses another web application's API on behalf of the user. For instance, consider a web application that integrates with Twitter. (Perhaps it's a geolocation app like Foursquare that offers the ability to tweet where you are and what you're doing.) Today, it is unacceptable for such a web application to store its users' Twitter passwords. OAuth was designed precisely for this use case -- it gives the web app a secure way to get an access token for Twitter, which the user can revoke at any time, without ever revealing that Twitter password to the web app.

Basic Auth- Still Important

In most cases OAuth should be one of two or three security choices for most APIs. Again, consider Twitter. It makes perfect sense for OAuth to be used by other web apps as a way to access Twitter. But Twitter has long supported "Basic" HTTP authentication as well, using a username and a password. While this is bad news for a web application client, for a mobile or a desktop client that is used by an individual user, it's just fine as long as the client takes some care with the password.

And importantly, Basic authentication is easy. If your API requires secure authentication, and you want it to be easy to integrate and test, then offering Basic authentication means that the barrier to entry is low.

Now, once the decision to use OAuth has been made, the question is whether to use the current version 1.0a, or the still-under-development OAuth 2.0. We'll talk about that next.

Tech Talk: API Security and Threat Protection »

Greg recorded a few whiteboard talks last month - this one is a good summary of recent posts on API Keys, API security recommendations, and OAuth best practices. 

(And here are some of our high-level API security features if you are looking into this.)

Don’t roll your own: API Security Recommendations »

Let's boil up the examples and common pitfalls from our last two entries on API Identity and Authorization and more API security choices.   

Use API Keys for non-sensitive data (only): 

If you have an “open” API - one that exposes data you’d make public on the Internet anyway -  consider issuing non-sensitive API keys. These are easy to manipulate and still give you a way to identify users. Armed with an API key, you have the option of establishing a quota for your API, or at least monitoring usage by user. Without one, all you have to go on is an IP address, and those are a lot less reliable than you might think. (Why don’t web sites issue “web site keys?” Because they have cookies.)

For example, the Yahoo Maps Geocoding API issues API keys so it can track its users and establish a quota, but the data that it returns is not sensitive so it’s not critical to keep the key secret.

Use username / password authentication for APIs based on web sites: 

If your API is based on a web site, support username/password authentication. That way, users can access your site using the API the same way that they access it using their web browser. For example, the Twitter API supports username/password authentication, so when you access it using a Twitter API client like Spaz or TweetDeck you simply enter the same password you use when you use the twitter.com web site.

However, if you do this, you may want to avoid session-based authentication, especially if you want people to be able to write API clients in lots of environments. It is very simple to use “curl,” for instance, to grab some data from the Twitter API because it uses HTTP Basic authentication. It is a lot more complex if I instead have to call “login,” and extract a session ID from some cookie or header, and then pass that to the real API call I want to make...

OAuth for server-to-server APIs that are based on web sites:

If your API is based on a web site (so you already have a username / password for each account) and the API will also be used by other sites, then support OAuth in addition to username / password authentication. This gives users a lot of peace of mind, because they can authorize another site to access their sensitive data without giving that site their password permanently.

Use SSL for everything sensitive:

Unless your API has only open and non-sensitive data, support SSL, and consider even enforcing it (that is, redirect any API traffic on the non-SSL port to the SSL port). It makes other authentication schemes more secure, and keeps your user’s private API data from prying eyes – and it’s not all that hard to do.

Don’t roll your own!

If the above suggestions still don’t apply to you, then keep looking – between OAuth, OpenID, SAML, HTTP authentication, and WS-Security, there are a lot of authentication schemes, and each has its pros and cons.

So wrapping up API security in our series on 10 API roadmap considerations. Here are some suggested questions you may want to ask when putting together your API security roadmap:

How valuable is the data exposed by your API?

• If it’s not that valuable, or if you plan to make it as open as possible, is an API key enough to uniquely identify users?
• If it is valuable, can you reuse username and password scheme for each user?
• Are you using SSL? Many authentication schemes are vulnerable without it.

What other schemes and websites will your API and users want to integrate with?

• If your API will be called programmatically by other APIs, or if your API is linked to another web site that requires authentication, have you considered OAuth?
• If you have username/password authentication, have you considered OpenID?
• Can you make authorization decisions in a central place?

What other expectations might your customers have?

• If your customers are enterprise customers, would they feel better about SAML or X.509 certificates?
• Can you change or support more than one your authentication approach for diverse enterprise customers?
• Do you have an existing internal security infrastructure that you need your API to interact with?

Up next:  API Data Protection and thanks to Torbin H. for the photo.

Do you need API keys?  API Identity vs. Authorization »

(This is part 3 in our series on "Is your API naked? 10 API Roadmap considerations")

We’ve seen very few API providers with a completely open API – almost all employ at least one of these:

• Identity - who is making an API request?
• Authentication - are they really are who they say they are?
• Authorization – are they allowed to do what they are trying to do?

Do you need them all?  Maybe not.  Some APIs only need only to establish identity and don’t really need to authenticate or authorize.

API Identity vs. Authentication - Compare Google Maps and Twitter  

Take Yahoo and Google maps – they are fairly open.  They want to know who you are but they aren’t concerned what address you are looking up. So they use an “API key” to establish identity, but don’t authenticate or authorize. So if you use someone else’s API key, it’s not good but not a serious security breach.

The API key lets them identify (most likely) who is making a API call so they can limit on the number of requests you can make. Identity is important here to keep service volume under control.

Then take Twitter’s API -  open for looking up public information about a user, but other operations require authentication. So Twitter supports both username/password authentication as well as OAuth. Twitter also has authorization checks in its code, so that you cannot “tweet” on behalf of another user without either their password or an OAuth key to their account. This is an example of an API that implements identify, authentication and authorization.

The “API Key” – do you need one? 

API keys originated with the first public web services, like Yahoo and Google APIs.  The developers wanted to have some way to establish identity without having the complexity of actually authenticating users with a password, so they came up with the “API key,” which is often a UUID or unique string. If the API key doesn’t grant access to very sensitive data, it might not be critical to keep secret, so this use of the API key is easy for the consumers of the API to use however they invoke the API.

An API key gives the API provider a way to (most of the time) know the identity of each caller to maintain a log and establish quotas by user (see the last section). 

Usernames and Passwords – again, see Twitter

With more sensitive data a simple, API key is not enough, unless you take measures to ensure users keep the key secret. An alternative is username/password authentication, like the authentication scheme supported by the vast majority of secure web sites. 

It’s easiest to use “HTTP Basic” authentication that most websites use. The advantage of using this technology is that nearly all clients and servers support it. There is no special processing required, as long as the caller takes reasonable precautions to keep the password secret.

Twitter simplifies things for their users by using usernames and passwords for API authentication.  Every time a user starts a Twitter client, it either prompts for the username and password to use, or it fetches them from the disk (where it is somehow scrambled or encrypted where possible). So here it makes a lot of sense to have the same username / password for the Twitter API that it used for the web site.

Usernames and passwords also work well for application-to-application communications. The trick - the password must be stored securely, and if it’s being used by a server, where do you store it?  If you are running an application server that uses a database, you already have solved this same problem, because the database usually requires a password too. Better application server platforms include a “credential mapper” that can be used to store such passwords relatively securely.

There is a lot we'd like to write about around security so we'll split this up into a couple entries.  Next time:  Session-based authentication, OAuth, SSL and WS-Security, and rolling your own.