com.dropbox.core

Class DbxWebAuth

java.lang.Object

com.dropbox.core.DbxWebAuth

public class DbxWebAuth
extends java.lang.Object

Does the OAuth 2 "authorization code" flow. (This SDK does not support the "token" flow.)

Eventually yields an access token, which can be used with DbxClientV2 to make Dropbox API calls. You typically only need to do this for a user when they first use your application. Once you have an access token for that user, it remains valid for years.

Redirect example

One-time setup typically done on server initialization:

     DbxRequestConfig requestConfig = new DbxRequestConfig("text-edit/0.1");
     DbxAppInfo appInfo = DbxAppInfo.Reader.readFromFile("api.app");
     DbxWebAuth auth = new DbxWebAuth(requestConfig, appInfo);

     String redirectUri = "http://my-server.com/dropbox-auth-finish";
 

Part 1

Handler for "http://my-server.com/dropbox-auth-start":

     HttpServletRequest request = ...
     HttpServletResponse response = ...

     // Select a spot in the session for DbxWebAuth to store the CSRF token.
     HttpSession session = request.getSession(true);
     String sessionKey = "dropbox-auth-csrf-token";
     DbxSessionStore csrfTokenStore = new DbxStandardSessionStore(session, sessionKey);

     // Build an auth request
     DbxWebAuth.Request authRequest = DbxWebAuth.newRequestBuilder()
         .withRedirectUri(redirectUri, csrfTokenStore)
         .build();

     // Start authorization.
     String authorizePageUrl = auth.authorize(authRequest);

     // Redirect the user to the Dropbox website so they can approve our application.
     // The Dropbox website will send them back to "http://my-server.com/dropbox-auth-finish"
     // when they're done.
     response.sendRedirect(authorizePageUrl);
 

Part 2

Handler for "http://my-server.com/dropbox-auth-finish":

     HttpServletRequest request = ...
     HttpServletResponse response = ...

     // Fetch the session to verify our CSRF token
     HttpSession session = request.getSession(true);
     String sessionKey = "dropbox-auth-csrf-token";
     DbxSessionStore csrfTokenStore = new DbxStandardSessionStore(session, sessionKey);
     String redirectUri = "http://my-server.com/dropbox-auth-finish";

     DbxAuthFinish authFinish;
     try {
         authFinish = auth.finishFromRedirect(redirectUri, csrfTokenStore, request.getParameterMap());
     } catch (DbxWebAuth.BadRequestException ex) {
         log("On /dropbox-auth-finish: Bad request: " + ex.getMessage());
         response.sendError(400);
         return;
     } catch (DbxWebAuth.BadStateException ex) {
         // Send them back to the start of the auth flow.
         response.sendRedirect("http://my-server.com/dropbox-auth-start");
         return;
     } catch (DbxWebAuth.CsrfException ex) {
         log("On /dropbox-auth-finish: CSRF mismatch: " + ex.getMessage());
         response.sendError(403, "Forbidden.");
         return;
     } catch (DbxWebAuth.NotApprovedException ex) {
         // When Dropbox asked "Do you want to allow this app to access your
         // Dropbox account?", the user clicked "No".
         ...
         return;
     } catch (DbxWebAuth.ProviderException ex) {
         log("On /dropbox-auth-finish: Auth failed: " + ex.getMessage());
         response.sendError(503, "Error communicating with Dropbox.");
         return;
     } catch (DbxException ex) {
         log("On /dropbox-auth-finish: Error getting token: " + ex.getMessage());
         response.sendError(503, "Error communicating with Dropbox.");
         return;
     }
     String accessToken = authFinish.getAccessToken();

     // Save the access token somewhere (probably in your database) so you
     // don't need to send the user through the authorization process again.
     ...

     // Now use the access token to make Dropbox API calls.
     DbxClientV2 client = new DbxClientV2(requestConfig, accessToken);
     ...
 

No Redirect Example

     DbxRequestConfig requestConfig = new DbxRequestConfig("text-edit/0.1");
     DbxAppInfo appInfo = DbxAppInfo.Reader.readFromFile("api.app");
     DbxWebAuth auth = new DbxWebAuth(requestConfig, appInfo);

     DbxWebAuth.Request authRequest = DbxWebAuth.newRequestBuilder()
         .withNoRedirect()
         .build();
     String authorizeUrl = auth.authorize(authRequest);
     System.out.println("1. Go to " + authorizeUrl);
     System.out.println("2. Click \"Allow\" (you might have to log in first).");
     System.out.println("3. Copy the authorization code.");
     System.out.print("Enter the authorization code here: ");

     String code = System.console().readLine();
     if (code != null) {
         code = code.trim();
         DbxAuthFinish authFinish = webAuth.finishFromCode(code);
         DbxClientV2 client = new DbxClientV2(requestConfig, authFinish.getAccessToken());
     }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DbxWebAuth.BadRequestException Thrown when the parameters passed to your redirect URI are not well-formed.
static class	DbxWebAuth.BadStateException Thrown if all the parameters to your redirect URI are well-formed, but there's no CSRF token in the session.
static class	DbxWebAuth.CsrfException Thrown if the given 'state' parameter doesn't contain the expected CSRF token.
static class	DbxWebAuth.Exception The base class for authorization redirect errors.
static class	DbxWebAuth.NotApprovedException Thrown when Dropbox tells us that the user chose not to grant your app access to their Dropbox account (i.e.
static class	DbxWebAuth.ProviderException Thrown when Dropbox tells us that some other error occurred in the authorization process.
static class	DbxWebAuth.Request OAuth web-based authorization flow request.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ROLE_PERSONAL Role representing the personal account associated with a user.
static java.lang.String	ROLE_WORK Role representing the team account associated with a user.

Constructor Summary

Constructors

Constructor and Description
DbxWebAuth(DbxRequestConfig requestConfig, DbxAppInfo appInfo) Creates a new instance that will perform the OAuth2 authorization flow using the given OAuth request configuration.
DbxWebAuth(DbxRequestConfig requestConfig, DbxAppInfo appInfo, java.lang.String redirectUri, DbxSessionStore sessionStore) Deprecated. use DbxWebAuth(DbxRequestConfig,DbxAppInfo) and authorize(com.dropbox.core.DbxWebAuth.Request) instead

Method Summary

Modifier and Type	Method and Description
java.lang.String	authorize(DbxWebAuth.Request request) Starts authorization and returns an "authorization URL" on the Dropbox website that let the user grant your app access to their Dropbox account.
DbxAuthFinish	finish(java.util.Map<java.lang.String,java.lang.String[]> queryParams) Deprecated. use finishFromRedirect(..) instead.
DbxAuthFinish	finishFromCode(java.lang.String code) Call this after the user has visited the authorizaton URL and copy/pasted the authorization code that Dropbox gave them.
DbxAuthFinish	finishFromCode(java.lang.String code, java.lang.String redirectUri) Call this after the user has visited the authorizaton URL with a redirectUrl and copy/pasted the authorization code that Dropbox gave them.
DbxAuthFinish	finishFromRedirect(java.lang.String redirectUri, DbxSessionStore sessionStore, java.util.Map<java.lang.String,java.lang.String[]> params) Call this after the user has visited the authorizaton URL and Dropbox has redirected them back to you at the redirect URI.
static DbxWebAuth.Request.Builder	newRequestBuilder() Returns a new request builder with default values (e.g.
java.lang.String	start(java.lang.String urlState) Deprecated. use DbxWebAuth(DbxRequestConfig,DbxAppInfo) and authorize(com.dropbox.core.DbxWebAuth.Request) instead.

Methods inherited from class java.lang.Object

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

Field Detail

ROLE_WORK

public static final java.lang.String ROLE_WORK

Role representing the team account associated with a user. Used by DbxWebAuth.Request.Builder.withRequireRole(java.lang.String).

See Also:

Constant Field Values

ROLE_PERSONAL

public static final java.lang.String ROLE_PERSONAL

Role representing the personal account associated with a user. Used by DbxWebAuth.Request.Builder.withRequireRole(java.lang.String).

See Also:

Constant Field Values

Constructor Detail

DbxWebAuth

@Deprecated
public DbxWebAuth(DbxRequestConfig requestConfig,
                              DbxAppInfo appInfo,
                              java.lang.String redirectUri,
                              DbxSessionStore sessionStore)

Deprecated. use DbxWebAuth(DbxRequestConfig,DbxAppInfo) and authorize(com.dropbox.core.DbxWebAuth.Request) instead

Creates a new instance that will perform the OAuth2 authorization flow using a redirect URI.

Parameters:

requestConfig - HTTP request configuration, never null.

appInfo - Your application's Dropbox API information (the app key and secret), never nulL.

redirectUri - Where to redirect the user after authorization has completed, never null.

sessionStore - Session store to use for storing CSRF nonces across requests, never null.

DbxWebAuth

public DbxWebAuth(DbxRequestConfig requestConfig,
                  DbxAppInfo appInfo)

Creates a new instance that will perform the OAuth2 authorization flow using the given OAuth request configuration.

Parameters:

requestConfig - HTTP request configuration, never null.

appInfo - Your application's Dropbox API information (the app key and secret), never null.

Method Detail

start

@Deprecated
public java.lang.String start(java.lang.String urlState)

Deprecated. use DbxWebAuth(DbxRequestConfig,DbxAppInfo) and authorize(com.dropbox.core.DbxWebAuth.Request) instead.

Starts authorization and returns a "authorization URL" on the Dropbox website that gives the lets the user grant your app access to their Dropbox account.

If a redirect URI was specified, then users will be redirected to the redirect URI after completing the authorization flow. Call finishFromRedirect(..) with the query parameters received from the redirect.

If no redirect URI was specified, then users who grant access will be shown an "authorization code". The user must copy/paste the authorization code back into your app, at which point you can call finishFromCode(String) to get an access token.

Parameters:

urlState - additional state to add to the flow that will be returned upon redirect

Returns:

Authorization URL of website user can use to authorize your app.

Throws:

java.lang.IllegalArgumentException - if urlState exceeds maximum size of 476 bytes

java.lang.IllegalStateException - if this instance was not created using the deprecated DbxWebAuth(DbxRequestConfig,DbxAppInfo,String,DbxSessionStore) constructor

authorize

public java.lang.String authorize(DbxWebAuth.Request request)

Starts authorization and returns an "authorization URL" on the Dropbox website that let the user grant your app access to their Dropbox account.

If a redirect URI was specified (DbxWebAuth.Request.Builder.withRedirectUri(java.lang.String, com.dropbox.core.DbxSessionStore)), then users will be redirected to the redirect URI after completing the authorization flow. Call finishFromRedirect(java.lang.String, com.dropbox.core.DbxSessionStore, java.util.Map<java.lang.String, java.lang.String[]>) with the query parameters received from the redirect.

If no redirect URI was specified (DbxWebAuth.Request.Builder.withNoRedirect()), then users who grant access will be shown an "authorization code". The user must copy/paste the authorization code back into your app, at which point you can call finishFromCode(String) to get an access token.

Parameters:

request - OAuth 2.0 web-based authorization flow request configuration

Returns:

Authorization URL of website user can use to authorize your app.

Throws:

java.lang.IllegalStateException - if this DbxWebAuth instance was created using the deprecated DbxWebAuth(DbxRequestConfig,DbxAppInfo,String,DbxSessionStore) constructor, or if this (@link DbxWebAuth} instance was created with DbxAppInfo without app secret.

finishFromCode

public DbxAuthFinish finishFromCode(java.lang.String code)
                             throws DbxException

Call this after the user has visited the authorizaton URL and copy/pasted the authorization code that Dropbox gave them.

Parameters:

code - The authorization code shown to the user when they clicked "Allow" on the authorization, page on the Dropbox website, never null.

Throws:

DbxException - if an error occurs communicating with Dropbox.

finishFromCode

public DbxAuthFinish finishFromCode(java.lang.String code,
                                    java.lang.String redirectUri)
                             throws DbxException

Call this after the user has visited the authorizaton URL with a redirectUrl and copy/pasted the authorization code that Dropbox gave them.

Parameters:

code - The authorization code shown to the user when they clicked "Allow" on the authorization, page on the Dropbox website, never null.

redirectUri - The original redirect URI used by authorize(com.dropbox.core.DbxWebAuth.Request), never null.

Throws:

DbxException - if an error occurs communicating with Dropbox.

finishFromRedirect

public DbxAuthFinish finishFromRedirect(java.lang.String redirectUri,
                                        DbxSessionStore sessionStore,
                                        java.util.Map<java.lang.String,java.lang.String[]> params)
                                 throws DbxException,
                                        DbxWebAuth.BadRequestException,
                                        DbxWebAuth.BadStateException,
                                        DbxWebAuth.CsrfException,
                                        DbxWebAuth.NotApprovedException,
                                        DbxWebAuth.ProviderException

Call this after the user has visited the authorizaton URL and Dropbox has redirected them back to you at the redirect URI.

Parameters:

redirectUri - The original redirect URI used by authorize(com.dropbox.core.DbxWebAuth.Request), never null.

sessionStore - Session store used by authorize(com.dropbox.core.DbxWebAuth.Request) to store CSRF tokens, never null.

params - The query parameters on the GET request to your redirect URI, never null.

Throws:

BadRequestException - If the redirect request is missing required query parameters, contains duplicate parameters, or includes mutually exclusive parameters (e.g. "error" and "code").

DbxWebAuth.BadStateException - If the CSRF token retrieved from sessionStore is null or malformed.

DbxWebAuth.CsrfException - If the CSRF token passed in params does not match the CSRF token from sessionStore. This implies the redirect request may be forged.

DbxWebAuth.NotApprovedException - If the user chose to deny the authorization request.

DbxWebAuth.ProviderException - If an OAuth2 error response besides "access_denied" is set.

DbxException - If an error occurs communicating with Dropbox.

DbxWebAuth.BadRequestException

finish

@Deprecated
public DbxAuthFinish finish(java.util.Map<java.lang.String,java.lang.String[]> queryParams)
                                 throws DbxException,
                                        DbxWebAuth.BadRequestException,
                                        DbxWebAuth.BadStateException,
                                        DbxWebAuth.CsrfException,
                                        DbxWebAuth.NotApprovedException,
                                        DbxWebAuth.ProviderException

Deprecated. use finishFromRedirect(..) instead.

Call this after the user has visited the authorizaton URL and Dropbox has redirected them back to you (using the redirectUri you passed in to start(java.lang.String).

Parameters:

queryParams - The query parameters on the GET request to your redirectUri.

Throws:

java.lang.IllegalStateException - if this instance was not created using the deprecated DbxWebAuth(DbxRequestConfig,DbxAppInfo,String,DbxSessionStore) constructor

BadRequestException - If the redirect request is missing required query parameters, contains duplicate parameters, or includes mutually exclusive parameters (e.g. "error" and "code")

DbxWebAuth.BadStateException - If the CSRF token retrieved from sessionStore is missing or malformed. Missing tokens often imply the user session has expired.

DbxWebAuth.CsrfException - If the CSRF token passed in params does not match the CSRF token from sessionStore. This implies the redirect request may be forged.

DbxWebAuth.NotApprovedException - If the user chose to deny the authorization request

DbxWebAuth.ProviderException - If an OAuth 2.0 error response besides "access_denied" is set.

DbxException - If an error occurs communicating with Dropbox

DbxWebAuth.BadRequestException

newRequestBuilder

public static DbxWebAuth.Request.Builder newRequestBuilder()

Returns a new request builder with default values (e.g. no redirect).

Returns:

new request builder with default values