Particle uses OAuth 2.0 Authorization Framework to ensure secure access to medical data to our customers. Given that this framework is very complex, we've put together an overview that explores how it works by sharing examples of how we use this technology in our everyday lives.
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.
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.
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.
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.
OAuth is an important and useful security framework because it drastically changes how requests are authenticated within an application. Here’s our recap: