Using OAuth2 API Service Authentication with Node.js

So, you’re working with a shiny new API service in your latest project, and while reading API documentation stumble across something worrying: “OAuth2 Client Credentials Authentication Required”.

Fear not, OAuth2 and the Client Credentials grant type are actually quite simple once you know what you’re working with.

Today I’m going to show you how to authenticate against an OAuth2 API service using Node.js.

What’s Up with OAuth2?

The OAuth2 protocol is pretty large and allows users to authenticate in several different ways. The OAuth2 protocol is broken up into separate “grant types”, which are each used in different authentication scenarios.

I’ve written about OAuth2 in detail before, so if you want to know everything about the protocol, you might want to start by reading this.

But, today we’re talking about authenticating against API services with OAuth2 — this means we’re going to be discussing the Client Credentials grant type!

The Client Credentials grant type is what you’ll be using if you’re writing server-side software that authenticates against an OAuth2 API service.

The way it works is quite simple:

• First, you (a developer) are given an API key.
• Next, you make an API request to the OAuth2 API service and “exchange” your API key for a temporary “Access Token”.
• Finally, you use this temporary “Access Token” to make authenticated API
  requests.

That’s it!

Now, let’s cover some terminology here:

When you exchange your API key for an Access Token, you’ll be making a POST request to the API service at a particular URL, typically /oauth/token, and supplying your API Key via Basic Auth.

An Access Token is just a long string. It could be anything — most of the time though, it’s a cryptographically signed token known as a JWT. The most important thing to know about Access Tokens is that they expire after a short amount of time (usually an hour or so).

The reason Access Tokens expire, is so that you (a developer) don’t need to constantly send your top-secret API key over the network. This reduces the risk of your API key being compromised.

Exchanging an API Key for an Access Token

The first step in authenticating against an OAuth2 protected API service is exchanging your API key for an Access Token.

Let’s take a look at how to do this.

Here are the requirements:

• We need to create a POST request
• We need to supply grant_type=client_credentials in the body of our request
• Our request needs to be application/x-www-form-urlencoded
• We need to supply our API key credentials via Basic Auth

Let’s say we have an API key with two components:

• ID: xxx
• Secret: yyy

We could use the curl command to get an Access Token from a typical OAuth2 API
service by doing:

NOTE: Most OAuth2 services use the /oauth/token URI endpoint for handling all OAuth2 requests.

In Node, we could use the request library to do something similar:

When you receive a response from the OAuth2 server, you should get back a JSON response that contains an access_token string.

Authenticating Against an OAuth2 API Using Node.js

Now that we’ve seen how we can exchange our API key for an Access Token, let’s take a look and see how we can actually authenticate ourselves against an OAuth2 protected API.

We’ll do this by generating an HTTP Authorization header, and including our token inside of it.

Here’s an example request using curl:

By using the -H flag with curl, we are telling it to send the included HTTP header with our request.

As long as our Authorization header contains the string "Bearer <token>", the remote server will be able to authenticate us successfully!

Likewise, we could use the request library to do something similar:

Easy!

Summary

Authenticating yourself against an OAuth2 API service in Node.js is quite easy once you know how it all works.

Hopefully, this quick tutorial will get you up and running in no time =)

PS: If you’re building an OAuth2 API service, you should really check
Stormpath out — we make it super duper easy.