Unless your API is a public feed of read-only data, you likely need authentication. There are many options you could choose, which may vary depending on your use case. However, it’s unlikely you’ll need to go out and create your own authentication method. Whenever possible, use a standard that is widely implemented. Otherwise, developers will spend more time than necessary figuring out how to get started. Plus, “creative” authentication can often lead to security issues.
We won’t mention every authentication option in this article, but we’ll cover three common approaches: OAuth, API Keys (and other tokens), and OpenID Connect.
OAuth for Accessing User Data
Gone are the days of users sharing passwords with API developers. This insecure practice has been replaced by an OAuth standard that is widely adopted. You can use OAuth for both authentication and authorization, terms that are easily confused.
A simple hotel analogy can help explain the difference. You give your driver license to the concierge, she reads your name and looks at your smiling face and photo. This is to determine your authenticity. Congratulations! You are now authenticated. The attendant then checks some records, returns you the smile and gives you a key card. In OAuth terms, she defined if you are authorized to stay in a hotel room, and gave you an access token for the resource.
OAuth can be used for authentication, but it was designed for authorization. You can use the keycard to access your room and amenities without confirming who you are again, the same as accessing resources with your OAuth token without copy-pasting keys or retyping passwords. Imagine the concierge writing your name and ID number on your card. Similarly, OAuth allows you to include your identity information as a claim in your token. You then prove your identity everywhere with the key.
OAuth makes your life easier and helps protect your passwords by using access tokens instead. But tokens themselves have to be protected.
API Keys and Other Tokens Must Be Secured
Microservices are now everywhere and so are API keys. You can use them with well-known callers when you don’t need granular permissions. Expanding on the hotel example, caretakers often have master keys opening every door. That practice itself is not insecure.
“Hey, what if such a super-key is stolen,” you might argue. Yes, we have a problem here. This is why API keys must be secured. Sniffed OAuth tokens are usually not as big of a risk, because they are often time-bound and can be scoped to specific areas of an API. Still, even if set to expire shortly, it can be used to perform a call or two on your behalf.
Sending keys or tokens unencrypted is like keeping those hotel key cards stacked on the counter. How you send your secrets also might be important. Headers or POST requests over an encrypted channel are proven ways to do it. The querystring, on the other hands, is subject to problems like bookmarking, screenshotting, or logging. OAuth2 access tokens, for instance, are sent inside a header. And always with SSL/TLS.
OpenID Connect Provides Identity Atop OAuth
As we’ve mentioned, OAuth is made for authorization. However. you can also send your identity information as a part of an OAuth token. There are advantages to letting OAuth focus on authorization and separating out the identity flow.
Again, let’s return to our hotel example. Remember the card the concierge gave you? It included your name and driver license number on it. If you lost that card bad things could happen. If your personal information was not on your card, it couldn’t be compromised. The same is true of your token.
Another standard can help us here. In this case, OpenID Connect. It employs battle-tested OAuth2 for authorization and adds a separate id_token for identity information. This way you avoid leaking user-specific information in access tokens. In addition, OpenID Connect is a standard, so all the implementations have to be compliant. You only need to know that a provider implements it to plug both authorization and authentication into your application.
When it comes to API authentication and authorization, choose standards and the best practices used across the industry. Don’t get creative, or you’ll make it difficult for developers to get started and easier for them to do the wrong thing.