JSON web token (JWT) support in Thriftly

The October 2017 version of Thriftly provides support for JSON Web Tokens. JSON Web Tokens (JWTs) are an open standard method for authorizing users and transmitting information securely using metadata embedded directly in your API calls.

JWTs are compact and self-contained, meaning authorization is fast and doesn’t require your server to maintain session data or route calls through a separate authorization layer. With Thriftly, all it takes is a few simple steps to create truly stateless APIs with built-in JWT authorization.

In this post, we’ll get into how JWTs are commonly used, what JWTs look like, and how to implement JWTs in Thriftly.

How JWTs Are Used

JWTs are primarily used to authorize users post-login and ensure transmitted information hasn’t been tampered with in transit.

With Thriftly (or any other service that provides JWTs), when a user initially logs in, Thriftly passes that user a unique JWT that contains several claims (pieces of unique, identifying information). This JWT is then embedded in the header of the user’s subsequent API calls, and the Thriftly API server itself (not a separate table containing session data) decodes the JWT to verify the user’s identity and ensure that the API call was not modified in transit. Using this stateless authorization method reduces the number of calls needed for each API request, significantly reducing server overhead while keeping requests secure.

You can view an example: 5 Easy Steps to Understanding JSON Web Tokens (JWT) / (after clicking the link, scroll to the first diagram).

What a JWT Looks Like

Above, we said JWTs are compact. In this section, we’ll explain what that means, and why it’s important.

JWTs contain just three components: a header, a payload, and a signature.

• The header contains info on the token’s type (which is always JWT) and the hashing algorithm needed to decode the token (more on this later).
• The payload contains the claims we mentioned above. You can include a variety of different claims in your payload, but all payloads include at least some identifying user information (such as user ID and name).
• The signature is calculated based on the JWT’s header, its payload, and a key (which can be secret, public, or private). The header and payload are encoded using Base64Url, and then those encoded strings are joined with the key and hashed using the algorithm provided in the header.

This, finally, creates an encoded JWT:

When your application server receives an API call containing this token, it works backwards, using the key and the hashing algorithm you’ve chosen to decode the JWT and verify that the user is who she says she is and that her API call wasn’t tampered with in transit. If your application can’t successfully decode the JWT, it throws an error and rejects the call.

JWTs’ simple structure is one of their greatest strengths. Because JWTs use a simple JSON structure, composed of just three parts, they are easy to encode and decode, further speeding up the authorization process.

How JWTs Work in Thriftly

As part of developing and deploying your Thriftly APIs, you can configure them to generate and require JWTs. Thriftly handles the majority of the work for you, generating and verifying JWTs largely as described above. There are just a few simple things you have to do to turn on JWTs in Thriftly and secure your APIs.

First, you must update your Thriftly APIs to create and require JWTs.
You do this by:

• Designating a specific function in your Thriftly API as the login call. When a user completes this call, Thriftly will pass her a JWT to be used in subsequent calls.
• Adding the auth method attribute to functions you want to secure. In the auth method attribute, you specify any custom authorization methods you’re using, so Thriftly knows to check for and verify a JWT before allowing a user to access the protected function. You also specify the registered claim names to be added to your JWTs’ payload.

Second, you can choose from several hashing algorithms, including ES256 and HMAC384, to determine how Thriftly encodes and decodes JWTs:

• In most cases, we suggest using the ES256 hashing algorithm, since it allows you to pair public and private keys, meaning you don’t have to actually share your server’s private key with the client making the API call (this is our default setting).
• You should use HMAC384 hashing only when sharing information between two trusted entities (e.g. business-to-business calls), as it requires that both the client and the server know the secret key used to decode the JWT.

Third, you can use Thriftly to generate the keys used to decode your JWTs:

• If your organization is already using JWTs, and therefore already has keys, you can import your existing keys and use them when making calls to Thriftly APIs.
• If you do not already have keys, you can easily create them in Thriftly. You can also export Thriftly-created keys to use elsewhere in your organization (e.g. if you need to use your key to validate JWTs on another server).

Conclusion

Detailed documentation walking you through exactly how to implement JWTs in Thriftly is available in the Thriftly docs (Configuring Your APIs to Handle JSON Web Tokens), but we wanted to tell you about this new feature here so you could get started experimenting with JWTs! If you have any questions, feel free to leave them as a comment below, and a Thriftly developer will get back to you.