Page Comparison

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:

...

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

Image Added

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:

...

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  See /wiki/spaces/TWT/pages/17073287 for more details on the specific meaning and source of these values.

Validating the JWT

...

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.

Example Code

Here is some sample java code to demonstrate parsing a JWT header.  This code takes advantage of the Echo API because it's easier to make a quick POC API Consumer than it is to setup a API Provider and register it with the APIM.  

import java.io.IOException;
import java.io.InputStream;
import java.security.KeyStore;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.PublicKey;
import java.security.cert.CertificateException;
import java.util.Map.Entry;
import org.junit.Test;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
public class DecodeJwtFromAPIM {
	private static final Logger log = LoggerFactory.getLogger(DecodeJwtFromAPIM.class);
	private static final String ConsumerSecret = "a6kF0HyNaergsVSGaCKhlbRtSXob";
	private static final String ConsumerKey = "5hJFay5newu3Pi1affMJgkk7LpIa";
	private static final String APIM_PUBLIC_KEY_PATH = "/api-qa.ucsd.edu.pub.jks";
	private static final String APIM_CERTIFICATE_ALIAS = "api-qa.ucsd.edu";
	private static final String JKS_PASSWORD = "middleware";
	@Test
	public void test() throws Exception {
		HttpResponse<JsonNode> jsonResponse = Unirest.post("https://api-qa.ucsd.edu:8243/token")
				.field("grant_type", "client_credentials").basicAuth(ConsumerKey, ConsumerSecret).asJson();
		log.debug("Response from token request: " + jsonResponse.getBody());
		String token = jsonResponse.getBody().getObject().getString("access_token");
		log.debug("Access Token: " + token);
		jsonResponse = Unirest.get("https://api-qa.ucsd.edu:8243/echo/1.0.0")
				.header("Authorization", "Bearer " + token)
				.asJson();
		log.debug("Response from echo request: " + jsonResponse.getBody());
		String jwtHeader = jsonResponse.getHeaders().getFirst("X-JWT-Assertion");
		log.debug("X-JWT-Assertion: " + jwtHeader);
		PublicKey publicKey = loadPublicKey();
		Claims claims = Jwts.parser()
				.setSigningKey(publicKey)
				.parseClaimsJws(jwtHeader)
				.getBody();
		for (Entry<String, Object> claim : claims.entrySet()) {
			log.debug("Claim {} ==> {}", claim.getKey(), claim.getValue());
		}
	}
	private PublicKey loadPublicKey()
			throws KeyStoreException, IOException, NoSuchAlgorithmException, CertificateException {
		try (InputStream is = DecodeJwtFromAPIM.class.getResourceAsStream(APIM_PUBLIC_KEY_PATH)) {
			KeyStore ks = KeyStore.getInstance("JKS");
			ks.load(is, JKS_PASSWORD.toCharArray());
			return ks.getCertificate(APIM_CERTIFICATE_ALIAS).getPublicKey();
		}
	}
}

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

...

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:

...

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. 

...

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

...