Accessing Authentication Details Via JWT

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:

• Fine grained access decisions - e.g. "Users can only access class details for classes they are enrolled in"
• Auditing - e.g. "The class was deleted by XXX"
• Returning "Your" data - e.g. "Invoking the api will return the current user's calendar"

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 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

The above resources have thorough explanations of what a JWT is how to use it, so this page will focus on the specific UCSD implementation.

The Header

The JWT will look like this:

X-JWT-Assertion: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5XVTJaV1F3WlRsbU1EVTVNbUpqWWpBd05tUTNOVFUyT1dFek5EQXlZakEyWm1NMFlqUm1OQT09In0=.eyJpc3MiOiJ3c28yLm9yZy9wcm9kdWN0cy9hbSIsImV4cCI6MTQ3OTQxMDU1MTY4MSwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9zdWJzY3JpYmVyIjoibHplbHVzIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9hcHBsaWNhdGlvbmlkIjoiMSIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvYXBwbGljYXRpb25uYW1lIjoiRGVmYXVsdEFwcGxpY2F0aW9uIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9hcHBsaWNhdGlvbnRpZXIiOiJVbmxpbWl0ZWQiLCJodHRwOi8vd3NvMi5vcmcvY2xhaW1zL2FwaWNvbnRleHQiOiIvZWNoby8xLjAuMCIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvdmVyc2lvbiI6IjEuMC4wIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy90aWVyIjoiVW5saW1pdGVkIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9rZXl0eXBlIjoiUFJPRFVDVElPTiIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvdXNlcnR5cGUiOiJBUFBMSUNBVElPTiIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvZW5kdXNlciI6Imx6ZWx1c0BjYXJib24uc3VwZXIiLCJodHRwOi8vd3NvMi5vcmcvY2xhaW1zL2VuZHVzZXJUZW5hbnRJZCI6Ii0xMjM0IiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9hZHVzZXJuYW1lIjoiLSIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvZGVwYXJ0bWVudGNvZGVzIjoiMDAwNDQ0LDAwMDQyNSIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvZWlkIjoiOTI3MTI0IiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9lbWFpbGFkZHJlc3MiOiJsemVsdXNAdWNzZC5lZHUiLCJodHRwOi8vd3NvMi5vcmcvY2xhaW1zL2dpdmVubmFtZSI6IkxvdWlzIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9sYXN0bmFtZSI6IlplbHVzIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9uZXR3b3JrdXNlcmlkIjoibHplbHVzIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9uaWNrbmFtZSI6Imx6ZWx1cyIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvcGFzc3dvcmRUaW1lc3RhbXAiOiJsemVsdXMiLCJodHRwOi8vd3NvMi5vcmcvY2xhaW1zL3BpZCI6IkExMjUwMzMyOSIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvcmFjZmlkIjoiREVWTERaIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9yb2xlIjoiSW50ZXJuYWwvbHplbHVzX0RlZmF1bHRBcHBsaWNhdGlvbl9QUk9EVUNUSU9OLEludGVybmFsL2x6ZWx1c19EZWZhdWx0QXBwbGljYXRpb25fU0FOREJPWCxJbnRlcm5hbC9semVsdXNfTG91aXNUZXN0QXBwX1BST0RVQ1RJT04sSW50ZXJuYWwvbHplbHVzX1J1bnNjb3BlVGVzdEFwcF9QUk9EVUNUSU9OLEludGVybmFsL2x6ZWx1c19SdW5zY29wZVRlc3RBcHBfU0FOREJPWCxJbnRlcm5hbC9semVsdXNfRVNCX0UyVF9QUk9EVUNUSU9OLEludGVybmFsL2x6ZWx1c19BUElNVG9rZW5MaWJUZXN0X1BST0RVQ1RJT04sSW50ZXJuYWwvbHplbHVzX0FQSU1Ub2tlbkxpYlRlc3RfU0FOREJPWCxJbnRlcm5hbC9semVsdXNfRGV2bG9wZXJzTW9udGhseURlbW9fUFJPRFVDVElPTixJbnRlcm5hbC9semVsdXNfRGV2bG9wZXJzTW9udGhseURlbW9fU0FOREJPWCxJbnRlcm5hbC9ldmVyeW9uZSIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvc3lzdGVtaWQiOiIwNDZmMzRlNzRkYzEyNDc1MDE0ZWZiMzFlZWYwMGUzNiJ9.IgICZeaUYLvTUkOLK+KxbDNf15eC/pO8w7jLvS1vsKMssMiIKwUD99QZMhP6P1fqblA5j34HM7l5z/gocKSX+snHvKQAara4oWTgpSUpf+SVzOqIFqn1d6Bg1pcXgULsiYploL5fbU/LC1rrT7Hdg05rKNHpvH06V6t7fBrMpvNLtGOLcV0FDsU1XPpJh8YLy6XFL01Jhkbw5L0N1ecHoq3QXq8St279eirQspbFjzz/tbUIEOgCCgI9hWoVjR9Y1pUfn5ARqEBLSqVdX8cAfdbNDJVtYAPm96q94zpJA8Yg6A3mVeMWZ5xSJpHSNN4C3ew97HHWGrbOMuPrF2mfBg==

See the above resources for a description of what the different parts mean, https://scotch.io/tutorials/the-anatomy-of-a-json-web-token is a particularly good place to start.

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. 

To use it,

1. Got to the Application page of the APIM Manager (https://api-qa.ucsd.edu/store/site/pages/applications.jag).
2. Create a new application:
   1. Name: XXX's APIM Javascript Tester
   2. Callback URL: https://lzelus.github.io/APIM/APIMJavascriptTester.html
3. Subscribe this new Application to the Echo API.
4. Copy the "Client Key" from your subscriptions page (be sure that your new application is selected).  
5. Open the APIM Javascript Tester and paste your Client Key.  
6. Click "Request an OAuth access token".  
7. This will send you to UCSD's SSO unless you already have an active SSO session.  Login using your Business Systems account.
8. You should be returned to the APIM Javascript Tester, which will then use the newly obtained access token to invoke the API.
9. The decoded JWT details should be rendered below.

Here is an example of the APIM Javascript Tester rendering the JWT contents:

The response had this JWT

JWT Contents

Fundamentally a JWT is a collection of claims.  Claims returned by UCSD's APIM can be broken into several groups:

• Standard JWT Claims - part of the JWT spec
• Invocation Claims - details about how api was called
• Application Details - details about the application invoking the API
• User Details - details about the user that the application is working on behalf of

Which claims are included vary based how authentication was done.  For example, using Client Authentication where only the client key and secret are provided, will result in the JWT not having any user claims.  

Standard Claims

The JWT specification includes a number of possible claims. The JWT contains the following standard claims:

Invocation Details

Application Details

User Details

SSO Details

In addition to the details about the user's APIM account, some of the values provided by UCSD's SSO server are included.  If a given value was not provided by the SSO server, it will be "-" as the integration element doesn't handle null values well.  See http://syswiki.ucsd.edu/index.php/Shibboleth#Shibboleth_attributes for more details on the specific meaning and source of these values.

Validating the JWT

The JWT supplied by the APIM is digitally signed by the APIM's certificate.  The certificate is issued by UCSD and signed by a reputable CA.  Please contact lzelus@ucsd.edu if you need a copy of the public certificates used. 

The JWT Spec has the exact details on how to validate a JWT, however there are many libraries that have already implemented the spec and make parsing/validating JWTs quite simple.

------------- Extra Documentation gathered from other sources ---------------

Below here are some extra bits of documentation gathered from around the web, primarily from BYU with whom we collaborate about our usage of WSO2's APIM.  The data below is not all applicable to UCSD's usage, it contains elements specific to other institutions, configurations and scenarios.

JWT Processing Code Example

BYU use of claims and JWT

From this point on we've included some details of how BYU is using JWT and claims.  This is only included to spark future discussion and thought, not as an indication of what is or will be implemented.

Following are claims used by BYU and are provide for reference only

BYU Claims

BYU has added a number of claims to make processing of identity information easier for service providers. The content of the Resource Owner and Client claims will be dependent upon which OAuth 2.0 grant type was used for authorization and if there has been a relationship established between the client application and a BYU entity (non-person person). That relationship is defined by placing a entry in the IAM.Credentials table within CESPRD. The entry would have the following values:

CREDENTIAL_NAME - The WSO2 Client Id for the application to be linked to a BYU entity. 

CREDENTIAL_TYPE - 'WSO2_CLIENT_ID'

BYU_ID - The BYU ID of the BYU entity to link this application to.

All other values in the table should be filled in with the appropriate information.

Some UCSD claims are optional based upon the OAuth 2.0 grant type used. For example, if the Client Credentials grant type is used no Resource Owner exists and so the claims dealing with Resource Owner values will not be present in the JWT. The set of possible BYU specific claims are as follows:

http://byu.edu/claims/resourceowner_person_id

http://byu.edu/claims/resourceowner_byu_id

http://byu.edu/claims/resourceowner_net_id

http://byu.edu/claims/resourceowner_surname

http://byu.edu/claims/resourceowner_surname_position

http://byu.edu/claims/resourceowner_rest_of_name

http://byu.edu/claims/resourceowner_preferred_first_name

http://byu.edu/claims/resourceowner_sort_name

http://byu.edu/claims/resourceowner_suffix

http://byu.edu/claims/resourceowner_prefix

http://byu.edu/claims/client_subscriber_net_id

http://byu.edu/claims/client_claim_source

http://byu.edu/claims/client_person_id

http://byu.edu/claims/client_byu_id

http://byu.edu/claims/client_net_id

http://byu.edu/claims/client_surname

http://byu.edu/claims/client_surname_position

http://byu.edu/claims/client_rest_of_name

http://byu.edu/claims/client_preferred_first_name

http://byu.edu/claims/client_sort_name

http://byu.edu/claims/client_name_suffix

http://byu.edu/claims/client_name_prefix

Examples

There are four possible combinations of the values of the http://wso2.org/claims/usertype and http://byu.edu/claims/client_claim_source claims. 

1) OAuth 2.0 Grant type with a Resource Owner and no relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION_USER' and http://byu.edu/claims/client_claim_source = 'CLIENT_SUBSCRIBER')

Resource Owner with Subscriber as Client Application Owner

2) OAuth 2.0 Grant type with a Resource Owner and and existing relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION_USER' and http://byu.edu/claims/client_claim_source = 'CLIENT_ID')

Resource Owner and BYU Entity as Client Application Owner

3) OAuth 2.0 Grant type with no Resource Owner and no relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION' and http://byu.edu/claims/client_claim_source = 'CLIENT_SUBSCRIBER')

No Resource Owner with Subscriber as Client Application Owner

4) OAuth 2.0 Grant type with no Resource Owner and an existing relationship between the client application and a BYU entity (http://wso2.org/claims/usertype = 'APPLICATION' and http://byu.edu/claims/client_claim_source = 'CLIENT_ID')

No Resource Owner and BYU Entity as Client Application Owner