loading...
Cover image for What are the best practices for architecting API authentication?

What are the best practices for architecting API authentication?

brentonhouse profile image Brenton House Updated on ・4 min read

Ask-a-Geek: Answers to Frequently asked API and Mobile Questions (6 Part Series)

1) How do I add a custom font to my mobile app for iOS and Android? [SOLVED] 2) What are the best practices for architecting API authentication? 3 ... 4 3) API-First, Mobile-First, Design-First... How do I know where to start?? 4) How do I take a screenshot inside mobile app for iOS and Android? 5) How can my Titanium iOS app detect that a screenshot has been taken? 6) How do I add the Star Wars intro to my iOS and Android mobile apps?

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.

Auth Comments
JWT Uses a JWT to authenticate. Easy to setup and use but user must manually manage token creation, etc. More secure alternative to API Keys.
OAuth 1.0a Less secure than OAuth 2.0. Just use OAuth 2.0
SAML Used for some SSO system. Difficult to use and manage for APIs

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.

About Brenton House
With 25 years of experience in the development world, Brenton House leads Developer Relations for Axway's API and mobile products, He has worked closely with many clients across various industries including broadcasting, advertising, retail, financial services, transportation, publishing, supply chain, and non-profits. Brenton's passion for everything API and mobile combined with his strategy and design experience, has enabled him to help developers create captivating products that inspire and delight audiences.

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

Ask-a-Geek: Answers to Frequently asked API and Mobile Questions (6 Part Series)

1) How do I add a custom font to my mobile app for iOS and Android? [SOLVED] 2) What are the best practices for architecting API authentication? 3 ... 4 3) API-First, Mobile-First, Design-First... How do I know where to start?? 4) How do I take a screenshot inside mobile app for iOS and Android? 5) How can my Titanium iOS app detect that a screenshot has been taken? 6) How do I add the Star Wars intro to my iOS and Android mobile apps?

Posted on by:

brentonhouse profile

Brenton House

@brentonhouse

API and Mobile Strategist with 25+ years in dev community. Head #DevRel Geek at Axway and host of Breaking the Build YouTube series.

Discussion

markdown guide