com.google.api.client.auth.oauth2

Class Credential

java.lang.Object

com.google.api.client.auth.oauth2.Credential

All Implemented Interfaces:

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

public class Credential
extends Object
implements com.google.api.client.http.HttpExecuteInterceptor, com.google.api.client.http.HttpRequestInitializer, com.google.api.client.http.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 CredentialStore and Credential.Builder.addRefreshListener(CredentialRefreshListener).

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.

Since:

1.7

Author:

Yaniv Inbar

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Credential.AccessMethod Method of presenting the access token to the resource server as specified in Accessing Protected Resources.
static class	Credential.Builder Credential builder.

Constructor Summary

Constructors

Modifier	Constructor and Description
	Credential(Credential.AccessMethod method) Constructor with the ability to access protected resources, but not refresh tokens.
protected	Credential(Credential.AccessMethod method, com.google.api.client.http.HttpTransport transport, com.google.api.client.json.JsonFactory jsonFactory, String tokenServerEncodedUrl, com.google.api.client.http.HttpExecuteInterceptor clientAuthentication, com.google.api.client.http.HttpRequestInitializer requestInitializer, List<CredentialRefreshListener> refreshListeners)
protected	Credential(Credential.AccessMethod method, com.google.api.client.http.HttpTransport transport, com.google.api.client.json.JsonFactory jsonFactory, String tokenServerEncodedUrl, com.google.api.client.http.HttpExecuteInterceptor clientAuthentication, com.google.api.client.http.HttpRequestInitializer requestInitializer, List<CredentialRefreshListener> refreshListeners, com.google.api.client.util.Clock clock)

Method Summary

Methods

Modifier and Type	Method and Description
protected TokenResponse	executeRefreshToken() Executes a request for new credentials from the token server.
String	getAccessToken() Returns the access token or null for none.
com.google.api.client.http.HttpExecuteInterceptor	getClientAuthentication() Returns the client authentication or null for none.
com.google.api.client.util.Clock	getClock() Returns the clock used for expiration checks by this Credential.
Long	getExpirationTimeMilliseconds() Expected expiration time in milliseconds or null for none.
Long	getExpiresInSeconds() Returns the remaining lifetime in seconds of the access token (for example 3600 for an hour, or -3600 if expired an hour ago) or null if unknown.
com.google.api.client.json.JsonFactory	getJsonFactory() Returns the JSON factory to use for parsing response for refresh token request or null for none.
Credential.AccessMethod	getMethod() Return the method of presenting the access token to the resource server (for example BearerToken.AuthorizationHeaderAccessMethod).
List<CredentialRefreshListener>	getRefreshListeners() Returns the unmodifiable list of listeners for refresh token results.
String	getRefreshToken() Returns the refresh token associated with the access token to be refreshed or null for none.
com.google.api.client.http.HttpRequestInitializer	getRequestInitializer() Returns the HTTP request initializer for refresh token requests to the token server or null for none.
String	getTokenServerEncodedUrl() Returns the encoded authorization server URL or null for none.
com.google.api.client.http.HttpTransport	getTransport() Return the HTTP transport for executing refresh token request or null for none.
boolean	handleResponse(com.google.api.client.http.HttpRequest request, com.google.api.client.http.HttpResponse response, boolean supportsRetry)
void	initialize(com.google.api.client.http.HttpRequest request)
void	intercept(com.google.api.client.http.HttpRequest request)
boolean	refreshToken() Request a new access token from the authorization endpoint.
Credential	setAccessToken(String accessToken) Sets the access token.
Credential	setExpirationTimeMilliseconds(Long expirationTimeMilliseconds) Sets the expected expiration time in milliseconds or null for none.
Credential	setExpiresInSeconds(Long expiresIn) Sets the lifetime in seconds of the access token (for example 3600 for an hour) or null for none.
Credential	setFromTokenResponse(TokenResponse tokenResponse) Sets the access token, refresh token (if available), and expires-in time based on the values from the token response.
Credential	setRefreshToken(String refreshToken) Sets the refresh token.

Methods inherited from class java.lang.Object

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

Constructor Detail

Credential

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 Credential.Builder.

Parameters:

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

Credential

protected Credential(Credential.AccessMethod method,
          com.google.api.client.http.HttpTransport transport,
          com.google.api.client.json.JsonFactory jsonFactory,
          String tokenServerEncodedUrl,
          com.google.api.client.http.HttpExecuteInterceptor clientAuthentication,
          com.google.api.client.http.HttpRequestInitializer requestInitializer,
          List<CredentialRefreshListener> refreshListeners)

Parameters:

method - method of presenting the access token to the resource server (for example BearerToken.authorizationHeaderAccessMethod())

transport - HTTP transport for executing refresh token request or null if not refreshing tokens

jsonFactory - JSON factory to use for parsing response for refresh token request or null if not refreshing tokens

tokenServerEncodedUrl - encoded token server URL or null if not refreshing tokens

clientAuthentication - client authentication or null for none (see TokenRequest.setClientAuthentication(HttpExecuteInterceptor))

requestInitializer - HTTP request initializer for refresh token requests to the token server or null for none

refreshListeners - listeners for refresh token results or null for none

Credential

protected Credential(Credential.AccessMethod method,
          com.google.api.client.http.HttpTransport transport,
          com.google.api.client.json.JsonFactory jsonFactory,
          String tokenServerEncodedUrl,
          com.google.api.client.http.HttpExecuteInterceptor clientAuthentication,
          com.google.api.client.http.HttpRequestInitializer requestInitializer,
          List<CredentialRefreshListener> refreshListeners,
          com.google.api.client.util.Clock clock)

Parameters:

method - method of presenting the access token to the resource server (for example BearerToken.authorizationHeaderAccessMethod())

transport - HTTP transport for executing refresh token request or null if not refreshing tokens

jsonFactory - JSON factory to use for parsing response for refresh token request or null if not refreshing tokens

tokenServerEncodedUrl - encoded token server URL or null if not refreshing tokens

clientAuthentication - client authentication or null for none (see TokenRequest.setClientAuthentication(HttpExecuteInterceptor))

requestInitializer - HTTP request initializer for refresh token requests to the token server or null for none

refreshListeners - listeners for refresh token results or null for none

clock - Clock used for retrieving the current time for expiration checks

Since:

1.9

Method Detail

intercept

public void intercept(com.google.api.client.http.HttpRequest request)
               throws IOException

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 Credential.AccessMethod.intercept(com.google.api.client.http.HttpRequest, java.lang.String).

Subclasses may override.

Specified by:

intercept in interface com.google.api.client.http.HttpExecuteInterceptor

Throws:

IOException

handleResponse

public boolean handleResponse(com.google.api.client.http.HttpRequest request,
                     com.google.api.client.http.HttpResponse response,
                     boolean supportsRetry)

Default implementation checks for a 401 error code and calls refreshToken(). If executeRefreshToken() throws an I/O exception, this implementation will log the exception and return false. Subclasses may override.

Specified by:

handleResponse in interface com.google.api.client.http.HttpUnsuccessfulResponseHandler

initialize

public void initialize(com.google.api.client.http.HttpRequest request)
                throws IOException

Specified by:

initialize in interface com.google.api.client.http.HttpRequestInitializer

Throws:

IOException

getAccessToken

public final String getAccessToken()

Returns the access token or null for none.

setAccessToken

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.

Parameters:

accessToken - access token or null for none

getMethod

public final Credential.AccessMethod getMethod()

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

getClock

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

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

Since:

1.9

getTransport

public final com.google.api.client.http.HttpTransport getTransport()

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

getJsonFactory

public final com.google.api.client.json.JsonFactory getJsonFactory()

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

getTokenServerEncodedUrl

public final String getTokenServerEncodedUrl()

Returns the encoded authorization server URL or null for none.

getRefreshToken

public final String getRefreshToken()

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

setRefreshToken

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.

Parameters:

refreshToken - refresh token or null for none

getExpirationTimeMilliseconds

public final Long getExpirationTimeMilliseconds()

Expected expiration time in milliseconds or null for none.

setExpirationTimeMilliseconds

public Credential setExpirationTimeMilliseconds(Long expirationTimeMilliseconds)

Sets the expected expiration time in milliseconds or null for none.

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

getExpiresInSeconds

public final Long getExpiresInSeconds()

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

setExpiresInSeconds

public Credential setExpiresInSeconds(Long expiresIn)

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

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

Parameters:

expiresIn - lifetime in seconds of the access token (for example 3600 for an hour) or null for none

getClientAuthentication

public final com.google.api.client.http.HttpExecuteInterceptor getClientAuthentication()

Returns the client authentication or null for none.

getRequestInitializer

public final com.google.api.client.http.HttpRequestInitializer getRequestInitializer()

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

refreshToken

public final boolean refreshToken()
                           throws IOException

Request a new access token from the authorization endpoint.

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

Returns:

whether a new access token was successfully retrieved

Throws:

IOException

setFromTokenResponse

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.

Parameters:

tokenResponse - successful token response

executeRefreshToken

protected TokenResponse executeRefreshToken()
                                     throws IOException

Executes a request for new credentials from the token server.

The default implementation calls TokenRequest.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:

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

Throws:

TokenResponseException - if an error response was received from the token server

IOException

getRefreshListeners

public final List<CredentialRefreshListener> getRefreshListeners()

Returns the unmodifiable list of listeners for refresh token results.