Tutorial: Validate a JSON Web Token (JWT)

This tutorial shows you how to define and implement a REST API definition that validates a JSON Web Token (JWT).

About this tutorial

In this tutorial, you complete the following lessons:
  1. Validate a JWT
  2. Testing the REST API
Note: The Sandbox catalog must be configured to use either a DataPower® Gateway (v5 compatible) or a DataPower API Gateway or both. See Creating and configuring catalogs.

Before You Begin

Also do the following steps.

Validate a JWT

Create a REST API to validate a JSON Web Token (JWT).

To add and define this REST API, complete the following steps:
  1. Log in to API Manager.
  2. In the Welcome page, click the Develop APIs and Products tile.

    API Manager screen

  3. Click Add > API (from REST, GraphQL or SOAP).

    Add API screen

  4. Ensure that OpenAPI 3.0 is selected.
  5. Select New OpenAPI. Click Next.

    Select OpenAPI

  6. Enter the appropriate information to create a REST API definition.
    1. In the Title field, enter JWTVAL.
    2. The Name and Base Path fields auto-populate with the terms jwtval and /jwtval respectively.
    3. The Version field auto-populates with 1.0.0.

    Basic information screen

  7. Click Next.
  8. Change no the Secure screen. Click Next.

    Secure API

  9. You see the progress as the new API gets created. When it is done, you see a Summary. Click Edit API.

    New API summary

  10. In the side bar of the Design page, select Paths to display the Paths panel.
  11. Click Add.

    Paths page

  12. In the path name field, enter /val.
  13. Click Create.

    Add a path info

  14. Scroll down. In the Parameters section, click Add.

    Add parameters

    1. Enter Authorization in the Parameter name field.
    2. Select the header in the Located In field.
    3. Enter Enter Bearer <jwt> to match in the Description field.
    4. Select Required.
    5. Click Create.

      Path Parameter settings

    6. Scroll down. In the Schema section, click Create

      Add schema

    7. Select the string in the Type field.
    8. Click Create.

      Add string

  15. After you create the parameter, click Save.
  16. Click Componets > Responses.
  17. Click Add.

    Responses page

  18. The Response name field auto-populates with 200.
  19. Enter 200 OK in the Description field.

  20. After you create the response, click Save.
  21. Click Gateway.
  22. Hover the mouse over the existing Proxy or start action and click the trash can icon to delete it.

    Gateway page

  23. Drag the Set Variable action onto the processing flow line. A configuration panel automatically opens.
  24. Click Add action.

    Set Variable action added

  25. Enter hs256-key in the Set field.
  26. Select the string in the Type field.
  27. Enter a JWK in the Value field. The following is an example. { "alg": "HS256", "kty": "oct", "use": "sig", "k": "o5yErLaE-dbgVpSw65Rq57OA9dHyaF66Q_Et5azPa-XUjbyP0w9iRWhR4kru09aFfQLXeIODIN4uhjElYKXt8n76jt0Pjkd2pqk4t9abRF6tnL19GV4pflfL6uvVKkP4weOh39tqHt4TmkBgF2P-gFhgssZpjwq6l82fz3dUhQ2nkzoLA_CnyDGLZLd7SZ1yv73uzfE2Ot813zmig8KTMEMWVcWSDvy61F06vs_6LURcq_IEEevUiubBxG5S2akNnWigfpbhWYjMI5M22FOCpdcDBt4L7K1-yHt95Siz0QUb0MNlT_X8F76wH7_A37GpKKJGqeaiNWmHkgWdE8QWDQ", "kid": "hs256-key" }

    Setvar properties

  28. Close the property panel. Click Save.
  29. Drag the Validate JWT action onto the processing flow line after the set-variable icon. A configuration panel automatically opens.

    JWT Validate action added

  30. Enter hs256-key in the Verify Crypto JWK variable name field.

    JWT Validate properties

  31. Close the property panel. Click Save.
  32. Drag the GatewayScript action onto the processing flow line after the Validate JWT icon. A configuration panel automatically opens.
  33. Enter the following code:
    var apim = require('apim');
    apim.setvariable('message.body',apim.getvariable('decoded.claims'));

    GatewayScript action added

  34. Close the property panel. Click Save.
  35. Ensure that the Show catches option is enabled so that the catch area is displayed.

    Assemble page catch

  36. Click Catches. A property panel opens.
  37. Click Add default catch.

    Assemble page catch

  38. Drag the GatewayScript policy action onto the catch flow line.
  39. Enter the following code:
    var apim = require('apim');
    apim.setvariable('message.body',apim.getvariable('jwt-validate.error-message'));

    Assemble page catch flow

  40. Close the property panel. Click Save.

Testing the REST API

Note: Due to Cross-Origin Resource Sharing (CORS) restrictions, the assembly test tool cannot be used with the Chrome or Safari browsers on the macOS Catalina platform.
To test the REST API, you need a valid JWT. You can obtain such a JWT by starting the API created in the Tutorial: Generate a JSON Web Token (JWT). To test the REST API, complete the following steps:
  1. Turn on the activation toggle to activate the API you created.
  2. Click Test.
  3. Enter Bearer followed by a space followed by a valid JWT generated with the same sign key in the Value field corresponding to the Authorization parameter.
    Note: If the Authorization key is missing from the parameters, confirm that the correct request path is selected. Select a request path that ends with /val, or manually append /val to the GET request.
  4. Click Send.
  5. The response contains branch data.

Manage your API definition

Now, that your new API works correctly, you can manage this API. To see your immediate options, take the following steps.

  1. Click the Develop icon Develop icon on the navigation bar.
  2. Click the Options icon The manage icon alongside the Mapper API.

    Manage API

  3. Select Download.

What you did in this tutorial

In this tutorial, you completed the following activities:
  • Created a new API definition that validates a JSON Web Token (JWT).
  • Tested the new API.