Configuring Your APIs to Handle JSON Web Tokens

If your developers coded your Thriftly API(s) to generate and require JSON Web Tokens (JWTs), as described in the Securing Your API with JSON Web Tokens (JWTs) topic, you must also configure your deployed application and API to handle JWTs. This way, your API will properly accept, require, and hash JWTs as users interact with it.

To configure your API(s) to generate and require JWTs, perform the setup below.

Creating a JWT Configuration

To start, you must create a JWT Configuration that defines how your API’s JWTs are encoded and decoded. You’ll then apply this configuration to your API (in the next set of setup steps).

  1. From the Windows Start menu, open the Thriftly Configurator (Thriftly Deployment Server > Thriftly Admin).

  2. From the Thriftly Configurator toolbar, select JWT Configs. The JWT Configurations Maintenance Window appears.

The JWT Configurations Maintenance window

  1. Select the Add button. Several fields appear on the right side of the window, including:

    • Algorithm

    • Description

    • Incoming Only

    • Configuration Name

  2. In the Algorithm field, select the hashing algorithm to use to encode your JWTs. We currently support the ECDSA (ES), HMAC (HS), PSS (PS), and RSA (RS) algorithms, using SHA-256, SHA-384, and SHA-512 hashing. In most cases, we suggest you select and use the ES256 hashing algorithm. If you want to learn more about JWT hashing algorithms before making your selection, click here.

    Note

    You should use HMAC hashing only when using your API to share information between two trusted entities (e.g. conducting business-to-business API calls), as HMAC hashing requires that both your server and the client making an API call know the secret used to decode your JWTs. If your API will communicate with untrusted entities, do not use HMAC hashing.

  3. In the Description field, enter a brief description of your JWT configuration.

  4. You can use the Incoming Only checkbox to configure whether your API verifies JWTs only when receiving requests, instead of performing verification both when receiving requests and providing responses. We recommend leaving this checkbox unselected, so your API verfies JWTs during both requests and responses. However, if you want your API to verify JWTs only upon receiving requests, select this checkbox.

  5. In the Configuration Name field, enter a unique name for this JWT configuration.

  6. Select the JWT_Config_Arrow_Button button to continue.

  7. Now, you must generate or import a key or secret that’s used to decode your JWTs. We imagine most Thriftly users will need to create a new JWT key/secret, so we’ll provide instructions for that first. If you want to import a key, skip to step 11. (Note that you cannot import secrets for use with the HS algorithm. You must generate your HS secrets within Thriftly.)

  8. Select the Generate Key/Secret button.

    • If you are using a hashing algorithm that allows you to select a key size, the Generate Keys window appears prompting you to select a key size. You can create keys that are 1024, 2048, or 4096 bits long. We recommend creating a a 2048 bit key. Optionally, you can learn more about key length, and use that information to inform your decision, by clicking here.

  9. (Skip if you performed step 10) To import your own pre-existing JWT key, select Import Key. The Import Keys window appears. You can import a public and/or private key to use with your JWTs.

  10. Your public and private keys appear in the appropriate fields. Select Save to save your JWT configuration. The details of your configuration appear in the JWT Configurations Maintenance window.

An example JWT configuration

Now, you must apply the configuration you created to your deployed Thriftly APIs.

Updating Your APIs to Use Your JWT Configuration

After you’ve created your JWT configuration, you must apply it to your deployed application and APIs. To do so:

  1. From the Thriftly Configurator, select the application you want to apply your JWT configuration to. Then, select the JWT Configuration tab.

The JWT Configuration tab within an application's settings

  1. On the JWT Configuration tab, select the JWT configuration you want to apply to your application. Then, select the Incoming checkbox to apply the configuration to incoming calls and the Outgoing checkbox to apply the configuration to your API’s responses. Then, select Save to save your settings.

    Note

    In certain scenarios, you could end up configuring your APIs to accept JWTs from multiple sources that provide differently formatted JWTs. In these scenarios, you’d create multiple JWT configurations and select the Incoming checkbox for each of those configurations, so your API accepts all your organization’s incoming JWTs. However, your APIs can only ever output one style of JWT, so you can select the Outgoing checkbox for only one JWT configuration. If you find yourself in this situation, you may want to Contact Us for help with your JWT configuration.

You’ve now configured your application’s APIs to accept, require, and hash JWTs. Now, let’s test your JWT configuration, so you can see your JWTs in action, protecting your app, data, and APIs.

Testing Your JWT Configuration

Now that you’ve updated your application and APIs to accept and require JWTs, you (or a developer) should test your APIs to make sure your application’s Login function and JWTs work correctly. To do so:

  1. From the Thriftly Configurator, run your application (by selecting your application from the sidebar and then selecting the Thriftly_Config_Run button).

  2. Select one of your application’s endpoints from the Thriftly Configurator sidebar. Then, select the Endpoint Info button to open that endpoint’s information in your web browser.

  3. When your endpoint information appears in your web browser, select the Test API link from within the service you want to test.

A Thriftly service and the Test API link

  1. The Thriftly API testing interface appears in your web browser. From the Method field, select LoginUser (or your API’s login function). Your function’s login parameters should appear in the Params field.

The LoginUser function in the Thriftly API testing interface

  1. Enter valid login information in the Params field. For example, if you’re testing an API built from our examples, you would enter “thriftly” in both the “user_name” and “password” parameters. Then, select Send.

  2. A valid response should appear in the Response field, with a JWT access token included in its header. Additionally, your token should appear in the testing interface’s JWT field, and the Include JWT Token checkbox should now appear, allowing you to toggle including your JWT in subsequent calls.

A JWT, the JWT field, and the Include JWT Token checkbox

  1. From the Method field, select one of your API’s secured methods. Then, clear the Include JWT Token checkbox. Attempt to make a valid call to your API.

  2. You should receive an error similar to the one pictured below, informing you that your call is not valid because it does not contain your JWT.

A invalid JWT API call

  1. Select the Include JWT Token checkbox and make the same call. Your call should now include the JWT in its header and return a valid response.

A valid JWT API call

You’ve now successfully configured your APIs to create, require, and hash JWTs and tested your configuration. Below, we’ll give you instructions on how to access your Thriftly-created JWT keys outside of Thriftly, if you need to validate them on another server, and delete a JWT configuration if you decide you no longer need it.

Accessing Thriftly JWT Keys Outside of Thriftly

If you need to validate your Thriftly JWTs on another server, you’ll need to download and access your JWT keys outside of Thriftly. To do so, you can export your Thriftly JWT keys to a .pem file from the JWT Configurations Maintenance window.

  1. If you haven’t already, open the Thriftly Configurator (Windows Start menu > Thriftly Deployment Server > Thriftly Admin). Then, select JWT Configs to open the JWT Configurations Maintenance window.

  2. From the JWT Configurations Maintenance window’s sidebar, select the configuration for which you’d like to export a JWT key.

  3. Select the Export Key button. The Export Keys window appears.

  4. Select the Export button located next to the key(s) you’d like to export as a .pem file. A window appears prompting you to specify the exported key’s file location and save your key.

Your exported key is now ready for use wherever and whenever you need it.

Deleting a JWT Configuration

If you decide you no longer need a certain JWT configuration, you can delete that configuration from within the JWT Configurations window. Note that, if you delete a configuration your applications are currently using, the configuration is also automatically removed from those applications.

  1. If you haven’t already, open the Thriftly Configurator (Windows Start menu > Thriftly Deployment Server > Thriftly Admin). Then, select JWT Configs to open the JWT Configurations Maintenance window.

  2. From the JWT Configurations Maintenance window’s sidebar, select the configuration you want to delete.

  3. Select the Delete button.

  4. The Delete JWT Configuration dialog appears to confirm you want to delete this configuration. Select Yes to delete your JWT configuration.