Tech Talk: What is OAuth?

Tech Talk: What is OAuth?

From 10,000 Feet: What is OAuth? - Well, without going down the rabbit hole of many definitions, descriptions, best practices, and different implementation, the OAuth 2.0 Authorization Framework, is a protocol. More simply it is a set of rules, which describe how unrelated services can allow access to one another in a safe and secure manner. This is what enables you to use your Google or Facebook accounts to sign in to other services like LinkedIn. While OAuth has numerous extensions and implementations, we’ll stay focused on the implementation that Particle uses.

Particle is using the Client Credentials JSON Web Token flow. Don’t worry if this sounds like jargon—we promise to keep it clear and to the point.

Let’s conceptualize this before diving into the tech. OAuth can be likened to staying at a resort. (So far so good, right?) Before being able to go anywhere at this metaphorical resort, you need to sign in at the front desk and be given a room card. This room card provides you with access to different areas of the resort; you can get into your room, work out at the gym, and maybe even visit the spa or pool. Hey you’re on vacation! You do you. However, despite having access to these amenities, some areas—like the employee break room or the restaurant’s kitchen—will still be off-limits. Furthermore, once your stay is over, you’ll be locked out from everywhere and you must visit the front desk again to either get a new card, or renew your existing one.

In this example, when you arrive at the resort, you provide your identity (Client Credentials) to the front desk (the Authorization Server) which in turn provides you with a room card (JSON Web Token). This card can be used to visit different amenities (Services), but doesn’t provide you full access to the resort itself.

What is the Client Credentials Flow?

The Client Credentials flow is intended to be used for server to server interactions. In this flow, a server, or client, who wishes to make requests to an OAuth2 protected API must obtain a set of client credentials from the API. This lets the API know that the client is a valid and trusted user, while also allowing the client to call an Authorization server using its credentials to generate a special token. When the client passes this token in the Authorization header to the API, the API is able to validate the token and authorize the client for use of its services. Depending on the implementation, the token can be used a set number of times, for a set period of time, or even indefinitely. Particle’s API is intended to be called from an application or service at scale, so this was the clear choice to pursue.

Can you elaborate on these tokens?

At Particle we’re implementing the token as a JSON Web Token (JWT). A JWT is a URL base64-encoded string consisting of three parts. The first part is a generic header containing metadata about the token such as the method used to sign it. The second part is where the good stuff happens: where the payload data, or claims are stored. Claims are what allows a service to know who is making the request, what they have access to, and for how long they have access. Last but definitely not least, the third part contains a signature that the API will use to validate the entire JWT to ensure it came from the expected source and the claims haven’t been tampered with.

So a JWT may look like this…

Got it. Credentials and JWTs. But how do I use them?

On Particle’s Developer Portal you’ll be able to generate a set of client credentials which are returned in plain text and should be saved for later use. (Please don’t write them on a sticky note). Using these credentials, a client can call Particle’s Authorization service which will validate the credentials via a one-way hashing algorithm and respond with a JWT. Each JWT is constructed based on the metadata of the user, as well as the permissions tied to the set of client credentials that are making the request. The resulting JWT can be stored for use up to 24 hours and is attached to every request against Particle’s API. This means that at scale, Particle will only need to populate a user’s JWT once a day, instead of once per request, saving time and processing power on every interaction. Typically, in a productionized environment the request would originate from an application’s Service Account. But, individual users can also generate client credentials and JWTs to help understand the flow as well as to ease development against Particle’s APIs.

Seems pretty cool, but why go through all the trouble?

OAuth is an important and useful security framework because it drastically changes how requests are authenticated within an application. Here’s our recap:

• Security:
  The API being called doesn’t actually need to know the credentials of the application that is making the request. All the API needs to know is if the requesting application has access. This means that instead of doing (potentially costly) lookup and permissions mapping operations per request, Particle can do it semi-regularly and provide a JWT valid for 24 hours. Furthermore, because the API doesn’t need to know the credentials of the requesting application, this prevents users from sending their most vulnerable information frequently. This helps cut down on the chance of client credentials leaking out. Even in the circumstance a JWT is somehow intercepted, stolen, misplaced, made erroneously publicly available, etc... anyone trying to use such a token will have limited time to act before it expires. Additionally, if such a situation occurs, Particle is able to revoke the JWT, preventing the nefarious actor from using it while not impacting the original owner’s account. Under such a scenario, the original owner can generate a new JWT and carry on uninterrupted.
• Efficiency:
  Calling an API while passing in secure credentials every time is insecure. And calling an authorization server for every API request effectively doubles the number of calls being made. At Particle, JWTs allow a happy medium by providing a vehicle for passing an API a set of permissions, preventing the need to do expensive table lookup and joins for each API invocation. Each JWT is constructed to hold all of the information needed for an API to make a determination on if the request should be processed or denied.
• Straightforward:
  OAuth2 and JWTs are a widely accepted, well documented, and easy to follow standard that most developers are familiar with. Even for an uninitiated software engineer, the process of developing against a JWT-based authorization flow should be fairly pain free. Not to mention, the payload of a JWT can evolve as Particle continues to grow and add additional offerings—all without impacting the end user!