This tutorial shows you how to define and implement a REST API definition that validates
a JSON Web Token (JWT).
Before You Begin
You must 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:
- Log in to API Manager.
- In the Welcome page, click the Develop APIs and Products tile.
![API Manager screen](tutorial_onprem_APIM_mgr_home.jpg)
- Click .
![Add API screen](tutorial_onprem_APIM_apiprod_add.jpg)
- Select New OpenAPI. Click Next.
![Select OpenAPI](tutorial_onprem_JWT_create.jpg)
- Enter the appropriate information to create a REST API definition.
- In the Title field, enter JWTVAL.
- The Name and Base Path fields autopopulate with
the terms jwtval and /jwtval respectively.
- Enter 1.0.0 in the Version field.
![Basic information screen](tutorial_onprem_JWTVAL_info.jpg)
- Click Next.
- Make no changes on the Secure screen. Click Next.
![Secure API](tutorial_onprem_MAPJ_createapi_secure.jpg)
- You see the progress as the new API gets created. When it is done, you see a Summary. Click
Edit API.
![New API summary](tutorial_onprem_JWT_summary.jpg)
- In the side bar of the Design page, select Paths to display the Paths
panel.
![Paths page](tutorial_onprem_JWTVAL_initial.jpg)
- Click Add.
- In the Path name field, enter /val.
- In the Operations section, click Add.
- Select GET and click Add.
![Path info](tutorial_onprem_JWTVAL_path_val_basic.jpg)
- Click Save.
- Click /val in the list of available paths.
![Path list](tutorial_onprem_JWTVAL_path_list.jpg)
- Click GET in the list of Operations.
- Scroll down. In the Parameters section, click Add.
- Select REQUIRED.
- Enter Authorization in the NAME field.
- Select header in the LOCATED IN field.
- Select string in the TYPE field.
- Enter Enter Bearer <jwt> in the DESCRIPTION
field.
![Path Parameter settings](tutorial_onprem_JWTVAL_param.jpg)
- In the Response section, change the description of the pre-supplied
200 status code to 200 OK.
![Path Response settings](tutorial_onprem_JWT_paths_response.jpg)
- Click Save.
- Click Assemble.
![Path list](tutorial_onprem_JWTVAL_paths2.jpg)
- Hover the mouse over the existing Proxy or Invoke action and click the trash can icon to delete it.
![Proxy action](tutorial_onprem_JWTVAL_delete_proxy.jpg)
- Drag the Set Variable action onto the processing flow line. A configuration panel automatically opens.
![Setvar action added](tutorial_onprem_JWT_jwtgen_add_setvar.jpg)
- Click + Action field.
- Enter hs256-key in the Set field.
- Select string in the Type field.
- Enter a JWK in the Value field. Here 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](tutorial_onprem_JWT_setvar_key.jpg)
- Close the property panel. Click Save.
- Drag the Validate JWT action onto the processing flow line after the
set-variable icon. A configuration panel automatically opens.
![JWT Validate action added](tutorial_onprem_JWTVAL_add_jwtval.jpg)
- Enter hs256-key in the Verify Crypto JWK variable name field.
![JWT Validate properties](tutorial_onprem_JWTVAL_verify_crypto.jpg)
- Close the property panel. Click Save.
- Drag the GatewayScript action onto the processing flow line after the Validate JWT icon.
A configuration panel automatically opens.
- Enter the following code:
var apim = require('apim');
apim.setvariable('message.body',apim.getvariable('decoded.claims'));
![GatewayScript action added](tutorial_onprem_JWTVAL_add_gws.jpg)
- Close the property panel. Click Save.
- Ensure that the Show catches option is enabled so that the
catch area is displayed.
![Assemble page catch](tutorial_onprem_JWTVAL_enable_catch.jpg)
- Click Catch. A property panel opens.
![Assemble page catch](tutorial_onprem_JWTVAL_assemble_catch_click.jpg)
- Click + Default.
- Drag the GatewayScript policy action onto the catch flow line.
- Enter the following code:
var apim = require('apim');
apim.setvariable('message.body',apim.getvariable('jwt-validate.error-message'));
![Assemble page catch flow](tutorial_onprem_JWTVAL_assemble_catch_flow.jpg)
- 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 will need a valid JWT. You can obtain such a JWT by invoking the API
created in the
Tutorial: Generate a JSON Web Token (JWT). To complete
testing, take the following steps:
- Click the Test icon
. ![Assemble page](tutorial_onprem_JWTVAL_assemble.jpg)
- Click Activate API.
![Test setup](tutorial_onprem_MAPJ_test_initial.jpg)
- Select the get /val Operation.
- Enter Bearer followed by a space followed by a valid JWT generated with
the same sign key in the Authorization field. Invoking the API created by the
Generate JWT tutorial will produce such a key.
![Test invoke](tutorial_onprem_JWTVAL_test_param.jpg)
- Click Invoke. You may encounter a yellow error box with a URL embedded in
it. Click this URL to override a browser certificate error.
![Test invoke](tutorial_onprem_APIM_test_yellow_error_box.jpg)
- Click Invoke again. The response contains branch data.
![Repeat invoke](tutorial_onprem_JWTVAL_test_ok.jpg)
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.
- Click the Develop icon
on the navigation bar.
![Navigation bar](tutorial_onprem_JWTVAL_test_nav_bar.jpg)
- Click the Options icon
alongside the Mapper API. ![Manage API](tutorial_onprem_JWTVAL_api_manage_opts.jpg)
- 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.