What are the best practices for architecting API authentication?

Dear Geek,

We are building an API and I am confused as to what kind of security we need? There are so many out there being used (OAuth 1.0a, OAuth 2.0, SAML, username/password, API Key, JWT, and plenty of others) and I am not sure what the best practices are for implementing authentication for our APIs. What advice to you have?
 

  —   OVERWHELMED BY SECURITY OPTIONS

Dear Overwhelmed,

There really are a lot of options for security when designing and architecting APIs but I can help you narrow down things and point you to some best practices for choosing authentication options for your APIs!

API Strategy

There are several things to take into consideration when looking at security for APIs and it is important to make sure it aligns with your organizations overall security strategy.

Let's look at a few of the most frequently used methods of API authentication.

No Security

You may be thinking about opening up your API to everyone with no security. I would not do this. Even if you data is non-sensitive and you may not care who sees your data, you should be thinking about rate limiting in order to protect your resources.

Look instead at using API Key, which I talk about next.

API Key

This is an option if the data you are presenting is non-sensitive. An API Key is a unique value generated for use by an API client. API Key is not really authentication as it is a way of filtering requests by client. You still have no idea who is using your API with that API Key. Adding an API Key requirement to your API will at least allow you to limit the number of requests per registered client.

Allowing the client to reset the API Key is an important feature as the key might become compromised.

Most APIs will require true authentication which is when a lot architects find themselves looking at OAuth 2.0 which I cover next.

OAuth 2.0

You will see this form of Authentication used on a lot of APIs. This involves an end user authenticating and getting a token that can be used by the client to then authenticate with your API. I won't go into details here as the OAuth 2.0 process can be challenging to understand if you're new to this. I will tell you that there are several different OAuth flows and you will need to work with your OAuth 2.0 provider to see which flows they support. OAuth 2.0 does have flows that support server-to-server communication but not all organizations and providers will have these flows enabled.

The one downside to some OAuth 2.0 flows is that it can get pretty ugly. You probably have some awesome designs showing a nice branded login flow for your app or website. But the reality is you will get thrown out of that into something much less branded before completing and getting back to your app.

The other downside is the additional screens themselves. Depending on what the timeout is for your app or website. You might have 3-5 screens and a whole lot more clicks just to open a link.

There is not much you can do about the downsides as security is more important than aesthetics.

My only point to pointing out the downsides is that you do want to be aware of what OAuth 2.0 flows are supported (and enabled) for your API and what it means for your clients if they are turned off.

Username/Password

Some APIs authenticate with username and password, often in the form of Basic Auth in the header. Even when combined with SSL, this is not a recommended solution for securing your API. You will often see this with older APIs that were created using a webpage paradigm. This also often led to APIs being created that were session based (or worse, session based with cookies).

Speaking of session-based APIs. Please don't do this! RESTful APIs are designed to be stateless!

If you are thinking about doing this, first see if your API falls into the one exception to this rule:

THERE IS NO EXCEPTION.

Don't do it.

For the love of all that is good. Just don't.

Others

Here are a few of the other authentication methods you might find out there.

Recommendations

• Use OAuth 2.0 but with flows enabled to support server-to-server, device authorization, etc. so you can ensure your API Client are secure while also enabling a great user experience!

• Use API Key authentication with caution if publishing non-sensitive data

• Avoid username/password authentication.

• Avoid maintaining state in your API calls.

Ask-a-Geek questions are answered by Brenton House, an API and Mobile Geek who has been working in dev community for 25+ years.