12 Oracle JSON Web Token

This chapter describes how to use Oracle JSON Web Token.

Oracle JSON Web Token, introduced in Release 11g, provides support for the JSON Web Token (JWT) standard.

12.1 Oracle JSON Web Token Features and Benefits

This section introduces JWT concepts and key features of Oracle JSON Web Token.

12.1.1 About JSON Web Token

JSON Web Token (JWT) is a means of representing claims to be transferred between two parties. JWT is a compact token format intended for space- constrained environments such as HTTP Authorization headers and URI query parameters.

The claims in a JWT are encoded as a JSON object that is base64url encoded and consists of zero or more name/value pairs (or members), where the names are strings and the values are arbitrary JSON values. Each member is a claim represented by the JWT.

A JSON object is digitally signed using a JSON Web Signature (JWS) and optionally encrypted using JSON Web Encryption (JWE).

The JWT is represented as the concatenation of three segments:

JWT Header Segment describes the cryptographic operations applied to the token.
JWT Claim Segment encodes the claims contained in the JWT.
JWT Crypto Segment contains the cryptographic material that secures the contents of the token.

The segments are separated by period ('.') characters. All three segments are always Base64url encoded values.

12.1.2 Oracle JSON Web Token Features

Oracle JSON Web Token is a full Java solution that provides extensive support for JWT tokens. You can use the API to:

construct Base64url encoded tokens and set the token's header and claim parameter values, including user-defined headers
parse and verify tokens
sign and serialize tokens

The oracle.security.jwt.JwtToken class represents the JSON Web Token (JWT). Representative methods of oracle.security.jwt.JwtToken include:

setAlgorithm(String), getAlgorithm()
signAndSerialize(PrivateKey)
serializeUnsigned()
claim methods such as setPrincipal(String), getPrincipal(), getIssuer()

For details, see the tables of header and claim parameter names and corresponding get/set methods in the Javadoc.

12.2 Setting Up Your Oracle JSON Web Token Environment

The Oracle Security Developer Tools are installed with Oracle WebLogic Server in ORACLE_HOME.

In order to use Oracle JSON Web Token, your system must have the Java Development Kit (JDK) version 1.6 or higher.

Your CLASSPATH environment variable must contain the full path and file names to all of the required jar and class files. Make sure the following items are included in your CLASSPATH:

osdt_core.jar file
osdt_cert.jar file
jackson-core-1.1.1.jar file
jackson-mapper-1.1.1.jar file

For example, your CLASSPATH might look like this:

setenv CLASSPATH $CLASSPATH:
$ORACLE_HOME/modules/oracle.osdt_11.1.1/osdt_core.jar:
$ORACLE_HOME/modules/oracle.osdt_11.1.1/osdt_cert.jar:
$Jackson.library.path/jackson-core-1.1.1.jar
$Jackson.library.path/jackson-mapper-1.1.1.jar

At run-time, the following locations are searched for the Jackson jars:

If present, the jars are loaded from the system class path.
If the jars are not present in the system class path, the system property Jackson.library.path is examined. If present, the jars are loaded from that location for both Java SE and Java EE clients.
If the system property Jackson.library.path is not set or the Jackson jars are not found there, they are picked up from the predefined location $ORACLE_HOME/modules (for Java EE environment) and from the present directory (for Java SE client).

12.3 Using Core Classes and Interfaces

The Oracle JSON Web Token consists of the oracle.security.restsec.jwt.JwtToken class. Key functions provided by this class include:

constructing a JWT token
setting the parameter values of the JWT token
signing the token
verifying the token
token serialization

Examples of Oracle JSON Web Token Usage demonstrates how to use Oracle JSON Web Token.

12.4 Examples of Oracle JSON Web Token Usage

This section provides some examples of using Oracle JSON Web Token.

Note:

These are specific examples to demonstrate how to use Oracle JSON Web Token. For details and other options for using the methods described here, see the JWT javadoc (The Oracle JSON Web Token Java API Reference).

12.4.1 Creating the JWT Token

Creating the JWT token involves creating the object itself, then setting header and claim parameters as needed.

The steps are as follows:

To create a JWT token, begin by using the constructor method JwtToken() to create a JwtToken object.
```
JwtToken jwtToken = new JwtToken(); 
```
You can use various setter methods to set the parameter values of the JWT token.
To set header parameters, the header parameter alg must first be set; use the setAlgorithm(String) and getAlgorithm() methods, respectively, to set and get this parameter. By default, the alg parameter is set to "none" implying that you do not want to sign the token.

Use the setHeaderParameter(String, Object) method to set a user-defined header parameter in the JWT header segment.
Oracle JSON Web Token provides methods to set claim parameters exp, iat, iss, aud, prn. All the claim parameters are optional.

Use the setClaimParameter(String, Object) method to set the user-defined claim parameter in the JWT claim segment.

12.4.2 Signing the JWT Token

Signing a token involves actions such as creating a token instance, setting token parameters, and finally signing the token.

The steps are as follows:

Create and sign the JWT token, by first creating the instance of the JwtToken class:
```
JwtToken jwtToken = new JwtToken(String); 
```

Next set the parameters like algorithm, issuer, expiry time, other claims and so on:

jwtToken.setAlgorithm(JwtToken.SIGN_ALGORITHM.HS256.toString());
jwtToken.setType(JwtToken.JWT);
jwtToken.setIssuer("my.company.com");
jwtToken.setPrincipal("john.doe");

Finally obtain the private key and sign the token with a secret key or private key:

PrivateKey privateKey ;
String jwtString = jwtToken.signAndSerialize(privateKey);

12.4.3 Verifying the JWT Token

Verifying a token involves actions such as reading the token from the HTTP header, checking the token issuer, and so on.

This example code verifies the expiry date and token issuer:

// Read the JWT token as a String from HTTP header
String jwtStr = "eyJ.eyJp.dB";
JwtToken token = new JwtToken(jwtStr);
 
// Validate the issued and expiry time stamp.
if (token.getExpiryTime().after(new Date())) {
...
...
}
 
// Get the issuer from the token
String issuer = token.getIssuer();

12.4.4 Serializing the JWT Token without Signing

If the JWT token is not required to be digitally signed, you can serialize the token without signing, as shown in the following example:

JwtToken jwtToken = new JwtToken();
jwtToken.setType(JwtToken.JWT);
jwtToken.setIssuer("my.example.com");
jwtToken.setPrincipal("john.doe");
String jwtString = jwtToken.serializeUnsigned();

12.5 The Oracle JSON Web Token Java API Reference

The Oracle JSON Web Token API Reference (Javadoc) is available at:

Oracle Fusion Middleware Java API Reference for Oracle Security Developer Tools