com.dropbox.client2.session.WebAuthSession Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dropbox-java-sdk Show documentation
The Dropbox API for Java is a Dropbox supported client library for accessing the JSON+REST interface to Dropbox. It supports OAuth proxied authentication. It is designed to be simple and easy to use, as well as instructional in case you want to write your own. It is MIT licensed.
The newest version!
/*
 * Copyright (c) 2009-2011 Dropbox, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */


package com.dropbox.client2.session;

import java.util.Map;

import org.apache.http.HttpResponse;

import com.dropbox.client2.DropboxAPI;
import com.dropbox.client2.RESTUtility;
import com.dropbox.client2.RESTUtility.RequestMethod;
import com.dropbox.client2.exception.DropboxException;
import com.dropbox.client2.exception.DropboxIOException;
import com.dropbox.client2.exception.DropboxParseException;
import com.dropbox.client2.exception.DropboxServerException;

/**
 * Keeps track of a logged in user contains configuration options for the
 * {@link DropboxAPI}. This type of {@link Session} uses the web OAuth flow
 * to authenticate users:
 * 
 *   A request token + secret and redirect URL are retrieved using
 *   {@link WebAuthSession#getAuthInfo()} or
 *   {@link WebAuthSession#getAuthInfo(String)}.
 *   You store the request token + secret, and redirect the
 *   user to the redirect URL where they will authenticate with Dropbox and
 *   grant your app permission to access their account.
 *   Dropbox will redirect back to your site if it was provided a URL to
 *   do so (otherwise, you have to ask the user when he/she is done).
 *   The user's access token + secret are set on this session when you
 *   call {@link WebAuthSession#retrieveWebAccessToken(RequestTokenPair)} with
 *   the previously-saved request token + secret. You have a limited amount
 *   of time to make this call or the request token will expire.
 * 
 */
public class WebAuthSession extends AbstractSession {

    /**
     * Contains the info needed to send the user to the Dropbox web auth page
     * and later retrieve an access token + secret.
     */
    public static final class WebAuthInfo {

        /** The URL to redirect the user to. */
        public final String url;

        /**
         * The request token to later use with
         * {@link WebAuthSession#retrieveWebAccessToken(RequestTokenPair)}.
         * Expires after a short amount of time (currently 5 minutes).
         */
        public final RequestTokenPair requestTokenPair;

        private WebAuthInfo(String url, RequestTokenPair requestTokenPair) {
            this.url = url;
            this.requestTokenPair = requestTokenPair;
        }
    }

    /**
     * Creates a new web auth session with the given app key pair and access
     * type. The session will not be linked because it has no access token or
     * secret.
     */
    public WebAuthSession(AppKeyPair appKeyPair, AccessType type) {
        super(appKeyPair, type);
    }

    /**
     * Creates a new web auth session with the given app key pair and access
     * type. The session will be linked to the account corresponding to the
     * given access token pair.
     */
    public WebAuthSession(AppKeyPair appKeyPair, AccessType type,
            AccessTokenPair accessTokenPair) {
        super(appKeyPair, type, accessTokenPair);
    }

    /**
     * Starts an authentication request with Dropbox servers and gets all the
     * info you need to start authenticating a user. This call blocks for a
     * non-trivial amount of time due to a network operation. Because a
     * callback URL is not provided, you will have to somehow determine when
     * the user has finished authenticating on the Dropbox site (for example,
     * put up a prompt after you open a browser window for authentication). If
     * you want to provide a callback URL, see
     * {@link WebAuthSession#getAuthInfo(String)}.
     *
     * @return a {@link WebAuthInfo}, from which you can obtain the URL to
     *         redirect the user to and a request token + secret to log the
     *         user in later.
     *
     * @throws DropboxServerException if the server responds with an error
     *         code. See the constants in {@link DropboxServerException} for
     *         the meaning of each error code. The most common error codes you
     *         can expect from this call are 500, 502, and 503 (all related to
     *         internal Dropbox server issues).
     * @throws DropboxIOException if any network-related error occurs.
     * @throws DropboxParseException if a malformed or unknown response was
     *         received from the server.
     * @throws 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.
     */
    public WebAuthInfo getAuthInfo() throws DropboxException {
        return getAuthInfo(null);
    }

    /**
     * Starts an authentication request with Dropbox servers and gets all the
     * info you need to start authenticating a user. This call blocks for a
     * non-trivial amount of time due to a network operation.
     *
     * @param callbackUrl the URL to which Dropbox will redirect the user after
     *         he/she has authenticated on the Dropbox site.
     *
     * @return a {@link WebAuthInfo}, from which you can obtain the URL to
     *         redirect the user to and a request token + secret to log the
     *         user in later.
     *
     * @throws DropboxServerException if the server responds with an error
     *         code. See the constants in {@link DropboxServerException} for
     *         the meaning of each error code. The most common error codes you
     *         can expect from this call are 500, 502, and 503 (all for
     *         internal Dropbox server issues).
     * @throws DropboxIOException if any network-related error occurs.
     * @throws DropboxParseException if a malformed or unknown response was
     *         received from the server.
     * @throws 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.
     */
    public WebAuthInfo getAuthInfo(String callbackUrl)
            throws DropboxException {
        setUpToken("/oauth/request_token");

        // Request token pair was set as access token pair as they act the
        // same. Convert it here.
        AccessTokenPair accessTokenPair = getAccessTokenPair();
        RequestTokenPair requestTokenPair = new RequestTokenPair(
                accessTokenPair.key, accessTokenPair.secret);

        String[] args;
        if (callbackUrl != null) {
            args = new String[] {"oauth_token", requestTokenPair.key,
                                 "oauth_callback", callbackUrl,
                                 "locale", getLocale().toString()};
        } else {
            args = new String[] {"oauth_token", requestTokenPair.key,
                                 "locale", getLocale().toString()};
        }

        String url = RESTUtility.buildURL(getWebServer(),
                DropboxAPI.VERSION, "/oauth/authorize", args);

        return new WebAuthInfo(url, requestTokenPair);
    }

    /**
     * When called after the user is done authenticating, sets the user's
     * access token + secret on this session. This call blocks for a
     * non-trivial amount of time due to a network operation. Since the request
     * token + secret expire after a short time (currently 5 minutes), this
     * should be called right after a user comes back from auth on the Dropbox
     * site.
     *
     * @param requestTokenPair the request token pair from the {@link WebAuthInfo}
     *         returned from {@code getAuthInfo()}.
     *
     * @return the Dropbox UID of the authenticated user.
     *
     * @throws DropboxServerException if the server responds with an error
     *         code. See the constants in {@link 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).
     * @throws DropboxIOException if any network-related error occurs.
     * @throws DropboxParseException if a malformed or unknown response was
     *         received from the server.
     * @throws 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.
     */
    public String retrieveWebAccessToken(RequestTokenPair requestTokenPair)
            throws DropboxException {
        setAccessTokenPair(requestTokenPair);
        Map result = setUpToken("/oauth/access_token");
        return result.get("uid");
    }

    private Map setUpToken(String path)
            throws DropboxException {
        HttpResponse response = RESTUtility.streamRequest(RequestMethod.GET,
                getAPIServer(), path,
                DropboxAPI.VERSION,
                new String[] {"locale", getLocale().toString()},
                this).response;
        Map result = RESTUtility.parseAsQueryString(response);

        if (!result.containsKey("oauth_token") ||
                !result.containsKey("oauth_token_secret")) {
            throw new DropboxParseException("Did not get tokens from Dropbox");
        }

        setAccessTokenPair(new AccessTokenPair(
            result.get("oauth_token"), result.get("oauth_token_secret")));

        return result;
    }
}