Package com.google.api.client.auth.oauth2 (1.36.0)

Implementation of the OAuth 2.0 Authorization Framework.

Before using this library, you will typically need to register your application with the authorization server to receive a client ID and client secret. See Client Registration.

These are the typical steps of the web server flow based on an authorization code, as specified in Authorization Code Grant:

These are the typical steps of the the browser-based client flow specified in Implicit Grant:

  • Redirect the end user in the browser to the authorization page using com.google.api.client.auth.oauth2.BrowserClientRequestUrl to grant your browser application access to the end user's protected data.
  • Use a JavaScript application to process the access token found in the URL fragment at the redirect URI registered with the authorization server.

Classes

AuthorizationCodeFlow

Thread-safe OAuth 2.0 authorization code flow that manages and persists end-user credentials.

This is designed to simplify the flow in which an end-user authorizes the application to access their protected data, and then the application has access to their data based on an access token and a refresh token to refresh that access token when it expires.

The first step is to call #loadCredential(String) based on the known user ID to check if the end-user's credentials are already known. If not, call #newAuthorizationUrl() and direct the end-user's browser to an authorization page. The web browser will then redirect to the redirect URL with a "code" query parameter which can then be used to request an access token using #newTokenRequest(String). Finally, use #createAndStoreCredential(TokenResponse, String) to store and obtain a credential for accessing protected resources.

AuthorizationCodeFlow.Builder

Authorization code flow builder.

Implementation is not thread-safe.

AuthorizationCodeRequestUrl

OAuth 2.0 URL builder for an authorization web page to allow the end user to authorize the application to access their protected resources and that returns an authorization code, as specified in Authorization Code Grant.

The default for #getResponseTypes() is "code". Use AuthorizationCodeResponseUrl to parse the redirect response after the end user grants/denies the request. Using the authorization code in this response, use AuthorizationCodeTokenRequest to request the access token.

Sample usage for a web application:

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { String url = new AuthorizationCodeRequestUrl("https://server.example.com/authorize", "s6BhdRkqt3") .setState("xyz").setRedirectUri("https://client.example.com/rd").build(); response.sendRedirect(url); }

Implementation is not thread-safe.

AuthorizationCodeResponseUrl

OAuth 2.0 URL parser for the redirect URL after end user grants or denies authorization as specified in Authorization Response.

Check if #getError() is null to check if the end-user granted authorization.

Sample usage:

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { StringBuffer fullUrlBuf = request.getRequestURL(); if (request.getQueryString() != null) { fullUrlBuf.append('?').append(request.getQueryString()); } AuthorizationCodeResponseUrl authResponse = new AuthorizationCodeResponseUrl(fullUrlBuf.toString()); // check for user-denied error if (authResponse.getError() != null) { // authorization denied... } else { // request access token using authResponse.getCode()... } }

Implementation is not thread-safe.

AuthorizationCodeTokenRequest

OAuth 2.0 request for an access token using an authorization code as specified in Access Token Request.

Use Credential to access protected resources from the resource server using the TokenResponse returned by #execute(). On error, it will instead throw TokenResponseException.

Sample usage:

static void requestAccessToken() throws IOException { try { TokenResponse response = new AuthorizationCodeTokenRequest(new NetHttpTransport(), new GsonFactory(), new GenericUrl("https://server.example.com/token"), "SplxlOBeZQQYbYS6WxSbIA") .setRedirectUri("https://client.example.com/rd") .setClientAuthentication( new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw")).execute(); System.out.println("Access token: " + response.getAccessToken()); } catch (TokenResponseException e) { if (e.getDetails() != null) { System.err.println("Error: " + e.getDetails().getError()); if (e.getDetails().getErrorDescription() != null) { System.err.println(e.getDetails().getErrorDescription()); } if (e.getDetails().getErrorUri() != null) { System.err.println(e.getDetails().getErrorUri()); } } else { System.err.println(e.getMessage()); } } }

Some OAuth 2.0 providers don't support BasicAuthentication but instead support ClientParametersAuthentication. In the above sample code, simply replace the class name and it will work the same way.

Implementation is not thread-safe.

AuthorizationRequestUrl

OAuth 2.0 URL builder for an authorization web page to allow the end user to authorize the application to access their protected resources, as specified in Authorization Endpoint.

Sample usage for a web application:

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { String url = new AuthorizationRequestUrl( "https://server.example.com/authorize", "s6BhdRkqt3", Arrays.asList("code")).setState("xyz") .setRedirectUri("https://client.example.com/rd").build(); response.sendRedirect(url); }

Implementation is not thread-safe.

BearerToken

OAuth 2.0 helper for accessing protected resources using the Bearer Token specification.

BrowserClientRequestUrl

OAuth 2.0 URL builder for an authorization web page to allow the end user to authorize the application to access their protected resources and that returns the access token to a browser client using a scripting language such as JavaScript, as specified in Implicit Grant.

The default for #getResponseTypes() is "token".

Sample usage for a web application:

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException { String url = new BrowserClientRequestUrl( "https://server.example.com/authorize", "s6BhdRkqt3").setState("xyz") .setRedirectUri("https://client.example.com/cb").build(); response.sendRedirect(url); }

Implementation is not thread-safe.

ClientCredentialsTokenRequest

OAuth 2.0 request for an access token using only its client credentials as specified in Client Credentials Grant.

Use Credential to access protected resources from the resource server using the TokenResponse returned by #execute(). On error, it will instead throw TokenResponseException.

Sample usage:

static void requestAccessToken() throws IOException { try { TokenResponse response = new ClientCredentialsTokenRequest(new NetHttpTransport(), new GsonFactory(), new GenericUrl("https://server.example.com/token")) .setRedirectUri("https://client.example.com/rd") .setClientAuthentication( new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw")).execute(); System.out.println("Access token: " + response.getAccessToken()); } catch (TokenResponseException e) { if (e.getDetails() != null) { System.err.println("Error: " + e.getDetails().getError()); if (e.getDetails().getErrorDescription() != null) { System.err.println(e.getDetails().getErrorDescription()); } if (e.getDetails().getErrorUri() != null) { System.err.println(e.getDetails().getErrorUri()); } } else { System.err.println(e.getMessage()); } } }

Some OAuth 2.0 providers don't support BasicAuthentication but instead support ClientParametersAuthentication. In the above sample code, simply replace the class name and it will work the same way.

Implementation is not thread-safe.

ClientParametersAuthentication

Client credentials specified as URL-encoded parameters in the HTTP request body as specified in Client Password

This implementation assumes that the HttpRequest#getContent() is null or an instance of UrlEncodedContent. This is used as the client authentication in TokenRequest#setClientAuthentication(HttpExecuteInterceptor).

Sample usage:

static void requestAccessToken() throws IOException { try { TokenResponse response = new AuthorizationCodeTokenRequest(new NetHttpTransport(), new GsonFactory(), new GenericUrl("https://server.example.com/token"), "SplxlOBeZQQYbYS6WxSbIA").setRedirectUri("https://client.example.com/rd") .setClientAuthentication( new ClientParametersAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw")).execute(); System.out.println("Access token: " + response.getAccessToken()); } catch (TokenResponseException e) { if (e.getDetails() != null) { System.err.println("Error: " + e.getDetails().getError()); if (e.getDetails().getErrorDescription() != null) { System.err.println(e.getDetails().getErrorDescription()); } if (e.getDetails().getErrorUri() != null) { System.err.println(e.getDetails().getErrorUri()); } } else { System.err.println(e.getMessage()); } } }

Implementation is immutable and thread-safe.

Credential

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.

Credential.Builder

Credential builder.

Implementation is not thread-safe.

CredentialStoreRefreshListener (deprecated)

Deprecated. (to be removed in the future) Use DataStoreCredentialRefreshListener instead.

Beta
Thread-safe OAuth 2.0 credential refresh listener that stores the refresh token response in the credential store.

It needs to be added as a refresh listener using Credential.Builder#addRefreshListener.

DataStoreCredentialRefreshListener

Beta
Thread-safe OAuth 2.0 credential refresh listener that stores the refresh token response in the credential data store.

It needs to be added as a refresh listener using Credential.Builder#addRefreshListener. Sample usage:

static void addDataStoreCredentialRefreshListener( Credential.Builder credentialBuilder, String userId, DataStoreFactory dataStoreFactory) throws IOException { credentialBuilder.addRefreshListener( new DataStoreCredentialRefreshListener(userId, dataStoreFactory)); }

PasswordTokenRequest

OAuth 2.0 request for an access token using the user's username and password as specified in Resource Owner Password Credentials Grant.

Use Credential to access protected resources from the resource server using the TokenResponse returned by #execute(). On error, it will instead throw TokenResponseException.

Sample usage:

static void requestAccessToken() throws IOException { try { TokenResponse response = new PasswordTokenRequest(new NetHttpTransport(), new GsonFactory(), new GenericUrl("https://server.example.com/token"), "johndoe", "A3ddj3w") .setRedirectUri("https://client.example.com/rd") .setClientAuthentication( new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw")).execute(); System.out.println("Access token: " + response.getAccessToken()); } catch (TokenResponseException e) { if (e.getDetails() != null) { System.err.println("Error: " + e.getDetails().getError()); if (e.getDetails().getErrorDescription() != null) { System.err.println(e.getDetails().getErrorDescription()); } if (e.getDetails().getErrorUri() != null) { System.err.println(e.getDetails().getErrorUri()); } } else { System.err.println(e.getMessage()); } } }

Some OAuth 2.0 providers don't support BasicAuthentication but instead support ClientParametersAuthentication. In the above sample code, simply replace the class name and it will work the same way.

Implementation is not thread-safe.

RefreshTokenRequest

OAuth 2.0 request to refresh an access token using a refresh token as specified in Refreshing an Access Token.

Use Credential to access protected resources from the resource server using the TokenResponse returned by #execute(). On error, it will instead throw TokenResponseException.

Sample usage:

static void refreshAccessToken() throws IOException { try { TokenResponse response = new RefreshTokenRequest(new NetHttpTransport(), new GsonFactory(), new GenericUrl( "https://server.example.com/token"), "tGzv3JOkF0XG5Qx2TlKWIA") .setClientAuthentication( new BasicAuthentication("s6BhdRkqt3", "7Fjfp0ZBr1KtDRbnfVdmIw")).execute(); System.out.println("Access token: " + response.getAccessToken()); } catch (TokenResponseException e) { if (e.getDetails() != null) { System.err.println("Error: " + e.getDetails().getError()); if (e.getDetails().getErrorDescription() != null) { System.err.println(e.getDetails().getErrorDescription()); } if (e.getDetails().getErrorUri() != null) { System.err.println(e.getDetails().getErrorUri()); } } else { System.err.println(e.getMessage()); } } }

Some OAuth 2.0 providers don't support BasicAuthentication but instead support ClientParametersAuthentication. In the above sample code, simply replace the class name and it will work the same way.

Implementation is not thread-safe.

StoredCredential

Beta
Credential information to be stored in a DataStoreFactory.

Implementation is thread safe.

TokenErrorResponse

OAuth 2.0 parser for an error access token response as specified in Error Response.

Implementation is not thread-safe.

TokenRequest

OAuth 2.0 request for an access token as specified in Obtaining Authorization.

Call #execute() to execute the request and use the returned TokenResponse. On error, it will instead throw TokenResponseException.

Implementation is not thread-safe.

TokenResponse

OAuth 2.0 JSON model for a successful access token response as specified in Successful Response.

Implementation is not thread-safe.

Interfaces

AuthorizationCodeFlow.CredentialCreatedListener

Listener for a created credential after a successful token response in #createAndStoreCredential.

Credential.AccessMethod

Method of presenting the access token to the resource server as specified in Accessing Protected Resources.

CredentialRefreshListener

Listener for refresh token results.

These methods are called from Credential#refreshToken() after a response has been received from refreshing the token. #onTokenResponse is called on a successful HTTP response, and #onTokenErrorResponse is called on an error HTTP response.

CredentialStore (deprecated)

Deprecated. (to be removed in the future) Use DataStoreFactory with StoredCredential instead.

Beta
OAuth 2.0 credential persistence store interface to provide a fully pluggable storage mechanism.

The user ID should be used as the primary key for storage, and the rest of the data consists of the access token, refresh token, and expiration time.

Implementations should be thread safe.

Exceptions

TokenResponseException

Exception thrown when receiving an error response from the token server as specified in Error Response

To get the structured details, use #getDetails().

Sample usage can be found for AuthorizationCodeTokenRequest.