Skip Headers
Oracle® Fusion Middleware Reference for Oracle Security Developer Tools
11g Release 1 (11.1.1)

Part Number E10037-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

13 Oracle JSON Web Token

Oracle JSON Web Token, introduced in 11g Release 1 (11.1.1) Patch Set 5, provides support for the J SON Web Token (JWT) standard.

13.1 Oracle JSON Web Token Features and Benefits

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

13.1.1 About JWT

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.

See Also:

JSON Web Token IETF draft document at http://tools.ietf.org/html/draft-jones-json-web-token-05.

13.1.2 Oracle JSON Web Token Features

Oracle JSON Web Token is a full Java solution that provides extensive support for JWT tokens. Features include:

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

13.2 Setting Up Your Oracle JSON Web Token Environment

The Oracle Security Developer Tools are installed with Oracle WebLogic Server in ORACLE_HOME. This section explains how to set up your environment for Oracle JSON Web Token. It contains these topics:

13.2.1 System Requirements for Oracle JSON Web Token

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

13.2.2 Setting the CLASSPATH Environment Variable

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

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

  1. If present, the jars are loaded from the system class path.

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

  3. 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).

13.2.2.1 Setting the CLASSPATH on Windows

To set the CLASSPATH on Windows:

  1. In your Windows Control Panel, select System.

  2. In the System Properties dialog, select the Advanced tab.

  3. Click Environment Variables.

  4. In the User Variables section, click New to add a CLASSPATH environment variable for your user profile. If a CLASSPATH environment variable already exists, select it and click Edit.

  5. Add the full path and file names for all the required jar and class files to the CLASSPATH.

    For example, your CLASSPATH might look like this:

    %CLASSPATH%;
    %ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_core.jar;
    %ORACLE_HOME%\modules\oracle.osdt_11.1.1\osdt_cert.jar;
    
  6. Click OK.

13.2.2.2 Setting the CLASSPATH on UNIX

On UNIX, set your CLASSPATH environment variable to include the full path and file names of all of the required jar and class files. For example:

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:

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

Section 13.4 demonstrates how to use Oracle JSON Web Token.

13.4 Examples of 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 (Section 13.5).

13.4.1 Creating the JWT Token

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.

Setting Header Parameters

The header parameter alg must 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.

Setting Claim Parameters

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.

13.4.2 Signing the JWT Token

To create and sign the JWT token, first create 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);

13.4.3 Verifying the JWT Token

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(); 

13.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();

13.5 The Oracle JSON Web Token Reference

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

Oracle Fusion Middleware JWT Java API Reference for Oracle Security Developer Tools