com.nimbusds.openid.connect.sdk.validators

Class IDTokenValidator

java.lang.Object

com.nimbusds.openid.connect.sdk.validators.IDTokenValidator

All Implemented Interfaces:

com.nimbusds.jwt.proc.ClockSkewAware

@ThreadSafe
public class IDTokenValidator
extends Object
implements com.nimbusds.jwt.proc.ClockSkewAware

Validator of ID tokens issued by an OpenID Provider (OP).

Supports processing of ID tokens with the following protection:

• ID tokens signed (JWS) with the OP's RSA or EC key, require the OP public JWK set (provided by value or URL) to verify them.
• ID tokens authenticated with a JWS HMAC, require the client's secret to verify them.
• Unsecured (plain) ID tokens received at the token endpoint.

Convenience static methods for creating an ID token validator from OpenID Provider metadata or issuer URL, and the registered Relying Party information:

• create(OIDCProviderMetadata, OIDCClientInformation)
• create(Issuer, OIDCClientInformation)

Related specifications:

• OpenID Connect Core 1.0, sections 3.1.3.7, 3.2.2.11 and 3.3.2.12.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_CLOCK_SKEW The default maximum acceptable clock skew for verifying token timestamps, in seconds.

Constructor Summary

Constructors

Constructor and Description
IDTokenValidator(Issuer expectedIssuer, ClientID clientID) Creates a new validator for unsecured (plain) ID tokens.
IDTokenValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, com.nimbusds.jose.jwk.JWKSet jwkSet) Creates a new validator for RSA or EC signed ID tokens where the OpenID Provider's JWK set is specified by value.
IDTokenValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, Secret clientSecret) Creates a new validator for HMAC protected ID tokens.
IDTokenValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, URL jwkSetURI) Creates a new validator for RSA or EC signed ID tokens where the OpenID Provider's JWK set is specified by URL.
IDTokenValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.JWSAlgorithm expectedJWSAlg, URL jwkSetURI, com.nimbusds.jose.util.ResourceRetriever resourceRetriever) Creates a new validator for RSA or EC signed ID tokens where the OpenID Provider's JWK set is specified by URL.
IDTokenValidator(Issuer expectedIssuer, ClientID clientID, com.nimbusds.jose.proc.JWSKeySelector jwsKeySelector, com.nimbusds.jose.proc.JWEKeySelector jweKeySelector) Creates a new ID token validator.

Method Summary

Modifier and Type	Method and Description
static IDTokenValidator	create(Issuer opIssuer, OIDCClientInformation clientInfo) Creates a new ID token validator for the specified OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/openid-configuration.
static IDTokenValidator	create(Issuer opIssuer, OIDCClientInformation clientInfo, com.nimbusds.jose.jwk.source.JWKSource clientJWKSource, int connectTimeout, int readTimeout) Creates a new ID token validator for the specified OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/openid-configuration.
static IDTokenValidator	create(OIDCProviderMetadata opMetadata, OIDCClientInformation clientInfo) Creates a new ID token validator for the specified OpenID Provider metadata and OpenID Relying Party registration.
static IDTokenValidator	create(OIDCProviderMetadata opMetadata, OIDCClientInformation clientInfo, com.nimbusds.jose.jwk.source.JWKSource clientJWKSource) Creates a new ID token validator for the specified OpenID Provider metadata and OpenID Relying Party registration.
protected static com.nimbusds.jose.proc.JWEKeySelector	createJWEKeySelector(OIDCProviderMetadata opMetadata, OIDCClientInformation clientInfo, com.nimbusds.jose.jwk.source.JWKSource clientJWKSource) Creates a key selector for JWE decryption.
protected static com.nimbusds.jose.proc.JWSKeySelector	createJWSKeySelector(OIDCProviderMetadata opMetadata, OIDCClientInformation clientInfo) Creates a key selector for JWS verification.
ClientID	getClientID() Returns the client ID (the expected token audience).
Issuer	getExpectedIssuer() Returns the expected token issuer.
com.nimbusds.jose.proc.JWEKeySelector	getJWEKeySelector() Returns the configured JWE key selector for encrypted token decryption.
com.nimbusds.jose.proc.JWSKeySelector	getJWSKeySelector() Returns the configured JWS key selector for signed token verification.
int	getMaxClockSkew() Gets the maximum acceptable clock skew for verifying the token timestamps.
void	setMaxClockSkew(int maxClockSkew) Sets the maximum acceptable clock skew for verifying the token timestamps.
IDTokenClaimsSet	validate(com.nimbusds.jwt.JWT idToken, Nonce expectedNonce) Validates the specified ID token.

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

Field Detail

DEFAULT_MAX_CLOCK_SKEW

public static final int DEFAULT_MAX_CLOCK_SKEW

The default maximum acceptable clock skew for verifying token timestamps, in seconds.

See Also:

Constant Field Values

Constructor Detail

IDTokenValidator

public IDTokenValidator(Issuer expectedIssuer,
                        ClientID clientID)

Creates a new validator for unsecured (plain) ID tokens.

Parameters:

expectedIssuer - The expected ID token issuer (OpenID Provider). Must not be null.

clientID - The client ID. Must not be null.

IDTokenValidator

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

Creates a new validator for RSA or EC signed ID tokens where the OpenID Provider's JWK set is specified by value.

Parameters:

expectedIssuer - The expected ID token issuer (OpenID Provider). 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 OpenID Provider JWK set. Must not be null.

IDTokenValidator

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

Creates a new validator for RSA or EC signed ID tokens where the OpenID Provider's JWK set is specified by URL.

Parameters:

expectedIssuer - The expected ID token issuer (OpenID Provider). 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.

IDTokenValidator

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

Creates a new validator for RSA or EC signed ID tokens where the OpenID Provider's JWK set is specified by URL. Permits setting of a specific resource retriever (HTTP client) for the JWK set.

Parameters:

expectedIssuer - The expected ID token issuer (OpenID Provider). 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.

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

IDTokenValidator

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

Creates a new validator for HMAC protected ID tokens.

Parameters:

expectedIssuer - The expected ID token issuer (OpenID Provider). 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.

IDTokenValidator

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

Creates a new ID token validator.

Parameters:

expectedIssuer - The expected ID token issuer (OpenID Provider). Must not be null.

clientID - The client ID. Must not be null.

jwsKeySelector - The key selector for JWS verification, null if unsecured (plain) ID tokens are expected.

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

Method Detail

validate

public IDTokenClaimsSet validate(com.nimbusds.jwt.JWT idToken,
                                 Nonce expectedNonce)
                          throws com.nimbusds.jose.proc.BadJOSEException,
                                 com.nimbusds.jose.JOSEException

Validates the specified ID token.

Parameters:

idToken - The ID token. Must not be null.

expectedNonce - The expected nonce, null if none.

Returns:

The claims set of the verified ID token.

Throws:

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

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

createJWSKeySelector

protected static com.nimbusds.jose.proc.JWSKeySelector createJWSKeySelector(OIDCProviderMetadata opMetadata,
                                                                            OIDCClientInformation clientInfo)
                                                                     throws GeneralException

Creates a key selector for JWS verification.

Parameters:

opMetadata - The OpenID Provider metadata. Must not be null.

clientInfo - The Relying Party metadata. Must not be null.

Returns:

The JWS key selector.

Throws:

GeneralException - If the supplied OpenID Provider metadata or Relying Party metadata are missing a required parameter or inconsistent.

createJWEKeySelector

protected static com.nimbusds.jose.proc.JWEKeySelector createJWEKeySelector(OIDCProviderMetadata opMetadata,
                                                                            OIDCClientInformation clientInfo,
                                                                            com.nimbusds.jose.jwk.source.JWKSource clientJWKSource)
                                                                     throws GeneralException

Creates a key selector for JWE decryption.

Parameters:

opMetadata - The OpenID Provider metadata. Must not be null.

clientInfo - The Relying Party metadata. Must not be null.

clientJWKSource - The client private JWK source, null if encrypted ID tokens are not expected.

Returns:

The JWE key selector.

Throws:

GeneralException - If the supplied OpenID Provider metadata or Relying Party metadata are missing a required parameter or inconsistent.

create

public static IDTokenValidator create(OIDCProviderMetadata opMetadata,
                                      OIDCClientInformation clientInfo,
                                      com.nimbusds.jose.jwk.source.JWKSource clientJWKSource)
                               throws GeneralException

Creates a new ID token validator for the specified OpenID Provider metadata and OpenID Relying Party registration.

Parameters:

opMetadata - The OpenID Provider metadata. Must not be null.

clientInfo - The OpenID Relying Party registration. Must not be null.

clientJWKSource - The client private JWK source, null if encrypted ID tokens are not expected.

Returns:

The ID token validator.

Throws:

GeneralException - If the supplied OpenID Provider metadata or Relying Party metadata are missing a required parameter or inconsistent.

create

public static IDTokenValidator create(OIDCProviderMetadata opMetadata,
                                      OIDCClientInformation clientInfo)
                               throws GeneralException

Creates a new ID token validator for the specified OpenID Provider metadata and OpenID Relying Party registration.

Parameters:

opMetadata - The OpenID Provider metadata. Must not be null.

clientInfo - The OpenID Relying Party registration. Must not be null.

Returns:

The ID token validator.

Throws:

GeneralException - If the supplied OpenID Provider metadata or Relying Party metadata are missing a required parameter or inconsistent.

create

public static IDTokenValidator create(Issuer opIssuer,
                                      OIDCClientInformation clientInfo)
                               throws GeneralException,
                                      IOException

Creates a new ID token validator for the specified OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/openid-configuration.

Parameters:

opIssuer - The OpenID Provider issuer identifier. Must not be null.

clientInfo - The OpenID Relying Party registration. Must not be null.

Returns:

The ID token validator.

Throws:

GeneralException - If the resolved OpenID Provider metadata is invalid.

IOException - On a HTTP exception.

create

public static IDTokenValidator create(Issuer opIssuer,
                                      OIDCClientInformation clientInfo,
                                      com.nimbusds.jose.jwk.source.JWKSource clientJWKSource,
                                      int connectTimeout,
                                      int readTimeout)
                               throws GeneralException,
                                      IOException

Creates a new ID token validator for the specified OpenID Provider, which must publish its metadata at [issuer-url]/.well-known/openid-configuration.

Parameters:

opIssuer - The OpenID Provider issuer identifier. Must not be null.

clientInfo - The OpenID Relying Party registration. Must not be null.

clientJWKSource - The client private JWK source, null if encrypted ID tokens 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 ID token validator.

Throws:

GeneralException - If the resolved OpenID Provider metadata is invalid.

IOException - On a HTTP exception.

getExpectedIssuer

public Issuer getExpectedIssuer()

Returns the expected token issuer.

Returns:

The token issuer.

getClientID

public ClientID getClientID()

Returns the client ID (the expected token audience).

Returns:

The client ID.

getJWSKeySelector

public com.nimbusds.jose.proc.JWSKeySelector getJWSKeySelector()

Returns the configured JWS key selector for signed token verification.

Returns:

The JWS key selector, null if none.

getJWEKeySelector

public com.nimbusds.jose.proc.JWEKeySelector getJWEKeySelector()

Returns the configured JWE key selector for encrypted token decryption.

Returns:

The JWE key selector, null.

getMaxClockSkew

public int getMaxClockSkew()

Gets the maximum acceptable clock skew for verifying the token timestamps.

Specified by:

getMaxClockSkew in interface com.nimbusds.jwt.proc.ClockSkewAware

Returns:

The maximum acceptable clock skew, in seconds. Zero indicates none.

setMaxClockSkew

public void setMaxClockSkew(int maxClockSkew)

Sets the maximum acceptable clock skew for verifying the token timestamps.

Specified by:

setMaxClockSkew in interface com.nimbusds.jwt.proc.ClockSkewAware

Parameters:

maxClockSkew - The maximum acceptable clock skew, in seconds. Zero indicates none. Must not be negative.