com.authlete.common.dto

Class JoseVerifyRequest

java.lang.Object

com.authlete.common.dto.JoseVerifyRequest

All Implemented Interfaces:

Serializable

public class JoseVerifyRequest
extends Object
implements Serializable

Request to Authlete's /api/jose/verify API.

Since:

2.23

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
JoseVerifyRequest()

Method Summary

Modifier and Type	Method and Description
String	getClientIdentifier() Get the identifier of the client application whose keys are required for verification of the JOSE object.
int	getClockSkew() Get the allowable clock skew in seconds.
String	getJose() Get the JOSE object that will be verified.
String[]	getMandatoryClaims() Get the mandatory claims that are required to be included in the JOSE object.
boolean	isSignedByClient() Get the flag which indicates whether the signature of the JOSE object has been signed by a client application with the client's private key or a shared symmetric key.
JoseVerifyRequest	setClientIdentifier(String clientIdentifier) Set the identifier of the client application whose keys are required for verification of the JOSE object.
JoseVerifyRequest	setClockSkew(int clockSkew) Set allowable clock skew in seconds.
JoseVerifyRequest	setJose(String jose) Set a JOSE object that will be verified.
JoseVerifyRequest	setMandatoryClaims(String[] mandatoryClaims) Set mandatory claims that are required to be included in the JOSE object.
JoseVerifyRequest	setSignedByClient(boolean signedByClient) Set the flag which indicates whether the signature of the JOSE object has been signed by a client application with the client's private key or a shared symmetric key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JoseVerifyRequest

public JoseVerifyRequest()

Method Detail

getJose

public String getJose()

Get the JOSE object that will be verified.

Returns:

The JOSE object. For example, a JWT in JWS compact serialization format.

setJose

public JoseVerifyRequest setJose(String jose)

Set a JOSE object that will be verified. This request parameter is mandatory.

If the payload part of the JOSE object can be parsed as JSON and the JSON has an exp claim (Expiration Time Claim), an nbf claim (Not Before Claim) and/or an iat claim (Issued At Claim), their values are checked based on the rules described in RFC 7519.

If getMandatoryClaims() method returns a non-empty array, the payload part of the JOSE object must be able to be parsed as JSON and the JSON must contain the mandatory claims.

Parameters:

jose - A JOSE object. For example, a JWT in JWS compact serialization format.

Returns:

this object.

getMandatoryClaims

public String[] getMandatoryClaims()

Get the mandatory claims that are required to be included in the JOSE object.

Returns:

The mandatory claims.

setMandatoryClaims

public JoseVerifyRequest setMandatoryClaims(String[] mandatoryClaims)

Set mandatory claims that are required to be included in the JOSE object. This request parameter is optional.

When this parameter is specified, it is assumed that the payload part of the JOSE object can be parsed as JSON. The implementation of /api/jose/verify API checks whether the JSON contains the mandatory claims.

When the Content-Type of the request is application/x-www-form-urlencoded, the value of this request parameter should be a string of space-delimited list of claim names.

Parameters:

mandatoryClaims - Mandatory claims.

Returns:

this object.

getClockSkew

public int getClockSkew()

Get the allowable clock skew in seconds.

Returns:

Allowable clock skew in seconds.

setClockSkew

public JoseVerifyRequest setClockSkew(int clockSkew)

Set allowable clock skew in seconds. This request parameter is optional and its default value is 0.

This parameter has a meaning only when the payload part of the JOSE object can be parsed as JSON and the JSON has an exp claim (Expiration Time Claim), an nbf claim (Not Before Claim) and/or an iat claim (Issued At Claim). The claims are time-related ones defined in RFC 7519 (JSON Web Token (JWT)). When the values of the claims are checked, the clock skew specified by this request parameter is taken into consideration.

For example, if the value of the exp claim is 1531193168 and the current time of the system on which the Authlete server runs is 1531193169, the JWT is regarded as invalid because the current time exceeds the expiration time. However, if 2 or a larger value is given as the clock skew, the value of the exp claim will not cause a verification error because the current time does not exceed (1531193168 + the clock skew).

Parameters:

clockSkew - Allowable clock skew in seconds.

Returns:

this object.

getClientIdentifier

public String getClientIdentifier()

Get the identifier of the client application whose keys are required for verification of the JOSE object.

Returns:

The client identifier.

setClientIdentifier

public JoseVerifyRequest setClientIdentifier(String clientIdentifier)

Set the identifier of the client application whose keys are required for verification of the JOSE object. This request parameter can be omitted under some conditions.

If the JOSE object has been signed by a client application with the client's private key or a shared symmetric key (i.e. if isSignedByClient() returns true), or if the signature algorithm is symmetric, a key that corresponds to the key used for the signature needs to be looked up or computed in order to verify the signature.

When the algorithm of the signature is asymmetric, the implementation of /api/jose/verify API searches the JWK Set Document of the client application for the public key which corresponds to the private key used to digitally sign the JOSE object. On the other hand, when the algorithm of the signature is symmetric, the implementation of the API computes the shared symmetric key based on the client secret of the client application by following the rule described in OpenID Connect Core 1.0, 10.1. Signing. In either case, information to identify the client application is needed. This request parameter (clientIdentifier) exists for the purpose.

In addition, if the JOSE object has been encrypted with a symmetric algorithm, the client secret of the client application is needed to compute the symmetric shared key (OpenID Connect Core 1.0, 10.2. Encryption). For this case, information to identify the client application is needed, too. Note that the implementation of /api/jose/verify API cannot decrypt the JOSE object if the encryption algorithm is asymmetric and a client's public key has been used because Authlete cannot access the private key of the client application (as Authlete does not manage private keys of client applications).

When this request parameter is omitted, the implementation of /api/jose/verify API may try to use the value of the iss claim as the value of the client identifier. This may happen only when isSignedByClient() returns true.

Parameters:

clientIdentifier - The client identifier.

Returns:

this object.

isSignedByClient

public boolean isSignedByClient()

Get the flag which indicates whether the signature of the JOSE object has been signed by a client application with the client's private key or a shared symmetric key.

Returns:

true if the JOSE object has been signed by a client application.

setSignedByClient

public JoseVerifyRequest setSignedByClient(boolean signedByClient)

Set the flag which indicates whether the signature of the JOSE object has been signed by a client application with the client's private key or a shared symmetric key. This request parameter is optional and its default value is false.

When true is set to this request parameter, the identifier of the client application needs to be set by setClientIdentifier(String) unless the JOSE object is not encrypted and the iss claim holds the client identifier.

Parameters:

signedByClient - true to indicate that the JOSE object has been signed by a client application.

Returns:

this object.