RESTful API Authentication Basics

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.

i know that it is a bit confusing that in rest apis we are using the authorization header for doing authentication (or both) but if we remember that when calling an api we are requesting an access to certain resource it means that the server should know whether it should give access to that resource or not, hence when  developing and designing restful api  authorization header sounds just fine.

basic authentication

the most simple way to deal with authentication is to use http basic authentication. we use a special http header where we add 'username:password' encoded in base64.

get / http/1.1
host: example.org
authorization: basic zm9vomjhcg==

note that even though your credentials are encoded, they are not encrypted! it is very easy to retrieve the username and password from a basic authentication. do not use this authentication scheme on plain http, but only through ssl/tls.

hmac

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.

another way is to use hmac (  hash-based message authentication  ). instead of having passwords that need to be sent over, we actually send a hashed version of the password, together with more information. let's assume we have the following credentials: username  username  , password  secret  .

suppose we try to access a protected resource:

/users/username/account

first, we need to fetch all the information we need and concatenate this.

get+/users/username/account

here, we just concatenate the http verb and the actual url. we could add other information as well, like the current timestamp, a random number, or the md5 of the message body in order to prevent tampering of the body, or prevent replay attacks. next, we generate an hmac:

digest = base64encode(hmac("sha256", "secret",     "get+/users/username/account"))

this digest we can send over as a http header:

get /users/username/account http/1.1
host: example.org
authentication: hmac username:[digest]

right now, the server knows the user "username" tries to access the resource. the server can generate the digest as well since it has all information.

please note that the "password" is not encrypted on the server, as the server needs to know the actual value. this is why the name "secret" is preferred and not a "password."

even if a hacker was listening in on the conversation, they could not use the authentication information to post data to user's account details, or look at some other users accounts or any other url, as this would change the digest and the hacker does not have the secret that both the server and client has.

however, the hacker could access user's account whenever it wants since it doesn't change the digest. this is why many times more information is sent over, like the current time, and a nonce:

digest = base64encode(hmac("sha256", "secret", "get+/users/username/account+20apr201312:59:24+123456"))

we added two extra pieces of information. the current date and a number that we only use once (nonce)

get /users/username/account http/1.1
host: example.org
authentication: hmac username:123456:[digest]
date: 20 apr 2013 12:59:24

the server can reconstruct the digest again since the client sends over the nonce and date. when the date is not in a certain range of the current servers time (say, 10 minutes), the server can ignore the message, as it probably is a replay of an earlier send message (note: either that, or the server or clients time is wrong. this is a common issue when dealing with time-limited authentications!).

the nonce is a number we only use once. if we want to access the same resource again, we must change this number. this means that every time we access a resource, the nonce will be different, and thus the digest will be different, even if we access the resource in the same second. this way we are sure that no replay attacks can be done. each request is only valid once, and only once.

OAuth 2.0 or OAuth 1.0

a little history

in december 2007, oauth 1.0 addressed delegation with a framework based on digital signatures. it was secure and it was strong. major players began to adopt it. google began oauth 1.0 support in 2008. by 2010, twitter forced all third-party apps to use their oauth 1.0 implementation.

however, oauth 1.0 required crypto-implementation and crypto-interoperability. while secure, it was a challenge for many developers to implement.

then came oauth 2.0 in october 2012.

building a secure oauth solution is no easy challenge. large enterprises joined the oauth standard body and influenced it in many ways. while oauth 2.0 is much easier to implement than oauth 1.0 with its crypto underpinnings, the new version contains many compromises at the security level.

however, support for non-browser implementations and a clear separation of resource delivery and authorization helped make the new standard more usable for large enterprises and more.

in many cases, it is no longer feasible to use oauth 1.0 as a client-side implementer. for example, google moved away from oauth 1.0 in april 2012, and no longer permits the use of oauth 1.0. however, twitter still fully supports oauth 1.0. for more information,  click here  .

it is very rare to see new authorization server implementations of oauth 1.0. however, you can still consider oauth 1.0 if your resource provider still supports it (and has committed to continue supporting it), you have developers with good experience in cryptography, and you have good key management capabilities.

these are a lot of “ifs,” and oauth 2.0 is almost always the right choice today. if your desire is to use oauth with proper cryptography, the trend is more and more to use oauth 2.0 with cryptographic extensions. if you are  designing and developing a new api  , oauth 2.0 is your choice!

still wondering what to do? compare the security properties of both versions and decide which is right for your implementation.

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

1. the client application registers with a provider such as twitter.
2. twitter provides the client with a consumer secret unique to that application.
3. the client app signs all oauth requests to twitter with its unique consumer secret.
4. if any of the oauth request is malformed, missing data, or signed improperly, the request will be rejected.

note: some use the oauth 1.0 scope parameter to carry authorization/entitlement in addition to the token; that can be a useful architecture consideration.

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.
•  flexible.  : oauth 1.0 only handled web workflows, but oauth 2.0 considers non-web clients as well.
•  better separation of duties.  : handling resource requests and handling user authorization can be decoupled in oauth 2.0.
•  basic signature workflow  .

example workflow:

1. the client application registers with a provider such as twitter.
2. twitter provides the client with a client secret unique to that application.
3. the client application includes the client secret with every request.
4. if any of the oauth request is malformed, missing data, or contains the wrong secret, the request will be rejected.

see also

please keep in mind that basic authentication and oauth versions must be protected through ssl/tls. they should not be used over plain http.

authentication is stating that you are who are you are and authorization is asking if you have access to a certain resource. when working with rest apis you must remember to consider security from the start.

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.