Auth Schemes of REST API. Policies, Key management, Security, and... | by Bibhash Biswas | Towards Data Science

The user’s data is the underlying currency that is driving the API economy. Like any currency, you need to handle it with care and transport it with caution to prevent theft.
Different devices and platforms have different vulnerabilities. Your desktop at home is not as vulnerable as your mobile phone. It’s easier to lose your phone. Someone can get access to the local files stored by the apps on your mobile. This changes the authentication and authorization flow for mobile apps.
Similarly, for single page web apps (SPA), the entire Javascript can be viewed as a source. You don’t want your credentials as part of your local data storage in your SPA.
There are many security models. Many ways to authenticate depending on the device and the usage. The different ways to authenticate are called schemes.
There is no one way to secure your API that fits all situations. But, you can learn the schemes, study how the biggest social networks are dealing with it and find out the industry standard; then apply it to your project in the way you see fit.
The 4 main schemes of REST API authentication are-
Basic AuthenticationToken Based AuthenticationAPI Key Based AuthenticationOAuth (Open Authorization)
Basic Authentication
Token Based Authentication
API Key Based Authentication
OAuth (Open Authorization)
You may have noticed that the OAuth says authorization instead of authentication. These two terms are not interchangeable. We’ll talk about the differences later in this article.
At the end of this article, you’ll have a clear understanding of the different schemes.
Before we get into the schemes, let’s talk about a few foundational concepts that are needed to build on the discussion.
Authentication is the art of unlocking things with a secret. At the heart of every authentication is a shared secret!
Your pin number for your ATM card is a shared secret between you and the Bank.
Your combination for your lock box at your bank is another shared secret.
Your password for logging into your email is a shared secret between you and the email provider.
The secret can be given to you, like a secret code to enter a night club, or you can generate the secret and store it with the system like your pin number for your bank card.
Either way, the secret has two copies. One copy is with the system and the other copy is with you. Your copy is called the private key.
Do you have any control over the copy that’s with the system? No, but that copy stored on their servers is not readable by another human being or by another machine. The server only has a highly encrypted version of your secret; it doesn’t know what the decrypted value would look like. It might take a few 1000 years for the server to decrypt it.
That’s why if you forget your password, you’d need to reset it. You can find out how long would it take to crack a password here.
Your front door lock is public. Anybody can come up to your front door and try your lock with their key but only your key would open it. While your key is private, the lock of your house is public.
In the digital world, the key is called a key, and the lock is also called a key. So there are two keys; one is your copy of the secret- your private key, and the other is the public key that’s accessible to anyone. This is the public/private key pair.
e.g. anyone can go to hotmail.com, and type in your email address but unless they have your password (your private key), they can’t login.
There are different ways to manage all the private keys you’ll end up owning, and there are different methods of storing them so they’re not easily compromised.
Figuring out ways to steal your private key is part of the job description of a hacker, and figuring out ways to manage, store, and transmit keys securely is part of the job of the API; either directly or through a 3rd party API management service.
Factors authenticate you by who you are, what do you know, and what do you have.
In addition to username and password, authentication can include additional information called factors.
Single Factor — this is the username and password that we talked about. This is the “who you are” type of auth.Two Factor — Along with the username and password, you need to answer another secret question that you set up while signing up. So you have 2 secrets keys. One for who you are and the other for what you know.Multi-Factor Authentication (MFA) — this is the hardest to crack. You use your secret key, and you set up a secret location for the server to send you another secret key. When you use your first secret key, the server sends you another secret key to the secret location that you mutually agreed on during the sign-up process (usually people set this as their phone number or their email address). This second secret key is usually valid for only a few minutes. Within that timeframe, you’ll need to use this second secret key to log in. This takes care of who you are, and what you have (the cell phone) type of auth.Biometric authentication — this is the fingerprint ID that is becoming a common part of authenticating on the mobile. My Dell laptop that I’m writing this article on has biometric authentication for logging in. I have to run my index finger on the power button to be able to log in. This is an automated “who you are” type of auth where you’re not required to manually type in a username and password.Captchas — there are two kinds. One where you have to decipher the squiggly words that you see and type those in. The other where you have to identify mountains, or cars, or storefronts, or any number of things in a grid of pictures. These are the most annoying ones, and I hope they go away soon. Sometimes the squiggly words are so convoluted that I have to ask for a second set, and then turn on the audio to hear them.
Single Factor — this is the username and password that we talked about. This is the “who you are” type of auth.
Two Factor — Along with the username and password, you need to answer another secret question that you set up while signing up. So you have 2 secrets keys. One for who you are and the other for what you know.
Multi-Factor Authentication (MFA) — this is the hardest to crack. You use your secret key, and you set up a secret location for the server to send you another secret key. When you use your first secret key, the server sends you another secret key to the secret location that you mutually agreed on during the sign-up process (usually people set this as their phone number or their email address). This second secret key is usually valid for only a few minutes. Within that timeframe, you’ll need to use this second secret key to log in. This takes care of who you are, and what you have (the cell phone) type of auth.
Biometric authentication — this is the fingerprint ID that is becoming a common part of authenticating on the mobile. My Dell laptop that I’m writing this article on has biometric authentication for logging in. I have to run my index finger on the power button to be able to log in. This is an automated “who you are” type of auth where you’re not required to manually type in a username and password.
Captchas — there are two kinds. One where you have to decipher the squiggly words that you see and type those in. The other where you have to identify mountains, or cars, or storefronts, or any number of things in a grid of pictures. These are the most annoying ones, and I hope they go away soon. Sometimes the squiggly words are so convoluted that I have to ask for a second set, and then turn on the audio to hear them.
Authentication and Authorization are two different things.
Authentication gets you logged into the server. Authorization gets you access to the resources on the server.
And You, are the resource owner. You give your resources to a server to store. Resources like your personal details, hobbies, your purchases, your desires, wants and needs (wishlist on Amazon), your location data, your relationship status, your anniversaries, your spouse’s details, the name of your kids, grandkids, their pictures, birthdays...that and a lot more of your life-data that you’ve given to, for example, Facebook!
Other apps that need to have access to that data will need your permission.
Authentication happens before Authorization. Just because you’ve logged in doesn’t mean you have access to everything.
Authentication is negotiated with usernames, passwords, and other factors we talked about. Authorization is negotiated based on policies on the account e.g. administrator or user, power user, guest...etc.
In a REST API, sending in the credentials once and logging in is not enough. REST is stateless as we discussed in this article. Being stateless, the REST API can’t remember your credentials. So you have to tell it who you are every time you talk to it!
Keeping that in mind, let’s dive into the schemes in order of their level of sophistication.
This is the most simple way of securing your API. Have the user type in a username and a password to identify themselves every time you send in a request.
In the standard HTTP specification, there is an Authorization header field that can be used for this purpose. The username and password are encoded with Base 64 encoding. Anybody intercepting that data en route to the server would see a long line of gibberish. Though, Base 64 encodings can be easily decoded in less than a second.
The interceptor can copy that gibberish and stick it into an online decoder to get back your username and password. This is called a Man-In-The-Middle (MiTM) attack. They could be sitting in a coffee shop with wifi set up with the name of the coffee shop. You may not notice the difference and connect to them instead. Now all your data is flowing through their laptop.
This is why basic authentication is well... basic.
For mobile apps and single-page apps, basic authentication is not a good scheme because you don’t want to store the username and the password on the device or in the Javascript code of the SPA.
For mobile and SPA, you can use token-based authentication instead.
In this scheme, the user will type in their username and password (credentials), and the server will generate a token based on those credentials.
The server then sends this token out to the user.
Now the user doesn’t need to send in login credentials with every request. Instead, they just send in the encoded token, and the server validates the token.
There are ways to encode date and time into this token so someone intercepting the token cannot re-use it after a certain time.
The user will need to pass this token through either the header, body, or as a query parameter when it calls on an endpoint to access resources.
The most popular format for tokens is JSON Web Tokens (JWT). The fields of the token are key/value pairs. The keys are called claims. The claims essentially tell the API what the values are supposed to mean. You can find a list of all the standard claims in RFC 7519
Here is an example of the JWT claims set. The aud field is the audience claim and tells the server that it contains the client ID. If this is missing then this token will get rejected.
{   "iss": "http://www.mysite.com",   "aud": "Client Secret",   "name": "first last",   "email": "firstlast@mysite.com",   }
JWT Tokens are negotiated based on the OpenID Connect protocol (OIDC).
The token can be set to expire after a certain amount of time so users will need to log in again. Tokens can also be revoked on the server-side if there has been any compromise.
In this scheme, the client that needs access to the resources needs to register itself with the API. The API generates a Key and a Secret for each registered client. These are then stored with the server, and a copy of these are sent to the client. The client will need to pass these in when they try to connect.
For example, if you need a developer to go in and write part of your app, then you can generate this key and the secret, and give it to them. If you need to hand out keys to many developers you’ll need to manually set things up. The problem is that this is hard to scale.
Another issue with the API key and client secret is the key management. You’ll need to provide a way for them to —
a. Generate the key and secret
b. Send it to them — this can be done via email or display it in their developer account on the API
c. Secure the key and secret
It can get complicated to be able to store and manage keys. That’s why some organizations prefer to hire a 3rd party service to do this. There are many API management tools available from IBM, Microsoft, and other vendors like Akana, Apigee, etc. Here is a list of the top 10 API management tools.
If you want to do it yourself instead of hiring a 3rd party service, you’ll want to automate the key generation and exchange so you can scale. The need for this automation is one of the main reasons an authorization framework like OAuth was developed.
OAuth automates the key generation and exchange. When an app needs your permission/authorization to access data on your behalf it’ll ask you to log in to the API provider.
Let’s run through a real-life example. If you want Joe to have access to your personal bank account to be able to withdraw funds, here’s how you’d “OAuth” Joe in this scenario.
You go to the bank, show your ID —(authenticate yourself )Tell them you want Joe to have access to your account — (authorize Joe)Give the bank Joe’s email address so the bank can send Joe an access token —(API Provider calls a website redirect URI with the access token in the response body)Joe brings the access token to the bank along with his ID — (client authenticates themselves and presents access token)The bank grants Joe access to your account — (API provider grants client access to your resources)
You go to the bank, show your ID —(authenticate yourself )
Tell them you want Joe to have access to your account — (authorize Joe)
Give the bank Joe’s email address so the bank can send Joe an access token —(API Provider calls a website redirect URI with the access token in the response body)
Joe brings the access token to the bank along with his ID — (client authenticates themselves and presents access token)
The bank grants Joe access to your account — (API provider grants client access to your resources)
In this article, you learned about a few different authentication factors like Single, Two-Factor, and Multi-Factor authentication.
We went over the difference between authentication and authorization so now you know even if the terms are thrown around loosely sometimes they are fundamentally very different.
We talked about the different authentication schemes like basic authentication, tokens, JWTs, API Keys, and OAuth2.0
At this point, you should have a good overview of the ways to secure your API. If you want a deep dive into the topics we touched on here, here are some references —
RFC6749- The OAuth 2.0 Authorization Framework
RFC2617- HTTP Authentication: Basic and Digest Access Authentication
RFC7235- Hypertext Transfer Protocol (HTTP/1.1): Authentication
RFC7519- JSON Web Token (JWT)