|
Oracle Fusion Middleware REST Security Java API Reference for Oracle Security Developer Tools 11g Release 1 (11.1.1) E26380-02 |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.security.restsec.jwt.JwtToken
public class JwtToken
This Class represents the JSON Web Token (JWT). The claims in a JWT are encoded as a JSON object that is digitally signed using a JSON Web Signature (JWS) and optionally encrypted using JSON Web Encryption (JWE). (See specification for details.)
JWT token contains three Segments: the JWT Header Segment, the JWT Claim Segment, and the JWT Crypto Segment, in that order, with the segments being separated by period ('.') characters. All the three Segments are always Base64url encoded values.
To build a JWT token, begin by using the constructor method
to create a JwtToken()
JwtToken
object. Continue by using the various setter
methods to set the parameter values of the JWT token. To get the Base64url representation of the JWT token use
or signAndSerialize(PrivateKey)
. One can use the method signAndSerialize(byte[])
, if the JWT token is not required to be digitally signed.serializeUnsigned()
The value of the header parameter alg
is MUST. Use the method
to set the value of the header parameter setAlgorithm(String)
alg
. The default value of alg
is "none". The following table shows the header parameter names and the corresponding methods to set/get their values.
Header parameter name | JSON value type | Provided methods to set/get the value of the header |
---|---|---|
alg | string | setAlgorithm(String) , getAlgorithm() |
typ | string | setType(String) , getType() |
jku | string | setJsonKeyURL(URL) , getJsonKeyURL() |
kid | string | setKeyID(String) , getKeyID() |
x5u | string | setX509URL(URL) , getX509URL() |
x5t | string | setX509CertThumbprint(X509Certificate) , getX509CertThumbprint() |
The value of the header parameters typ,jku, kid, x5u, x5t
are case sensitive and optional.
To set user defined header parameter in the JWT Header Segment use the method setHeaderParameter(String, Object)
The value of the claim parameters exp, iat, iss, aud, prn
are case sensitive and optional. The following table shows the claim parameter names and the corresponding methods to set/get their values.
Claim parameter name | JSON value type | Provided methods to set/get the value of the claim |
---|---|---|
exp | integer | setExpiryTime(Date) , getExpiryTime() |
iat | integer | setIssueTime(Date) , getIssueTime() |
iss | string | setIssuer(String) , getIssuer() |
aud | string | setAudience(String) , getAudience() |
prn | string | setPrincipal(String) , getPrincipal() |
To set user defined claim parameter in the JWT Claim Segment use the method setClaimParameter(String, Object)
To parse and verify the JWT token, create the instance of the JwtToken class using the constructor
. Use various JwtToken(String)
getter
methods to access the values of the different parameters. Use
or verify(byte[])
to verify the JWT token.verify(PublicKey)
Example code for JWT token signing:-
JwtToken jwtToken = new JwtToken();
//Fill in all the parameters- algorithm, issuer, expiry time, other claims etc
jwtToken.setAlgorithm(JwtToken.SIGN_ALGORITHM.HS256.toString());
jwtToken.setType(JwtToken.JWT);
jwtToken.setIssuer("my.oracle.com");
jwtToken.setPrincipal("john.doe");
// Get the private key and sign the token with a secret key or a private key
PrivateKey privateKey ;
String jwtString = jwtToken.signAndSerialize(privateKey);
Example code for JWT token serialization without signing:-
JwtToken jwtToken = new JwtToken();
jwtToken.setType(JwtToken.JWT);
jwtToken.setIssuer("my.oracle.com");
jwtToken.setPrincipal("john.doe");
String jwtString = jwtToken.serializeUnsigned();
Example code to verify JWT token:-
// 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();
// One need to maintain the mapping of issuer and issuer public key(i.e. a certificate)/secret key. Retrieve the issuer key from this map. It can be a secret key or a public key
PublicKey issuerKey = issuerKeyMap.get(issuer) ;
// Use this issuer key and verify the token.
boolean result = token.verify(issuerKey);
Working example code to sign JWT token (using HMAC SHA 256 algorithm):-
static final byte[] hmacKey = { 3, 35, 53, 75, 43, 15, (byte) 165, (byte) 188, (byte) 131, 126, 6, 101, 119, 123, (byte) 166, (byte) 143, 90, (byte) 179, 40, (byte) 230, (byte) 240, 84, (byte) 201, 40, (byte) 169, 15, (byte) 132, (byte) 178, (byte) 210, 80, 46, (byte) 191, (byte) 211, (byte) 251, 90, (byte) 146, (byte) 210, 6, 71, (byte) 239, (byte) 150, (byte) 138, (byte) 180, (byte) 195, 119, 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, (byte) 192, (byte) 205, (byte) 154, (byte) 245, 103, (byte) 208, (byte) 128, (byte) 163 }; JwtToken jwtToken = new JwtToken(); jwtToken.setIssuer("joe"); jwtToken.setExpiryTime(new Date(1300819380)); jwtToken.setClaimParameter(http://example.com/is_root, true); jwtToken.setType(JwtToken.JWT); jwtToken.setAlgorithm(JwtToken.SIGN_ALGORITHM.HS256.toString()); String jwtString = jwtToken.signAndSerialize(hmacKey); System.out.println(jwtString); The output for the above code will be:- "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 .eyJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlLCJpc3MiOiJqb2UifQ .tu77b1J0ZCHMDd3tWZm36iolxZtBRaArSrtayOBDO34";
Working example code to verify JWT token (using HMAC SHA 256 algorithm):-
String jwtString = "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9" + ".eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ" + ".dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"; JwtToken jwtToken = new JwtToken(jwtString); boolean result = jwtToken.verify(hmacKey); String algo = jwtToken.getAlgorithm(); System.out.println("Type:- "+ jwtToken.getType()); System.out.println("Issuer:- " + jwtToken.getIssuer()); System.out.println("Expiry time:- " +jwtToken.getExpiryTime()); Map<String, Object> claims = jwtToken.getClaimParameters(); Map<String, Object> headers = jwtToken.getHeaderParameters(); System.out.println("claims:- " + claims + "\n"); System.out.println("headers:- " + headers + "\n"); The output for the above code will be:- Type:- JWT Issuer:- joe Expiry time:- Thu Jan 15 17:20:19 PST 1970 claims:- {iss=joe, exp=1300819380, http://example.com/is_root=true} headers:- {typ=JWT, alg=HS256}
Nested Class Summary | |
---|---|
static class |
JwtToken.SIGN_ALGORITHM This represents the specific cryptographic algorithms to sign the contents of the JWT token. |
Field Summary | |
---|---|
static java.lang.String |
JWT This string constant represents the standard JWT token type |
static java.lang.String |
JWT_URI This string constant represents the standard JWT token type uri |
Constructor Summary | |
---|---|
JwtToken() This constructor is used to build the JWT token. |
|
JwtToken(java.lang.String jwtString) This constructor is used when Base64url encoded JWT token is required to be parsed in to JwtToken Class instance. |
Method Summary | |
---|---|
static byte[] |
fromBase64url(java.lang.String s) Returns the decoded form of the given Base64url encoded string. |
java.lang.String |
getAlgorithm() This method returns the cryptographic algorithm used to secure the JWS. |
java.lang.String |
getAudience() This method returns the intended audience for this JWT token. |
java.lang.Object |
getClaimParameter(java.lang.String claim) This method returns the value of the JWT claim. |
java.util.Map<java.lang.String,java.lang.Object> |
getClaimParameters() This method returns the map of the name/value pair of the JWT claim segment. |
java.util.Date |
getExpiryTime() This method returns the expiration time of the JWT token. |
java.lang.Object |
getHeaderParameter(java.lang.String header) This method returns the value of the JWT header. |
java.util.Map<java.lang.String,java.lang.Object> |
getHeaderParameters() This method returns the map of the name/value pair of the JWT header segment. |
java.lang.String |
getIssuer() This method returns the issuer of the JWT token. |
java.util.Date |
getIssueTime() This method returns the issue time of the JWT token. |
java.net.URL |
getJsonKeyURL() This method returns the URL that points to JSON-encoded public keys that can be used to validate the signature. |
java.lang.String |
getKeyID() This method returns the key id. |
java.lang.String |
getPrincipal() This method returns the principal of the JWT token. |
java.lang.String |
getType() This method returns the type of the JWT token. |
byte[] |
getX509CertThumbprint() This method returns the Base64url encoded SHA-1 thumbprint of the X.509 certificate, which can be used to validate the JWT signature. |
java.net.URL |
getX509URL() This method returns the URL pointing to the X.509 public key certificate or certificate chain that can be used to validate the signature. |
java.lang.String |
serializeUnsigned() This method is used to get the Base64url representation of the JWT token without any digital signature. |
void |
setAlgorithm(java.lang.String algorithm) This method sets cryptographic algorithm used to secure the JWS. |
void |
setAudience(java.lang.String audience) This method sets the aud claim in the JWT claim segment. |
void |
setClaimParameter(java.lang.String claimParameter, java.lang.Object value) This method is used to set the custom claims in the JWT claim segment. |
void |
setExpiryTime(java.util.Date expiryTime) This method sets the exp claim in the JWT claim segment. |
void |
setHeaderParameter(java.lang.String headerParameter, java.lang.Object value) This method is used to set the custom claims in the JWT header segment. |
void |
setIssuer(java.lang.String issuer) This method sets the iss claim in the JWT claim segment. |
void |
setIssueTime(java.util.Date issueTime) This method sets the iat claim in the JWT claim segment. |
void |
setJsonKeyURL(java.net.URL jsonKeyURL) This method sets the jku header parameter in the JWT header segment. |
void |
setKeyID(java.lang.String keyID) This method sets the kid header parameter in the JWT header segment. |
void |
setPrincipal(java.lang.String principal) This method sets the prn claim in the JWT claim segment. |
void |
setType(java.lang.String type) The value of the header parameter typ is case sensitive and optional, and if present the recommended values are either "JWT" or "http://openid.net/specs/jwt/1.0". |
void |
setX509CertThumbprint(java.security.cert.X509Certificate cert) This method sets the x5t header parameter in the JWT header segment. |
void |
setX509URL(java.net.URL x509url) This method sets the x5u header parameter in the JWT header segment. |
java.lang.String |
signAndSerialize(byte[] secret) This method returns the Base64url representation of the JWT token including the Crypto segment. |
java.lang.String |
signAndSerialize(java.security.PrivateKey privateKey) This method returns the Base64url representation of the JWT token including the Crypto segment. |
static java.lang.String |
toBase64url(byte[] data) Returns the Base64url encoding of the given byte array. |
java.lang.String |
toString() This method returns the text representation of the name/value pair defined in the JWT token. |
boolean |
verify(byte[] secret) This method is used to verify the digitally signed JWT token. |
boolean |
verify(java.security.PublicKey publicKey) This method is used to verify the digitally signed JWT token. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String JWT
This string constant represents the standard JWT token type
public static final java.lang.String JWT_URI
This string constant represents the standard JWT token type uri
Constructor Detail |
---|
public JwtToken()
This constructor is used to build the JWT token. The default value of the header parameter alg
is set to "none".
public JwtToken(java.lang.String jwtString) throws JwtException
This constructor is used when Base64url encoded JWT token is required to be parsed in to JwtToken Class instance.
jwtString
- the Base64url encoded JWT token to be parsedJwtException
- if some error occurs while deserialization of the JWT Base64url stringMethod Detail |
---|
public static byte[] fromBase64url(java.lang.String s)
s
- the string to be decoded.public static java.lang.String toBase64url(byte[] data)
data
- the data to be encoded.public java.lang.String getAlgorithm()
This method returns the cryptographic algorithm used to secure the JWS.
public java.lang.String getAudience()
public java.lang.Object getClaimParameter(java.lang.String claim)
String
and the value is a JSON Object. The simple data binding is used for processing JSON. Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls.claim
-public java.util.Map<java.lang.String,java.lang.Object> getClaimParameters()
String
and the value is a JSON Object. The simple data binding is used for processing JSON. Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls.public java.util.Date getExpiryTime()
This method returns the expiration time of the JWT token.
Date
public java.lang.Object getHeaderParameter(java.lang.String header)
String
and the value is a JSON Object. The simple data binding is used for processing JSON. Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls.header
-public java.util.Map<java.lang.String,java.lang.Object> getHeaderParameters()
String
and the value is a JSON Object.The simple data binding is used for processing JSON. Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls.public java.lang.String getIssuer()
This method returns the issuer of the JWT token.
public java.util.Date getIssueTime()
This method returns the issue time of the JWT token.
Date
public java.net.URL getJsonKeyURL() throws java.net.MalformedURLException
This method returns the URL that points to JSON-encoded public keys that can be used to validate the signature. The keys is encoded as per the JSON Web Key (JWK)
URL
java.net.MalformedURLException
- if the value of the parameter "jku" can not be converted in to a valid URLpublic java.lang.String getKeyID()
This method returns the key id. It gives a pointer to a specific key owned by the signer, which should be used to validate the signature.
public java.lang.String getPrincipal()
This method returns the principal of the JWT token.
public java.lang.String getType()
This method returns the type of the JWT token.
public byte[] getX509CertThumbprint()
This method returns the Base64url encoded SHA-1 thumbprint of the X.509 certificate, which can be used to validate the JWT signature.
byte[]
public java.net.URL getX509URL() throws java.net.MalformedURLException
This method returns the URL pointing to the X.509 public key certificate or certificate chain that can be used to validate the signature.
URL
java.net.MalformedURLException
- if the value of the parameter "x5u" can not be converted in to a valid URLpublic java.lang.String serializeUnsigned() throws JwtException
This method is used to get the Base64url representation of the JWT token without any digital signature. The Crypto JWT segment of the unsigned JWT token will an EMPTY String
.
JwtException
public void setAlgorithm(java.lang.String algorithm)
This method sets cryptographic algorithm used to secure the JWS.
algorithm
- the algorithm to set.
The JSON Web Signature Reserved Algorithm Values are HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512. The enum JwtToken.SIGN_ALGORITHM
represents these values.
Algorithm | Description |
---|---|
HS256 |
HMAC using SHA-256 hash algorithm |
HS384 |
HMAC using SHA-384 hash algorithm |
HS512 |
HMAC using SHA-512 hash algorithm2 |
RS256 |
RSA using SHA-256 hash algorithm |
RS384 |
RSA using SHA-384 hash algorithm |
RS512 |
RSA using SHA-512 hash algorithm |
ES256 |
ECDSA using P-256 curve and SHA-256 hash algorithm |
ES384 |
ECDSA using P-384 curve and SHA-384 hash algorithm |
ES512 |
ECDSA using P-521 curve and SHA-512 hash algorithm |
none |
The algorithm value "none", if the digital signature of JWT token is not required. |
public void setAudience(java.lang.String audience)
This method sets the aud
claim in the JWT claim segment. This claim identifies the audience that the JWT is intended for. The principal intended to process the JWT MUST be identified by the value of the audience claim.
audience
- the audience to setpublic void setClaimParameter(java.lang.String claimParameter, java.lang.Object value)
This method is used to set the custom claims in the JWT claim segment. The name of the claim must be a String
and the value of the claim must be a JSON Object. The simple data binding is used for processing JSON. Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls.
claim
- the name of the claim parametervalue
- the value of the claim parameterpublic void setExpiryTime(java.util.Date expiryTime)
This method sets the exp
claim in the JWT claim segment. This claim identifies the expiration time on or after which the token MUST NOT be accepted for processing.
expiryTime
- the expiry time to setpublic void setHeaderParameter(java.lang.String headerParameter, java.lang.Object value)
This method is used to set the custom claims in the JWT header segment. The name of the header must be a String
and the value of the claim must be a JSON Object. The simple data binding is used for processing JSON. Simple data binding means converting to and from Java Maps, Lists, Strings, Numbers, Booleans and nulls.
headerParameter
- the name of the header parametervalue
- the value of the header parameterpublic void setIssuer(java.lang.String issuer)
This method sets the iss
claim in the JWT claim segment. This claim identifies the principal that issued the JWT.
issuer
- the issuer to setpublic void setIssueTime(java.util.Date issueTime)
This method sets the iat
claim in the JWT claim segment. This claim identifies the UTC time at which the JWT was issued.
issueTime
- the issue time to setpublic void setJsonKeyURL(java.net.URL jsonKeyURL)
This method sets the jku
header parameter in the JWT header segment. This header parameter is a URL that points to JSON-encoded public keys that can be used to validate the signature. The keys MUST be encoded as per the JSON Web Key (JWK).
jsonKeyURL
- the JSON key URL to setpublic void setKeyID(java.lang.String keyID)
This method sets the kid
header parameter in the JWT header segment. This header parameter value gives a pointer for a specific key owned by the signer, which should be used to validate the signature. This allows signers to explicitly signal a change of key to recipients.
keyID
- the keyID to setpublic void setPrincipal(java.lang.String principal)
This method sets the prn
claim in the JWT claim segment. This claim identifies to the principal for whom the access token is being requested.
audience
- the principal to setpublic void setType(java.lang.String type)
The value of the header parameter typ
is case sensitive and optional, and if present the recommended values are either "JWT" or "http://openid.net/specs/jwt/1.0". The String constants JWT
and JWT_URI
represents these values respectively.
type
- the type of JWT token to setpublic void setX509CertThumbprint(java.security.cert.X509Certificate cert) throws JwtException
This method sets the x5t
header parameter in the JWT header segment. This header parameter identifies to a base64url encoded SHA-1 thumbprint of an X.509 certificate
x509CertThumbprint
- the x509Certificate whose thumbprint is to be setJwtException
public void setX509URL(java.net.URL x509url)
This method sets the x5u
header parameter in the JWT header segment. This header parameter corresponds to a URL that points to an X.509 public key certificate or certificate chain that can be used to validate the signature.
x509url
- the x509URL to setpublic java.lang.String signAndSerialize(byte[] secret) throws SigningException, JwtException
This method returns the Base64url representation of the JWT token including the Crypto segment. The following steps are followed:-
1. The signing input is created by the concatenation of the JWT header segment (Base64url), a period ('.') character, and JWT claim segment (Base64url).
2. The digital signature of the above signing input is computed using the provided key. The Crypto segment is the Base64url representation of the computed digital signature
3. The result of the signing of the JWT token will be the concatenation of the JWT header segment, a period ('.') character, JWT claim segment , a period ('.') character, and JWT Crypto segment.
secret
- The MAC key or password to be used to compute the HMAC signature bytesSigningException
JwtException
public java.lang.String signAndSerialize(java.security.PrivateKey privateKey) throws SigningException, JwtException
This method returns the Base64url representation of the JWT token including the Crypto segment. The following steps are followed:-
1. The signing input is created by the concatenation of the JWT header segment (Base64url), a period ('.') character, and JWT claim segment (Base64url).
2. The digital signature of the above signing input is computed using the provided key. The Crypto segment is the Base64url representation of the computed digital signature
3. The result of the signing of the JWT token will be the concatenation of the JWT header segment, a period ('.') character, JWT claim segment , a period ('.') character, and JWT Crypto segment. *
privateKey
- the key to be used to sign the JWT inputSigningException
JwtException
public java.lang.String toString()
This method returns the text representation of the name/value pair defined in the JWT token. First segment is the name/value pairs of the header segment and the second segment is the collection of the name/value pair of the claim segment.
toString
in class java.lang.Object
public boolean verify(byte[] secret) throws VerifyException
This method is used to verify the digitally signed JWT token. It does nothing, if the token is not signed (i.e., the crypto segment of the JWT token is an empty string).
secret
- the secret to be used to verify the HMAC signature bytes of the JWT tokenVerifyException
- if an error occurs while verifying the signature of the JWT tokenpublic boolean verify(java.security.PublicKey publicKey) throws VerifyException
This method is used to verify the digitally signed JWT token. No signature verification is done, if the token is not signed (i.e., the Crypto segment of the JWT token is an empty string), and the value of the header parameter alg
is "none".
publicKey
- the key to be used to verify the signature of the JWT tokenVerifyException
- if some error occurs while verifying the signature of JWT token
|
Oracle Fusion Middleware REST Security Java API Reference for Oracle Security Developer Tools 11g Release 1 (11.1.1) E26380-02 |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |