Package com.nimbusds.oauth2.sdk.jarm

Class JARMValidator

java.lang.Object

com.nimbusds.openid.connect.sdk.validators.AbstractJWTValidator

com.nimbusds.oauth2.sdk.jarm.JARMValidator

All Implemented Interfaces:

com.nimbusds.jwt.proc.ClockSkewAware

@ThreadSafe
public class JARMValidator
extends AbstractJWTValidator
implements com.nimbusds.jwt.proc.ClockSkewAware

Validator of JSON Web Token (JWT) secured authorisation responses (JARM).

Supports processing of JWT responses with the following protection:

• JWTs signed (JWS) with the Authorisation Server's RSA or EC key, require the Authorisation Server's public JWK set (provided by value or URL) to verify them.
• JWTs authenticated with a JWS HMAC, require the client's secret to verify them.

Convenience static methods for creating a validator from Authorisation Server metadata or issuer URL, and the registered OAuth 2.0 client information:

• create(AuthorizationServerMetadata, ClientInformation)
• create(Issuer, ClientInformation)

Related specifications:

• Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM).

Field Summary

Fields inherited from class com.nimbusds.openid.connect.sdk.validators.AbstractJWTValidator

DEFAULT_MAX_CLOCK_SKEW

Constructor Summary

Constructors

Constructor	Description
JARMValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, com.nimbusds.jose.jwk.JWKSet jwkSet)	Creates a new JARM validator for RSA or EC signed authorisation responses where the Authorisation Server's JWK set is specified by value.
JARMValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, Secret clientSecret)	Creates a new JARM validator for HMAC protected authorisation responses.
JARMValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, URL jwkSetURI)	Creates a new JARM validator for RSA or EC signed authorisation responses where the Authorisation Server's JWK set is specified by URL.
JARMValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, URL jwkSetURI, com.nimbusds.jose.util.ResourceRetriever resourceRetriever)	Creates a new JARM validator for RSA or EC signed authorisation responses where the Authorisation Server's JWK set is specified by URL.
JARMValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.proc.JWSKeySelector jwsKeySelector, com.nimbusds.jose.proc.JWEKeySelector jweKeySelector)	Creates a new JARM validator.

Method Summary

Modifier and Type	Method	Description
static JARMValidator	create(AuthorizationServerMetadata asMetadata, ClientInformation clientInfo)	Creates a new JARM validator for the specified Authorisation Server metadata and OAuth 2.0 client registration.
static JARMValidator	create(AuthorizationServerMetadata asMetadata, ClientInformation clientInfo, com.nimbusds.jose.jwk.source.JWKSource clientJWKSource)	Creates a new JARM validator for the specified Authorisation Server metadata and OAuth 2.0 client registration.
static JARMValidator	create(Issuer issuer, ClientInformation clientInfo)	Creates a new JARM validator for the specified Authorisation Server or OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/oauth-authorization-server resp.
static JARMValidator	create(Issuer issuer, ClientInformation clientInfo, com.nimbusds.jose.jwk.source.JWKSource clientJWKSource, int connectTimeout, int readTimeout)	Creates a new JARM validator for the specified Authorisation Server or OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/oauth-authorization-server resp.
protected static com.nimbusds.jose.proc.JWEKeySelector	createJWEKeySelector(AuthorizationServerMetadata asMetadata, ClientInformation clientInfo, com.nimbusds.jose.jwk.source.JWKSource clientJWKSource)	Creates a key selector for JWE decryption.
protected static com.nimbusds.jose.proc.JWSKeySelector	createJWSKeySelector(AuthorizationServerMetadata asMetadata, ClientInformation clientInfo)	Creates a key selector for JWS verification.
com.nimbusds.jwt.JWTClaimsSet	validate(com.nimbusds.jwt.JWT jwtResponse)	Validates the specified JWT-secured authorisation response.
com.nimbusds.jwt.JWTClaimsSet	validate(String jwtResponseString)	Validates the specified JWT-secured authorisation response.

Methods inherited from class com.nimbusds.openid.connect.sdk.validators.AbstractJWTValidator

getClientID, getExpectedIssuer, getJWEKeySelector, getJWSKeySelector, getMaxClockSkew, setMaxClockSkew

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.nimbusds.jwt.proc.ClockSkewAware

getMaxClockSkew, setMaxClockSkew

Constructor Detail

JARMValidator

public JARMValidator(Issuer expectedIssuer,
                     ClientID clientID,
                     com.nimbusds.jose.JWSAlgorithm expectedJWSAlg,
                     com.nimbusds.jose.jwk.JWKSet jwkSet)

Creates a new JARM validator for RSA or EC signed authorisation responses where the Authorisation Server's JWK set is specified by value.

Parameters:

expectedIssuer - The expected issuer (Authorisation Server). Must not be null.

clientID - The client ID. Must not be null.

expectedJWSAlg - The expected RSA or EC JWS algorithm. Must not be null.

jwkSet - The Authorisation Server JWK set. Must not be null.

JARMValidator

public JARMValidator(Issuer expectedIssuer,
                     ClientID clientID,
                     com.nimbusds.jose.JWSAlgorithm expectedJWSAlg,
                     URL jwkSetURI)

Creates a new JARM validator for RSA or EC signed authorisation responses where the Authorisation Server's JWK set is specified by URL.

Parameters:

expectedIssuer - The expected issuer (Authorisation Server). Must not be null.

clientID - The client ID. Must not be null.

expectedJWSAlg - The expected RSA or EC JWS algorithm. Must not be null.

jwkSetURI - The OpenID Provider JWK set URL. Must not be null.

JARMValidator

public JARMValidator(Issuer expectedIssuer,
                     ClientID clientID,
                     com.nimbusds.jose.JWSAlgorithm expectedJWSAlg,
                     URL jwkSetURI,
                     com.nimbusds.jose.util.ResourceRetriever resourceRetriever)

Creates a new JARM validator for RSA or EC signed authorisation responses where the Authorisation Server's JWK set is specified by URL. Permits setting of a specific resource retriever (HTTP client) for the JWK set.

Parameters:

expectedIssuer - The expected issuer (Authorisation Server). Must not be null.

clientID - The client ID. Must not be null.

expectedJWSAlg - The expected RSA or EC JWS algorithm. Must not be null.

jwkSetURI - The Authorisation Server JWK set URL. Must not be null.

resourceRetriever - For retrieving the Authorisation Server JWK from the specified URL. If null the default retriever will be used, with preset HTTP connect timeout, HTTP read timeout and entity size limit.

JARMValidator

public JARMValidator(Issuer expectedIssuer,
                     ClientID clientID,
                     com.nimbusds.jose.JWSAlgorithm expectedJWSAlg,
                     Secret clientSecret)

Creates a new JARM validator for HMAC protected authorisation responses.

Parameters:

expectedIssuer - The expected issuer (Authorisation Server). Must not be null.

clientID - The client ID. Must not be null.

expectedJWSAlg - The expected HMAC JWS algorithm. Must not be null.

clientSecret - The client secret. Must not be null.

JARMValidator

public JARMValidator(Issuer expectedIssuer,
                     ClientID clientID,
                     com.nimbusds.jose.proc.JWSKeySelector jwsKeySelector,
                     com.nimbusds.jose.proc.JWEKeySelector jweKeySelector)

Creates a new JARM validator.

Parameters:

expectedIssuer - The expected issuer (Authorisation Server). Must not be null.

clientID - The client ID. Must not be null.

jwsKeySelector - The key selector for JWS verification, must not be null.

jweKeySelector - The key selector for JWE decryption, null if encrypted authorisation responses are not expected.

Method Detail

validate

public com.nimbusds.jwt.JWTClaimsSet validate(String jwtResponseString)
                                       throws com.nimbusds.jose.proc.BadJOSEException,
                                              com.nimbusds.jose.JOSEException

Validates the specified JWT-secured authorisation response.

Parameters:

jwtResponseString - The JWT-secured authorisation response string. Must not be null.

Returns:

The claims set of the verified JWT.

Throws:

com.nimbusds.jose.proc.BadJOSEException - If the JWT is invalid or expired.

com.nimbusds.jose.JOSEException - If an internal JOSE exception was encountered.

validate

public com.nimbusds.jwt.JWTClaimsSet validate(com.nimbusds.jwt.JWT jwtResponse)
                                       throws com.nimbusds.jose.proc.BadJOSEException,
                                              com.nimbusds.jose.JOSEException

Validates the specified JWT-secured authorisation response.

Parameters:

jwtResponse - The JWT-secured authorisation response. Must not be null.

Returns:

The claims set of the verified JWT.

Throws:

com.nimbusds.jose.proc.BadJOSEException - If the JWT is invalid or expired.

com.nimbusds.jose.JOSEException - If an internal JOSE exception was encountered.

createJWSKeySelector

protected static com.nimbusds.jose.proc.JWSKeySelector createJWSKeySelector(AuthorizationServerMetadata asMetadata,
                                                                            ClientInformation clientInfo)
                                                                     throws GeneralException

Creates a key selector for JWS verification.

Parameters:

asMetadata - The Authorisation Server metadata. Must not be null.

clientInfo - The OAuth 2.0 client information. Must not be null.

Returns:

The JWS key selector.

Throws:

GeneralException - If the supplied Authorisation Server metadata or OAuth 2.0 client information are missing a required parameter or inconsistent.

createJWEKeySelector

protected static com.nimbusds.jose.proc.JWEKeySelector createJWEKeySelector(AuthorizationServerMetadata asMetadata,
                                                                            ClientInformation clientInfo,
                                                                            com.nimbusds.jose.jwk.source.JWKSource clientJWKSource)
                                                                     throws GeneralException

Creates a key selector for JWE decryption.

Parameters:

asMetadata - The Authorisation Server metadata. Must not be null.

clientInfo - The OAuth 2.0 client information. Must not be null.

clientJWKSource - The client private JWK source, null if encrypted JWT-secured authorisation responses are not expected.

Returns:

The JWE key selector.

Throws:

GeneralException - If the supplied Authorisation Server metadata or OAuth 2.0 client information are missing a required parameter or inconsistent.

create

public static JARMValidator create(AuthorizationServerMetadata asMetadata,
                                   ClientInformation clientInfo,
                                   com.nimbusds.jose.jwk.source.JWKSource clientJWKSource)
                            throws GeneralException

Creates a new JARM validator for the specified Authorisation Server metadata and OAuth 2.0 client registration.

Parameters:

asMetadata - The Authorisation Server metadata. Must not be null.

clientInfo - The OAuth 2.0 client registration. Must not be null.

clientJWKSource - The client private JWK source, null if encrypted authorisation responses are not expected.

Returns:

The JARM validator.

Throws:

GeneralException - If the supplied Authorisation Server metadata or OAuth 2.0 client information are missing a required parameter or inconsistent.

create

public static JARMValidator create(AuthorizationServerMetadata asMetadata,
                                   ClientInformation clientInfo)
                            throws GeneralException

Creates a new JARM validator for the specified Authorisation Server metadata and OAuth 2.0 client registration.

Parameters:

asMetadata - The Authorisation Server metadata. Must not be null.

clientInfo - The OAuth 2.0 client registration. Must not be null.

Returns:

The JARM validator.

Throws:

GeneralException - If the supplied Authorisation Server metadata or OAuth 2.0 client information are missing a required parameter or inconsistent.

create

public static JARMValidator create(Issuer issuer,
                                   ClientInformation clientInfo)
                            throws GeneralException,
                                   IOException

Creates a new JARM validator for the specified Authorisation Server or OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/oauth-authorization-server resp. [issuer-url]/.well-known/openid-configuration.

Parameters:

issuer - The Authorisation Server / OpenID Provider issuer identifier. Must not be null.

clientInfo - The OAuth 2.0 client registration. Must not be null.

Returns:

The JARM validator.

Throws:

GeneralException - If the resolved Authorisation Server / OpenID Provider metadata is invalid.

IOException - On a HTTP exception.

create

public static JARMValidator create(Issuer issuer,
                                   ClientInformation clientInfo,
                                   com.nimbusds.jose.jwk.source.JWKSource clientJWKSource,
                                   int connectTimeout,
                                   int readTimeout)
                            throws GeneralException,
                                   IOException

Creates a new JARM validator for the specified Authorisation Server or OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/oauth-authorization-server resp. [issuer-url]/.well-known/openid-configuration.

Parameters:

issuer - The Authorisation Server / OpenID Provider issuer identifier. Must not be null.

clientInfo - The OAuth 2.0 client registration. Must not be null.

clientJWKSource - The client private JWK source, null if encrypted authorisation responses are not expected.

connectTimeout - The HTTP connect timeout, in milliseconds. Zero implies no timeout. Must not be negative.

readTimeout - The HTTP response read timeout, in milliseconds. Zero implies no timeout. Must not be negative.

Returns:

The JARM validator.

Throws:

GeneralException - If the resolved Authorisation Server / OpenID Provider metadata is invalid.

IOException - On a HTTP exception.