When proxying calls to your back end API, the API Manager adds a header with details gathered during the authentication process. These details are commonly used for:
...
When a client invokes your API, all of the headers, query parameters and content will be passed along to your backend API, untouched. There are two exceptions to this rule. First the Authorization header submitted by the client is used by the APIM to determine access and is stripped from the request before it's passed to the backend. Secondly a digitally signed JSON Web Token (JWT) is added as the header a header. This JWT contains
- information about the entities involved. This includes
- Which Application made the call
- Which user is currently sitting behind the key board (if available).
- A Signature to verify that the JWT is from the API Manager
- Security details to prevent replay and similar attacks.
- information about the authentication preformed (e.g. did the user or just application authenticate).
Resources:
- https://docs.wso2.com/display/AM200/Passing+Enduser+Attributes+to+the+Backend+Using+JWT - WSO2's documentation on the subject with specifics on exactly what the JWT header will look like.
- https://scotch.io/tutorials/the-anatomy-of-a-json-web-token - A very clear, high level overview of JWT
- https://openid.net/specs/draft-jones-json-web-token-07.html#anchor3 - A nice rundown of what JWT is
- https://jwt.io/ - The main JWT resource hub
- https://bitbucket.org/b_c/jose4j/wiki/Home - A Java Library for processing the JWT
...
| Note |
|---|
This header is only on the request sent to the backend. It is not on added to the response sent to the client. This often causes some confusion to people new to JWT as they hope to inspect the header in their browser or similar client. To see the JWT header you must log, store, print or return it from a web service that is invoked by the APIM. See the Echo API below for other ways to see the JWT.section below about the Echo API which does just that. |
The Echo API
UCSD has implemented an API specifically for testing and demonstration. This API simply returns everything passed to it. Additionally it is specifically designed to also return the JWT that it received. This means that you can use a web client (like Postman) to invoke the echo API and inspect the JWT in the response.
APIM Javascript Tester
A pure javascript API client is avialiable at https://lzelus.github.io/APIM/APIMJavascriptTester.html. It has a special feature when used to invoke the Echo API. It will detect the returned JWT and decode it, rendering the data that it received.
| Note |
|---|
| Note |
The JWT should not be returned to the client, it is intended for the backend API's use. The JWT features of the Echo API and the APIM Javascript Tester are non-standard and discouraged usages of the JWT. The JWT should not be returned to the client, it is intended for the backend API's use. These tools purposely tools purposely break this convention to make it easier for API developers to "see" an example of a JWT. While this is helpful when learning about JWT's, it should not be emulated in production code. |
APIM Javascript Tester
A pure javascript API client is avialiable at https://lzelus.github.io/APIM/APIMJavascriptTester.html. It has a special feature when used to invoke the Echo API. It will detect the returned JWT and decode it, rendering the data that it received.
To use it,
- Got to the Application page of the APIM Manager (https://api-qa.ucsd.edu/store/site/pages/applications.jag).
- Create a new application:
- Name: XXX's APIM Javascript Tester
- Callback URL: https://lzelus.github.io/APIM/APIMJavascriptTester.html
- Subscribe this new Application to the Echo API.
- Copy the "Client Key" from your subscriptions page (be sure that your new application is selected).
- Open the APIM Javascript Tester and paste your Client Key.
- Click "Request an OAuth access token".
- This will send you to UCSD's SSO unless you already have an active SSO session. Login using your Business Systems account.
- You should be returned to the APIM Javascript Tester, which will then use the newly obtained access token to invoke the API.
- The decoded JWT details should be rendered below.
...
All other values in the table should be filled in with the appropriate information.
Relationship records should only be added for applications under the control of a BYU entity. There is no need to add them for individuals publishing their own applications. Currently there is no defined process for approving and adding these relationship records.
...