Class Credential (1.36.0)

Version latest

• 1.36.0 (latest)
• 1.34.1
• 1.33.3
• 1.32.1

public class Credential implements HttpExecuteInterceptor, HttpRequestInitializer, HttpUnsuccessfulResponseHandler

Thread-safe OAuth 2.0 helper for accessing protected resources using an access token, as well as optionally refreshing the access token when it expires using a refresh token.

Sample usage:

public static Credential createCredentialWithAccessTokenOnly( HttpTransport transport, JsonFactory jsonFactory, TokenResponse tokenResponse) { return new Credential(BearerToken.authorizationHeaderAccessMethod()).setFromTokenResponse( tokenResponse); }

public static Credential createCredentialWithRefreshToken( HttpTransport transport, JsonFactory jsonFactory, TokenResponse tokenResponse) { return new Credential.Builder(BearerToken.authorizationHeaderAccessMethod()).setTransport( transport) .setJsonFactory(jsonFactory) .setTokenServerUrl( new GenericUrl("https://server.example.com/token")) .setClientAuthentication(new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw")) .build() .setFromTokenResponse(tokenResponse); }

If you need to persist the access token in a data store, use DataStoreFactory and Builder#addRefreshListener(CredentialRefreshListener) with DataStoreCredentialRefreshListener.

If you have a custom request initializer, request execute interceptor, or unsuccessful response handler, take a look at the sample usage for HttpExecuteInterceptor and HttpUnsuccessfulResponseHandler, which are interfaces that this class also implements.

Inheritance

java.lang.Object > Credential

Implements

com.google.api.client.http.HttpExecuteInterceptor, com.google.api.client.http.HttpRequestInitializer, com.google.api.client.http.HttpUnsuccessfulResponseHandler

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Constructors

Credential(Credential.AccessMethod method)

public Credential(Credential.AccessMethod method)

Constructor with the ability to access protected resources, but not refresh tokens.

To use with the ability to refresh tokens, use Builder.

Parameter
Name	Description
method	Credential.AccessMethod method of presenting the access token to the resource server (for example BearerToken.AuthorizationHeaderAccessMethod)

Credential(Credential.Builder builder)

protected Credential(Credential.Builder builder)

Parameter
Name	Description
builder	Credential.Builder credential builder

Methods

executeRefreshToken()

protected TokenResponse executeRefreshToken()

Executes a request for new credentials from the token server.

The default implementation calls RefreshTokenRequest#execute() using the #getTransport(), #getJsonFactory(), #getRequestInitializer(), #getTokenServerEncodedUrl(), #getRefreshToken(), and the #getClientAuthentication(). If #getRefreshToken() is null, it instead returns null.

Subclasses may override for a different implementation. Implementations can assume proper thread synchronization is already taken care of inside #refreshToken().

Returns
Type	Description
TokenResponse	successful response from the token server or null if it is not possible to refresh the access token

Exceptions
Type	Description
IOException	if an error response was received from the token server

getAccessToken()

public final String getAccessToken()

Returns the access token or null for none. If null the token needs to be refreshed using refreshToken().

Returns
Type	Description
String

getClientAuthentication()

public final HttpExecuteInterceptor getClientAuthentication()

Returns the client authentication or null for none.

Returns
Type	Description
com.google.api.client.http.HttpExecuteInterceptor

getClock()

public final Clock getClock()

Returns the clock used for expiration checks by this Credential. Mostly used for unit-testing.

Returns
Type	Description
com.google.api.client.util.Clock

getExpirationTimeMilliseconds()

public final Long getExpirationTimeMilliseconds()

Expected expiration time in milliseconds relative to the Java epoch, or null for none.

Returns
Type	Description
Long

getExpiresInSeconds()

public final Long getExpiresInSeconds()

Returns the remaining lifetime in seconds of the access token (for example 3600 for an hour from now, or -3600 if expired an hour ago) or null if unknown.

Returns
Type	Description
Long

getJsonFactory()

public final JsonFactory getJsonFactory()

Returns the JSON factory to use for parsing response for refresh token request or null for none.

Returns
Type	Description
com.google.api.client.json.JsonFactory

getMethod()

public final Credential.AccessMethod getMethod()

Return the method of presenting the access token to the resource server (for example BearerToken.AuthorizationHeaderAccessMethod).

Returns
Type	Description
Credential.AccessMethod

getRefreshListeners()

public final Collection<CredentialRefreshListener> getRefreshListeners()

Returns the unmodifiable collection of listeners for refresh token results.

Returns
Type	Description
Collection<CredentialRefreshListener>

getRefreshToken()

public final String getRefreshToken()

Returns the refresh token associated with the access token to be refreshed or null for none.

Returns
Type	Description
String

getRequestInitializer()

public final HttpRequestInitializer getRequestInitializer()

Returns the HTTP request initializer for refresh token requests to the token server or null for none.

Returns
Type	Description
com.google.api.client.http.HttpRequestInitializer

getTokenServerEncodedUrl()

public final String getTokenServerEncodedUrl()

Returns the encoded authorization server URL or null for none.

Returns
Type	Description
String

getTransport()

public final HttpTransport getTransport()

Return the HTTP transport for executing refresh token request or null for none.

Returns
Type	Description
com.google.api.client.http.HttpTransport

handleResponse(HttpRequest request, HttpResponse response, boolean supportsRetry)

public boolean handleResponse(HttpRequest request, HttpResponse response, boolean supportsRetry)

Default implementation checks if WWW-Authenticate exists and contains a "Bearer" value (see rfc6750 section 3.1 for more details). If so, it calls #refreshToken in case the error code contains invalid_token. If there is no "Bearer" in WWW-Authenticate and the status code is HttpStatusCodes#STATUS_CODE_UNAUTHORIZED it calls #refreshToken. If #executeRefreshToken() throws an I/O exception, this implementation will log the exception and return false. Subclasses may override.

Parameters
Name	Description
request	com.google.api.client.http.HttpRequest
response	com.google.api.client.http.HttpResponse
supportsRetry	boolean

Returns
Type	Description
boolean

initialize(HttpRequest request)

public void initialize(HttpRequest request)

Parameter
Name	Description
request	com.google.api.client.http.HttpRequest

Exceptions
Type	Description
IOException

intercept(HttpRequest request)

public void intercept(HttpRequest request)

Default implementation is to try to refresh the access token if there is no access token or if we are 1 minute away from expiration. If token server is unavailable, it will try to use the access token even if has expired. If a 4xx error is encountered while refreshing the token, TokenResponseException is thrown. If successful, it will call #getMethod() and AccessMethod#intercept.

Subclasses may override.

Parameter
Name	Description
request	com.google.api.client.http.HttpRequest

Exceptions
Type	Description
IOException

refreshToken()

public final boolean refreshToken()

Request a new access token from the authorization endpoint.

On success, it will call #setFromTokenResponse(TokenResponse), call CredentialRefreshListener#onTokenResponse with the token response, and return true. On error, it will call #setAccessToken(String) and #setExpiresInSeconds(Long) with null, call CredentialRefreshListener#onTokenErrorResponse with the token error response, and return false. If a 4xx error is encountered while refreshing the token, TokenResponseException is thrown.

If there is no refresh token, it will quietly return false.

Returns
Type	Description
boolean	whether a new access token was successfully retrieved

Exceptions
Type	Description
IOException

setAccessToken(String accessToken)

public Credential setAccessToken(String accessToken)

Sets the access token.

Overriding is only supported for the purpose of calling the super implementation and changing the return type, but nothing else.

Parameter
Name	Description
accessToken	String access token or null for none

Returns
Type	Description
Credential

setExpirationTimeMilliseconds(Long expirationTimeMilliseconds)

public Credential setExpirationTimeMilliseconds(Long expirationTimeMilliseconds)

Sets the expected expiration time in milliseconds relative to the Java epoch, or null for none.

Overriding is only supported for the purpose of calling the super implementation and changing the return type, but nothing else.

Parameter
Name	Description
expirationTimeMilliseconds	Long

Returns
Type	Description
Credential

setExpiresInSeconds(Long expiresIn)

public Credential setExpiresInSeconds(Long expiresIn)

Sets the lifetime in seconds of the access token (for example 3600 for an hour from now) or null for none.

Overriding is only supported for the purpose of calling the super implementation and changing the return type, but nothing else.

Parameter
Name	Description
expiresIn	Long lifetime in seconds of the access token (for example 3600 for an hour from now) or null for none

Returns
Type	Description
Credential

setFromTokenResponse(TokenResponse tokenResponse)

public Credential setFromTokenResponse(TokenResponse tokenResponse)

Sets the access token, refresh token (if available), and expires-in time based on the values from the token response.

It does not call the refresh listeners.

Overriding is only supported for the purpose of calling the super implementation and changing the return type, but nothing else.

Parameter
Name	Description
tokenResponse	TokenResponse successful token response

Returns
Type	Description
Credential

setRefreshToken(String refreshToken)

public Credential setRefreshToken(String refreshToken)

Sets the refresh token.

Overriding is only supported for the purpose of calling the super implementation and changing the return type, but nothing else.

Parameter
Name	Description
refreshToken	String refresh token or null for none

Returns
Type	Description
Credential