class DropboxOAuth2Flow

The standard OAuth 2 authorization helper. Use this if you're writing a web app.

Public Class Methods

new(consumer_key, consumer_secret, redirect_uri, session, csrf_token_session_key, locale=nil) click to toggle source
  • consumer_key: Your Dropbox API app's “app key”

  • consumer_secret: Your Dropbox API app's “app secret”

  • redirect_uri: The URI that the Dropbox server will redirect the user to after the user finishes authorizing your app. This URI must be HTTPs-based and pre-registered with the Dropbox servers, though localhost URIs are allowed without pre-registration and can be either HTTP or HTTPS.

  • session: A hash that represents the current web app session (will be used to save the CSRF token)

  • csrf_token_key: The key to use when storing the CSRF token in the session (for example, :dropbox_auth_csrf_token)

  • locale: The locale of the user currently using your app (ex: “en” or “en_US”).

Calls superclass method
# File lib/dropbox_sdk.rb, line 524
def initialize(consumer_key, consumer_secret, redirect_uri, session, csrf_token_session_key, locale=nil)
  super(consumer_key, consumer_secret, locale)
  if not redirect_uri.is_a?(String)
    raise ArgumentError, "redirect_uri must be a String, got #{consumer_secret.inspect}"
  @redirect_uri = redirect_uri
  @session = session
  @csrf_token_session_key = csrf_token_session_key

Public Instance Methods

finish(query_params) click to toggle source

Call this after the user has visited the authorize URL (see: start()), approved your app, and was redirected to your redirect URI.

  • query_params: The query params on the GET request to your redirect URI.

Returns a tuple of (access_token, user_id, url_state). access_token can be used to construct a DropboxClient. user_id is the Dropbox user ID of the user that jsut approved your app. url_state is the value you originally passed in to start().

Can throw BadRequestError, BadStateError, CsrfError, NotApprovedError, ProviderError, and the standard DropboxError.

# File lib/dropbox_sdk.rb, line 574
def finish(query_params)
  csrf_token_from_session = @session[@csrf_token_session_key]

  # Check well-formedness of request.

  state = query_params['state']
  if state.nil?
    raise"Missing query parameter 'state'.")

  error = query_params['error']
  error_description = query_params['error_description']
  code = query_params['code']

  if not error.nil? and not code.nil?
    raise"Query parameters 'code' and 'error' are both set;" +
                  " only one must be set.")
  if error.nil? and code.nil?
    raise"Neither query parameter 'code' or 'error' is set.")

  # Check CSRF token

  if csrf_token_from_session.nil?
    raise"Missing CSRF token in session.");
  unless csrf_token_from_session.length > 20
    raise"CSRF token unexpectedly short: #{csrf_token_from_session.inspect}")

  split_pos = state.index('|')
  if split_pos.nil?
    given_csrf_token = state
    url_state = nil
    given_csrf_token, url_state = state.split('|', 2)
  if not Dropbox::safe_string_equals(csrf_token_from_session, given_csrf_token)
    raise"Expected #{csrf_token_from_session.inspect}, " +
                "got #{given_csrf_token.inspect}.")

  # Check for error identifier

  if not error.nil?
    if error == 'access_denied'
      # The user clicked "Deny"
      if error_description.nil?
        raise"No additional description from Dropbox.")
        raise"Additional description from Dropbox: #{error_description}")
      # All other errors.
      full_message = error
      if not error_description.nil?
        full_message += ": " + error_description

  # If everything went ok, make the network call to get an access token.

  access_token, user_id = _finish(code, @redirect_uri)
  return access_token, user_id, url_state
start(url_state=nil) click to toggle source

Starts the OAuth 2 authorizaton process, which involves redirecting the user to the returned “authorization URL” (a URL on the Dropbox website). When the user then either approves or denies your app access, Dropbox will redirect them to the redirect_uri you provided to the constructor, at which point you should call finish() to complete the process.

This function will also save a CSRF token to the session and csrf_token_session_key you provided to the constructor. This CSRF token will be checked on finish() to prevent request forgery.

  • url_state: Any data you would like to keep in the URL through the authorization process. This exact value will be returned to you by finish().

Returns the URL to redirect the user to.

# File lib/dropbox_sdk.rb, line 548
def start(url_state=nil)
  unless url_state.nil? or url_state.is_a?(String)
    raise ArgumentError, "url_state must be a String"

  csrf_token = SecureRandom.base64(16)
  state = csrf_token
  unless url_state.nil?
    state += "|" + url_state
  @session[@csrf_token_session_key] = csrf_token

  return _get_authorize_url(@redirect_uri, state)