RESTful API Authentication Mechanism

Authentication vs Authorization

The distinction between authentication and authorization is important in understanding how RESTful APIs are working and why connection attempts are either accepted or denied:

Authentication is the verification of the credentials of the connection attempt. This process consists of sending the credentials from the remote access client to the remote access server in an either plaintext or encrypted form by using an authentication protocol.

Authorization is the verification that the connection attempt is allowed. Authorization occurs after successful authentication.

In other words, Authentication is stating that you are who are you are and Authorization is asking if you have access to a certain resource.

Consequences if an API lacks security

Why do APIs even need authentication? For read-only APIs, sometimes users don’t need keys. But most commercial APIs do require authorization in the form of API keys or other methods. If you didn’t have any security with your API, users could make unlimited amounts of API calls without any kind of registration. Allowing unrestricted requests would make a revenue model for your API difficult.

Additionally, without authentication, there wouldn’t be an easy way to associate requests with specific user data. And there wouldn’t be a way to protect against requests from malicious users that might delete another user’s data (such as by making DELETE requests on another’s account).

Finally, you couldn’t track who is using your API, or what endpoints are most used. Clearly, API developers must think about ways to authenticate and authorize requests made to their API.

Overall, authentication and authorization with APIs serves the following purposes:

Authenticate calls to the API to registered users only

Track who is making the requests

Track usage of the API

Block or throttle any requester who exceeds the rate limits

Apply different permission levels to different users

Different types of authorization

There are several methods for authorization. The following are various types of API authorization you might encounter:

API Keys

Basic Auth

HMAC

OAuth

1. API keys

Most APIs require you to sign up for an API key in order to use the API. The API key is a long string that you usually include either in the request URL or request header. The API key mainly functions as a way to identify the person making the API call (authenticating you to use the API). The API key might also be associated with a specific app that you register.APIs might give you both a public and private key. The public key is usually included in the request, while the private key is treated more like a password and used only in server-to-server communication

2. Basic Auth

Another type of authorization is called Basic Auth. With this method, the sender places a

1

username:password

into the request header. The username and password are encoded with Base64, which is an encoding technique that converts the username and password into a set of 64 characters to ensure safe transmission. Here’s an example of a Basic Auth in a request header

Authorization: Basic bG9sOnNlY3VyZQ==

APIs that use Basic Auth will also use HTTPS, which means the message content will be encrypted within the HTTP transport protocol. (Without HTTPS, it would be easy for people to decode the username and password.)

In Postman, you can configure Basic Authorization by clicking the Authorization tab, selecting Basic Auth from the drop-down selector, and then typing the username and password on the right of the colon on each row. The Headers tab will show a key-value pair that looks like this:

Authorization: Basic RnJlZDpteXBhc3N3b3Jk

Postman handles the Base64 encoding for you automatically when you enter a username and password with Basic Auth selected.

3. HMAC (Hash-based message authorization code)

One of the downsides of basic authentication is that we need to send over the password on every request. Also, it does not safeguard against tampering of headers or body.

HMAC stands for Hash-based message authorization code and is a stronger type of authentication, more common in financial APIs. With HMAC, both the sender and receiver know a secret key that no one else does. The sender creates a message based on some system properties (for example, the request timestamp plus account ID).

The message is then encoded by the secret key and passed through a secure hashing algorithm (SHA). (A hash is a scramble of a string based on an algorithm.) The resulting value, referred to as a signature, is placed in the request header.

When the receiver (the API server) receives the request, it takes the same system properties (the request timestamp plus account ID) and uses the secret key (which only the requester and API server know) and SHA to generate the same string. If the string matches the signature in the request header, it accepts the request. If the strings don’t match, then the request is rejected.

The important point is that the secret key (critical to reconstructing the hash) is known only to the sender and receiver. The secret key is not included in the request. HMAC security is used when you want to ensure the request is both authentic and hasn’t been tampered with.

HMAC Workflow

4. OAuth

OAuth is a bit of a strange beast. OAuth is not technically an authentication method, but a method of both authentication and authorization. When OAuth is used solely for authentication, it is what is referred to as “pseudo-authentication.”

OAuth 1.0

Transport-Independent. Security is not delegated to HTTPS/TLS.

Founded in cryptography, especially digital signatures. Digital signatures are used to prove the integrity and authenticity of a message. Digital signatures can ensure that a certain message was sent from a specific source and that the message and signature were not tampered with in any way. A signed message is tied to its origin. It cannot be tampered with or copied to another source, but client-side implementations can be especially complex.

Messages are each individually cryptographically signed. If a single message within the communication is constructed or signed improperly, the entire transaction will be invalidated

Basic signature workflow.

Example Workflow

The client application registers with a provider such as Twitter.

Twitter provides the client with a consumer secret unique to that application.

The client app signs all OAuth requests to Twitter with its unique consumer secret.

If any of the OAuth request is malformed, missing data, or signed improperly, the request will be rejected.

OAuth 2.0

Transport-Dependent. : Most security defenses are delegated to HTTPS/TLS. A typo, an improper TLS configuration, a failure to properly validate a certificate, or vulnerabilities in an underlying library can lead to a man-in-the-middle (MiTM) attack, compromising all OAuth communications.

Centered around bearer tokens. : These are easy for integration but not great for security. Bearer tokens do not provide internal security mechanisms. They can be copied or stolen but are easier to implement.

Easier. : OAuth 2.0 is much more usable, but much more difficult to build securely.

Example workflow:

Twitter provides the client with a client secret unique to that application.

The client application includes the client secret with every request.

If any of the OAuth request is malformed, missing data, or contains the wrong secret, the request will be rejected.

Conclusion

RESTful API often use GET (read), POST (create), PUT (replace/update) and DELETE (to delete a record). Not all of these are valid choices for every single resource collection, user, or action. Make sure the incoming HTTP method is valid for the session token/API key and associated resource collection, action, and record.

For example, if you have a RESTful API for a library, it’s not okay to allow anonymous users to DELETE book catalog entries, but it’s fine for them to GET a book catalog entry. On the other hand, for the librarian, both of these are valid uses.