com.dropbox.client2.session

Class WebOAuth2Session

java.lang.Object

com.dropbox.client2.session.AbstractSession

com.dropbox.client2.session.WebOAuth2Session

All Implemented Interfaces:

Session

public class WebOAuth2Session
extends AbstractSession

Keeps track of a logged in user contains configuration options for the DropboxAPI. This type of Session uses the OAuth2 "auth code flow" to authenticate users:

1. A redirect URL are retrieved using getAuthorizeURL() or getAuthorizeURL(String, String).
2. You redirect the user to the redirect URL where they will authenticate with Dropbox and grant your app permission to access their account.
3. Dropbox will redirect back to your site with a auth code in the query string if it was provided a URL to do so (otherwise, you have to ask the user for the auth code when he/she is done).
4. The user's access token is set on this session when you call retrieveWebAccessToken(String, String) with the auth code from Dropbox and the same redirect URL you passed to getAuthorizeURL(String, String). You have a limited amount of time to make this call or the request token will expire.

Nested Class Summary

Nested classes/interfaces inherited from interface com.dropbox.client2.session.Session

Session.AccessType, Session.ProxyInfo

Constructor Summary

Constructors

Constructor and Description
WebOAuth2Session(AppKeyPair appKeyPair) Creates a new web auth session with the given app key pair.
WebOAuth2Session(AppKeyPair appKeyPair, java.lang.String oauth2AccessToken) Creates a new web auth session with the given app key pair.

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	getAuthorizeURL()
java.lang.String	getAuthorizeURL(java.lang.String redirectUrl, java.lang.String csrfToken) Starts an authentication request with Dropbox servers and computes the URL the user needs to visit to authorize your app.
java.lang.String	retrieveWebAccessToken(java.lang.String code, java.lang.String redirectUrl) Obtain an access token for a user.

Methods inherited from class com.dropbox.client2.session.AbstractSession

getAccessTokenPair, getAccessType, getAPIServer, getAppKeyPair, getContentServer, getHttpClient, getLocale, getOAuth2AccessToken, getProxyInfo, getWebServer, isLinked, setAccessTokenPair, setOAuth2AccessToken, setRequestTimeout, sign, unlink

Methods inherited from class java.lang.Object

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

Constructor Detail

WebOAuth2Session

public WebOAuth2Session(AppKeyPair appKeyPair)

Creates a new web auth session with the given app key pair. The session will not be linked because it has no access token.

WebOAuth2Session

public WebOAuth2Session(AppKeyPair appKeyPair,
                java.lang.String oauth2AccessToken)

Creates a new web auth session with the given app key pair. The session will also be linked to the account corresponding to the given access token.

Method Detail

getAuthorizeURL

public java.lang.String getAuthorizeURL()

getAuthorizeURL

public java.lang.String getAuthorizeURL(java.lang.String redirectUrl,
                               java.lang.String csrfToken)

Starts an authentication request with Dropbox servers and computes the URL the user needs to visit to authorize your app.

Parameters:

redirectUrl - the URL to which Dropbox will redirect the user after he/she has authenticated on the Dropbox site. If the user authorizes your app, the server will pass a code query parameter that you should pass to retrieveWebAccessToken(String, String) to finish authentication. If the user denies access to your app, the query will contain error and error_description parameters. Make sure this URL appears in the "Redirect URIs" section on the App Console page for your app. If you pass null for this parameter, the user will be presented with the Auth code.

csrfToken - If not null, this will appear as the state query parameter when the server redirects the user to redirectURL. This should be a short string tied to the authentication state of the user in your system. When a user fetches redirectURL, you should verify the state parameter is the same what you pass to this function. This protects your application against cross-site request forgery. While technically optional, this parameter should always be passed when using redirects.

Returns:

the URL to redirect the user to to authorize your app

retrieveWebAccessToken

public java.lang.String retrieveWebAccessToken(java.lang.String code,
                                      java.lang.String redirectUrl)
                                        throws DropboxException

Obtain an access token for a user. This is the second step of OAuth2 "Auth code flow". After you send the user to the authorize URL, you can use the authorized request code with this method to get the access token to use for future operations. The access token is stored on the session object.

Parameters:

code - the auth code sent to you by the Dropbox server

redirectUrl - This should be exactly the same as was passed to getAuthorizeURL. (Possibly null).

Returns:

the access token for the user

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 401 (bad request token), 403 (bad app key pair), 500, 502, and 503 (all for internal Dropbox server issues).

DropboxIOException - if any network-related error occurs.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.