com.google.api.client.auth.openidconnect

Class IdTokenVerifier

java.lang.Object

com.google.api.client.auth.openidconnect.IdTokenVerifier

public class IdTokenVerifier
extends Object

Thread-safe ID token verifier based on ID Token Validation.

Call verify(IdToken) to verify an ID token. This is a light-weight object, so you may use a new instance for each configuration of expected issuer and trusted client IDs. Sample usage:

 IdTokenVerifier verifier = new IdTokenVerifier.Builder()
 .setIssuer("issuer.example.com")
 .setAudience(Arrays.asList("myClientId"))
 .build();
 ...
 if (!verifier.verify(idToken)) {...}
 

The verifier validates token signature per current OpenID Connect Spec: https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation By default, method gets a certificate from well-known location A request to certificate location is performed using NetHttpTransport Either or both certificate location and transport implementation can be overridden via IdTokenVerifier.Builder

 IdTokenVerifier verifier = new IdTokenVerifier.Builder()
 .setIssuer("issuer.example.com")
 .setAudience(Arrays.asList("myClientId"))
 .setHttpTransportFactory(customHttpTransportFactory)
 .build();
 ...
 if (!verifier.verify(idToken)) {...}
 

not recommended: this check can be disabled with OAUTH_CLIENT_SKIP_SIGNATURE environment variable set to true. Use verifyPayload(IdToken) instead.

Note that verify(IdToken) only implements a subset of the verification steps, mostly just the MUST steps. Please read ID Token Validation for the full list of verification steps.

Since:

1.16

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IdTokenVerifier.Builder Builder for IdTokenVerifier.

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_TIME_SKEW_SECONDS Default value for seconds of time skew to accept when verifying time (5 minutes).

Constructor Summary

Constructors

Modifier	Constructor and Description
	IdTokenVerifier()
protected	IdTokenVerifier(IdTokenVerifier.Builder builder)

Method Summary

Modifier and Type	Method and Description
long	getAcceptableTimeSkewSeconds() Returns the seconds of time skew to accept when verifying time.
Collection<String>	getAudience() Returns the unmodifiable list of trusted audience client IDs or null to suppress the audience check.
com.google.api.client.util.Clock	getClock() Returns the clock.
String	getIssuer() Returns the first of equivalent expected issuers or null if issuer check suppressed.
Collection<String>	getIssuers() Returns the equivalent expected issuers or null if issuer check suppressed.
boolean	verify(IdToken idToken) Deprecated.
boolean	verifyOrThrow(IdToken idToken) Verifies that the given ID token is valid using the cached public keys.
protected boolean	verifyPayload(IdToken idToken) Verifies the payload of the given ID token It verifies: The issuer is one of getIssuers() by calling IdToken.verifyIssuer(String).

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_TIME_SKEW_SECONDS

public static final long DEFAULT_TIME_SKEW_SECONDS

Default value for seconds of time skew to accept when verifying time (5 minutes).

See Also:

Constant Field Values

Constructor Detail

IdTokenVerifier

public IdTokenVerifier()

IdTokenVerifier

protected IdTokenVerifier(IdTokenVerifier.Builder builder)

Parameters:

builder - builder

Method Detail

getClock

public final com.google.api.client.util.Clock getClock()

Returns the clock.

getAcceptableTimeSkewSeconds

public final long getAcceptableTimeSkewSeconds()

Returns the seconds of time skew to accept when verifying time.

getIssuer

public final String getIssuer()

Returns the first of equivalent expected issuers or null if issuer check suppressed.

getIssuers

public final Collection<String> getIssuers()

Returns the equivalent expected issuers or null if issuer check suppressed.

Since:

1.21.0

getAudience

public final Collection<String> getAudience()

Returns the unmodifiable list of trusted audience client IDs or null to suppress the audience check.

verify

@Deprecated
public boolean verify(IdToken idToken)

Deprecated.

Verifies that the given ID token is valid using the cached public keys.

It verifies:

• The issuer is one of getIssuers() by calling IdToken.verifyIssuer(String).
• The audience is one of getAudience() by calling IdToken.verifyAudience(Collection).
• The current time against the issued at and expiration time, using the getClock() and allowing for a time skew specified in getAcceptableTimeSkewSeconds() , by calling IdToken.verifyTime(long, long).
• This method verifies token signature per current OpenID Connect Spec: https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation. By default, method gets a certificate from well-known location. A request to certificate location is performed using NetHttpTransport Both certificate location and transport implementation can be overridden via IdTokenVerifier.Builder not recommended: this check can be disabled with OAUTH_CLIENT_SKIP_SIGNATURE environment variable set to true. Use verifyPayload(IdToken) instead.

Deprecated. This method returns false if network requests to get certificates fail. Use IdTokenVerifier.verfyOrThrow(IdToken) instead to differentiate between potentially retryable network errors and false verification results.

Parameters:

idToken - ID token

Returns:

true if verified successfully or false if failed

verifyOrThrow

public boolean verifyOrThrow(IdToken idToken)
                      throws IOException

Verifies that the given ID token is valid using the cached public keys.

It verifies:

• The issuer is one of getIssuers() by calling IdToken.verifyIssuer(String).
• The audience is one of getAudience() by calling IdToken.verifyAudience(Collection).
• The current time against the issued at and expiration time, using the getClock() and allowing for a time skew specified in getAcceptableTimeSkewSeconds() , by calling IdToken.verifyTime(long, long).
• This method verifies token signature per current OpenID Connect Spec: https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation. By default, method gets a certificate from well-known location. A request to certificate location is performed using NetHttpTransport Both certificate location and transport implementation can be overridden via IdTokenVerifier.Builder not recommended: this check can be disabled with OAUTH_CLIENT_SKIP_SIGNATURE environment variable set to true.

Overriding is allowed, but it must call the super implementation.

Parameters:

idToken - ID token

Returns:

true if verified successfully or false if payload validation failed

Throws:

IOException - if verification fails to run. For example, if it fails to get public keys for signature verification.

verifyPayload

protected boolean verifyPayload(IdToken idToken)

Verifies the payload of the given ID token

It verifies:

• The issuer is one of getIssuers() by calling IdToken.verifyIssuer(String).
• The audience is one of getAudience() by calling IdToken.verifyAudience(Collection).
• The current time against the issued at and expiration time, using the getClock() and allowing for a time skew specified in getAcceptableTimeSkewSeconds() , by calling IdToken.verifyTime(long, long).

Overriding is allowed, but it must call the super implementation.

Parameters:

idToken - ID token

Returns:

true if verified successfully or false if failed