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.
This section introduces JWT concepts and key features of Oracle 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.
See Also:
JSON Web Token IETF draft document at http://tools.ietf.org/html/draft-jones-json-web-token-05
.
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.
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:
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
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).
To set the CLASSPATH
on Windows:
In your Windows Control Panel, select System.
In the System Properties dialog, select the Advanced tab.
Click Environment Variables.
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.
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;
Click OK.
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:
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
Section 13.4 demonstrates how to use Oracle JSON Web Token.
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).
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.
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.
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.
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);
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();
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();
The Oracle JSON Web Token API Reference (Javadoc) is available at:
Oracle Fusion Middleware JWT Java API Reference for Oracle Security Developer Tools