Credential (google-oauth-java-client 1.31.0)

java.lang.Object
- com.google.api.client.auth.oauth2.Credential

All Implemented Interfaces:: HttpExecuteInterceptor, HttpRequestInitializer, HttpUnsuccessfulResponseHandler

public class Credential
extends Object
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 Credential.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.

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.Builder builder)`

Method Summary

All Methods Instance Methods Concrete 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.
`HttpExecuteInterceptor`	`getClientAuthentication()` Returns the client authentication or `null` for none.
`Clock`	`getClock()` Returns the clock used for expiration checks by this Credential.
`Long`	`getExpirationTimeMilliseconds()` Expected expiration time in milliseconds relative to the `Java epoch`, or `null` for none.
`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.
`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`).
`Collection<CredentialRefreshListener>`	`getRefreshListeners()` Returns the unmodifiable collection of listeners for refresh token results.
`String`	`getRefreshToken()` Returns the refresh token associated with the access token to be refreshed or `null` for none.
`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.
`HttpTransport`	`getTransport()` Return the HTTP transport for executing refresh token request or `null` for none.
`boolean`	`handleResponse(HttpRequest request, HttpResponse response, boolean supportsRetry)`
`void`	`initialize(HttpRequest request)`
`void`	`intercept(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 relative to the `Java epoch`, or `null` for none.
`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.
`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.Builder builder)
```
    Parameters:
    
    builder - credential builder
    
    Since:
    
    1.14
- Method Detail
  - intercept
```
public void intercept(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 HttpExecuteInterceptor
    
    Throws:
    
    IOException
  - handleResponse
```
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.
    
    Specified by:
    
    handleResponse in interface HttpUnsuccessfulResponseHandler
  - initialize
```
public void initialize(HttpRequest request)
                throws IOException
```
    Specified by:
    
    initialize in interface HttpRequestInitializer
    
    Throws:
    
    IOException
  - getAccessToken
```
public final String getAccessToken()
```
    Returns the access token or null for none. If null the token needs to be refreshed using refreshToken().
  - 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 Clock getClock()
```
    Returns the clock used for expiration checks by this Credential. Mostly used for unit-testing.
    
    Since:
    
    1.9
  - getTransport
```
public final HttpTransport getTransport()
```
    Return the HTTP transport for executing refresh token request or null for none.
  - getJsonFactory
```
public final 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 relative to the Java epoch, or null for none.
  - setExpirationTimeMilliseconds
```
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.
  - 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.
  - setExpiresInSeconds
```
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.
    
    Parameters:
    
    expiresIn - lifetime in seconds of the access token (for example 3600 for an hour from now) or null for none
  - getClientAuthentication
```
public final HttpExecuteInterceptor getClientAuthentication()
```
    Returns the client authentication or null for none.
  - getRequestInitializer
```
public final 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.
    
    If there is no refresh token, it will quietly return false.
    
    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 Collection<CredentialRefreshListener> getRefreshListeners()
```
    Returns the unmodifiable collection of listeners for refresh token results.

Class Credential

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Credential

Credential

Method Detail

intercept

handleResponse

initialize

getAccessToken

setAccessToken

getMethod

getClock

getTransport

getJsonFactory

getTokenServerEncodedUrl

getRefreshToken

setRefreshToken

getExpirationTimeMilliseconds

setExpirationTimeMilliseconds

getExpiresInSeconds

setExpiresInSeconds

getClientAuthentication

getRequestInitializer

refreshToken

setFromTokenResponse

executeRefreshToken

getRefreshListeners