Package com.nimbusds.openid.connect.sdk.validators

Class IDTokenValidator

  • All Implemented Interfaces:
    com.nimbusds.jwt.proc.ClockSkewAware
    @ThreadSafe
public class IDTokenValidator
extends AbstractJWTValidator
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:

    Related specifications:

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

    • 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.