lib/google/api_client/auth/oauth_1.rb

   1 # Copyright 2010 Google Inc.
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #      http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 require "addressable/uri"
  16 require "oauth"
  17
  18 module Google #:nodoc:
  19   class APIClient #:nodoc:
  20     ##
  21     # An OAuth 1.0a handler.
  22     class OAuth1
  23       ##
  24       # The default OAuth 1.0a configuration values.  These may be overrided
  25       # simply by passing in the same key to the constructor.
  26       DEFAULTS = {
  27         :request_token_uri =>
  28           'https://www.google.com/accounts/OAuthGetRequestToken',
  29         :authorization_uri =>
  30           'https://www.google.com/accounts/OAuthAuthorizeToken',
  31         :access_token_uri =>
  32           'https://www.google.com/accounts/OAuthGetAccessToken',
  33         :scopes => [],
  34         :callback => OAuth::OUT_OF_BAND,
  35         :display_name => nil,
  36         :consumer_key => "anonymous",
  37         :consumer_secret => "anonymous"
  38       }
  39
  40       ##
  41       # A set of default configuration values specific to each service.  These
  42       # may be overrided simply by passing in the same key to the constructor.
  43       SERVICE_DEFAULTS = {
  44         :buzz => {
  45           :authorization_uri =>
  46             'https://www.google.com/buzz/api/auth/OAuthAuthorizeToken',
  47           :scopes => ["https://www.googleapis.com/auth/buzz"]
  48         }
  49       }
  50
  51       ##
  52       # Creates a new OAuth 1.0a handler.  This object obtains the tokens from
  53       # the provider and handles signing any requests to the API.
  54       #
  55       # @param [Hash] options
  56       #   The configuration options.
  57       #   <code>:service</code>::
  58       #     The name of the service.
  59       #   <code>:request_token_uri</code>::
  60       #     The OAuth endpoint for obtaining a request token.
  61       #   <code>:authorization_uri</code>::
  62       #     The OAuth endpoint for obtaining user permission.
  63       #   <code>:access_token_uri</code>::
  64       #     The OAuth endpoint for obtaining an access token.
  65       #   <code>:scopes</code>::
  66       #     An <code>Array</code> of scopes that define the access being
  67       #     requested to the API.
  68       #   <code>:callback</code>::
  69       #     The URI the user will be redirected to if access is granted to the
  70       #     API.  For development purposes, the special value
  71       #     <code>OAuth::OUT_OF_BAND</code> may also be used.
  72       #   <code>:display_name</code>::
  73       #     A human-readable service name to present to the user when they
  74       #     visit the <code>:authorization_uri</code>.
  75       #   <code>:consumer_key</code>::
  76       #     The consumer key you registered with the Google Accounts API.
  77       #   <code>:consumer_secret</code>::
  78       #     The consumer secret issued to you when you registered with the
  79       #     Google Accounts API.
  80       #
  81       # @return [Google::APIClient::OAuth1] The OAuth 1.0a handler.
  82       def initialize(options={})
  83         if options[:service] && SERVICE_DEFAULTS[options[:service]]
  84           @options = DEFAULTS.merge(SERVICE_DEFAULTS[options[:service]])
  85         else
  86           @options = DEFAULTS.clone
  87         end
  88         @options.merge!(options)
  89         @options[:request_token_uri] =
  90           Addressable::URI.parse(@options[:request_token_uri])
  91         @options[:authorization_uri] =
  92           Addressable::URI.parse(@options[:authorization_uri])
  93         @options[:access_token_uri] =
  94           Addressable::URI.parse(@options[:access_token_uri])
  95         if (@options[:request_token_uri].site !=
  96             @options[:authorization_uri].site) ||
  97             (@options[:request_token_uri].site !=
  98             @options[:authorization_uri].site)
  99           raise ArgumentError, "All OAuth endpoints must be on the same site."
 100         end
 101         @oauth_consumer = ::OAuth::Consumer.new(
 102           @options[:consumer_key], @options[:consumer_secret], {
 103             # This is an extremely unfortunate way to configure the consumer,
 104             # but not worth forking or patching to resolve.  Yet.
 105             :site               => @options[:request_token_uri].site,
 106             :scheme             => :header,
 107             :http_method        => :post,
 108             :request_token_path => @options[:request_token_uri].request_uri,
 109             :access_token_path  => @options[:access_token_uri].request_uri,
 110             :authorize_path     => @options[:authorization_uri].request_uri
 111           }
 112         )
 113       end
 114
 115       ##
 116       # Returns the configuration of the handler.  Configuration options that
 117       # are not recognized by the handler are ignored.
 118       #
 119       # @return [Hash] The configuration options.
 120       def options
 121         return @options
 122       end
 123
 124       ##
 125       # Returns the current request token.  Obtains a new request token if
 126       # one hasn't already been obtained.
 127       #
 128       # @return [OAuth::RequestToken] The request token.
 129       def request_token
 130         oauth_parameters = {
 131           :oauth_callback => @options[:callback]
 132         }
 133         app_parameters = {
 134           :scope => @options[:scopes].join(" ")
 135         }
 136         if @options[:display_name]
 137           app_parameters[:xoauth_displayname] = @options[:display_name]
 138         end
 139         return @request_token ||= @oauth_consumer.get_request_token(
 140           oauth_parameters,
 141           app_parameters
 142         )
 143       end
 144
 145       ##
 146       # Sets the request token for the handler.
 147       #
 148       # @param [OAuth::RequestToken] new_request_token The request token.
 149       def request_token=(new_request_token)
 150         if new_request_token.kind_of?(OAuth::RequestToken)
 151           @request_token = new_request_token
 152         else
 153           raise TypeError,
 154             "Expected OAuth::RequestToken, got #{new_request_token.class}."
 155         end
 156       end
 157
 158       ##
 159       # Returns the current access token.  Obtains a new access token if
 160       # one hasn't already been obtained.  An request token must have already
 161       # been obtained and authorized or this method will fail.
 162       #
 163       # @return [OAuth::AccessToken] The access token.
 164       def access_token
 165         return @access_token ||=
 166           @oauth_consumer.get_access_token(self.request_token)
 167       end
 168
 169       ##
 170       # Sets the access token for the handler.
 171       #
 172       # @param [OAuth::AccessToken] new_access_token The access token.
 173       def access_token=(new_access_token)
 174         if new_access_token.kind_of?(OAuth::AccessToken)
 175           @access_token = new_access_token
 176         else
 177           raise TypeError,
 178             "Expected OAuth::AccessToken, got #{new_access_token.class}."
 179         end
 180       end
 181
 182       ##
 183       # Returns the list of scopes for the handler.
 184       #
 185       # @return [Array] An <code>Array</code> of access scopes.
 186       def scopes
 187         return @options[:scopes]
 188       end
 189
 190       ##
 191       # Returns the callback for the handler.
 192       #
 193       # @return [String] The OAuth 1.0a callback for the consumer.
 194       def callback
 195         return @options[:callback]
 196       end
 197
 198       ##
 199       # Returns a human-readable service name to present to the user when they
 200       # visit the <code>:authorization_uri</code>.
 201       #
 202       # @return [String] The display name for the consumer.
 203       def display_name
 204         return @options[:display_name]
 205       end
 206
 207       ##
 208       # Returns the consumer key.
 209       #
 210       # @return [String]
 211       #   The consumer key you registered with the Google Accounts API.
 212       def consumer_key
 213         return @oauth_consumer.key
 214       end
 215
 216       ##
 217       # Returns the consumer key.
 218       #
 219       # @return [String]
 220       #   The consumer secret issued to you when you registered with the
 221       #   Google Accounts API.
 222       def consumer_secret
 223         return @oauth_consumer.secret
 224       end
 225
 226       ##
 227       # Returns the request token URI.
 228       #
 229       # @return [String]
 230       #   The OAuth endpoint for obtaining a request token.
 231       def request_token_uri
 232         return @oauth_consumer.request_token_url
 233       end
 234
 235       ##
 236       # Returns the authorization endpoint URI.  This URI is used to construct
 237       # the {#authorization_uri}.
 238       #
 239       # @return [String]
 240       #   The OAuth endpoint for obtaining user permission.
 241       def authorization_endpoint_uri
 242         return @oauth_consumer.authorize_url
 243       end
 244
 245       ##
 246       # Builds the authorization URI that the user will be redirected to.
 247       # Note that this value is derived from the
 248       # {#authorization_endpoint_uri}.
 249       #
 250       # @param [Hash] parameters
 251       #   The extra URI query parameters appended to the
 252       #   {#authorization_endpoint_uri}.
 253       #
 254       # @return [String]
 255       #   The URI to redirect the user to to obtain permission.
 256       def authorization_uri(parameters={})
 257         return self.request_token.authorize_url(parameters)
 258       end
 259
 260       ##
 261       # Returns the access token URI.
 262       #
 263       # @return [String]
 264       #   The OAuth endpoint for obtaining an access token.
 265       def access_token_uri
 266         return @oauth_consumer.access_token_url
 267       end
 268     end
 269   end
 270 end