cf-uaa-lib 1.3.1 → 1.3.2

data/lib/uaa/token_coder.rb

@@ -21,8 +21,8 @@ module CF::UAA
 # but they do not obtain them from the Authorization Server. This
 # class is for resource servers which accept bearer JWT tokens.
 #
-# For more on JWT, see the JSON Web \Token RFC here:
-# http://tools.ietf.org/id/draft-ietf-oauth-json-web-token-05.html
+# For more on JWT, see the JSON Web Token RFC here:
+# {http://tools.ietf.org/id/draft-ietf-oauth-json-web-token-05.html}
 #
 # An instance of this class can be used to decode and verify the contents
 # of a bearer token. Methods of this class can validate token signatures
@@ -30,19 +30,40 @@ module CF::UAA
 # is for a particular audience.
 class TokenCoder
 
-  def self.init_digest(algo) # :nodoc:
+  def self.init_digest(algo) # @private
     OpenSSL::Digest::Digest.new(algo.sub('HS', 'sha').sub('RS', 'sha'))
   end
 
-  # Takes a +token_body+ (the middle section of the JWT) and returns a signed
-  # token string.
-  def self.encode(token_body, skey, pkey = nil, algo = 'HS256')
+  def self.normalize_options(opts) # @private
+    opts = opts.dup
+    pk = opts[:pkey]
+    opts[:pkey] = OpenSSL::PKey::RSA.new(pk) if pk && !pk.is_a?(OpenSSL::PKey::PKey)
+    opts[:audience_ids] = Util.arglist(opts[:audience_ids])
+    opts[:algorithm] = 'HS256' unless opts[:algorithm]
+    opts[:verify] = true unless opts.key?(:verify)
+    opts
+  end
+
+  # Constructs a signed JWT.
+  # @param token_body Contents of the token in any object that can be converted to JSON.
+  # @param skey (see #initialize)
+  # @param pkey  (see #initialize)
+  # @return [String] a signed JWT token string in the form "xxxx.xxxxx.xxxx".
+  def self.encode(token_body, options = {}, obsolete1 = nil, obsolete2 = nil)
+    unless options.is_a?(Hash) && obsolete1.nil? && obsolete2.nil?
+      # deprecated: def self.encode(token_body, skey, pkey = nil, algo = 'HS256')
+      warn "#{self.class}##{__method__} is deprecated with these parameters. Please use options hash."
+      options = {:skey => options }
+      options[:pkey], options[:algorithm] = obsolete1, obsolete2
+    end
+    options = normalize_options(options)
+    algo = options[:algorithm]
     segments = [Util.json_encode64("typ" => "JWT", "alg" => algo)]
     segments << Util.json_encode64(token_body)
     if ["HS256", "HS384", "HS512"].include?(algo)
-      sig = OpenSSL::HMAC.digest(init_digest(algo), skey, segments.join('.'))
+      sig = OpenSSL::HMAC.digest(init_digest(algo), options[:skey], segments.join('.'))
     elsif ["RS256", "RS384", "RS512"].include?(algo)
-      sig = pkey.sign(init_digest(algo), segments.join('.'))
+      sig = options[:pkey].sign(init_digest(algo), segments.join('.'))
     elsif algo == "none"
       sig = ""
     else
@@ -52,27 +73,37 @@ class TokenCoder
     segments.join('.')
   end
 
-  # Decodes a +token+ and optionally verifies the signature. Both a secret key
-  # and a public key can be provided for signature verification. The JWT
-  # +token+ header indicates what signature algorithm was used and the
+  # Decodes a JWT token and optionally verifies the signature. Both a
+  # symmetrical key and a public key can be provided for signature verification.
+  # The JWT header indicates what signature algorithm was used and the
   # corresponding key is used to verify the signature (if +verify+ is true).
-  # Returns a hash of the token contents or raises +DecodeError+.
-  def self.decode(token, skey = nil, pkey = nil, verify = true)
-    pkey = OpenSSL::PKey::RSA.new(pkey) unless pkey.nil? || pkey.is_a?(OpenSSL::PKey::PKey)
+  # @param [String] token A JWT token as returned by {TokenCoder.encode}
+  # @param skey (see #initialize)
+  # @param pkey  (see #initialize)
+  # @param [Boolean] verify
+  # @return [Hash] the token contents
+  def self.decode(token, options = {}, obsolete1 = nil, obsolete2 = nil)
+    unless options.is_a?(Hash) && obsolete1.nil? && obsolete2.nil?
+      # deprecated: def self.decode(token, skey = nil, pkey = nil, verify = true)
+      warn "#{self.class}##{__method__} is deprecated with these parameters. Please use options hash."
+      options = {:skey => options }
+      options[:pkey], options[:verify] = obsolete1, obsolete2
+    end
+    options = normalize_options(options)
     segments = token.split('.')
     raise DecodeError, "Not enough or too many segments" unless [2,3].include? segments.length
     header_segment, payload_segment, crypto_segment = segments
     signing_input = [header_segment, payload_segment].join('.')
     header = Util.json_decode64(header_segment)
-    payload = Util.json_decode64(payload_segment)
-    return payload if !verify || (algo = header["alg"]) == "none"
+    payload = Util.json_decode64(payload_segment, (:sym if options[:symbolize_keys]))
+    return payload if !options[:verify] || (algo = header["alg"]) == "none"
     signature = Util.decode64(crypto_segment)
     if ["HS256", "HS384", "HS512"].include?(algo)
       raise DecodeError, "Signature verification failed" unless
-          signature == OpenSSL::HMAC.digest(init_digest(algo), skey, signing_input)
+          signature == OpenSSL::HMAC.digest(init_digest(algo), options[:skey], signing_input)
     elsif ["RS256", "RS384", "RS512"].include?(algo)
       raise DecodeError, "Signature verification failed" unless
-          pkey.verify(init_digest(algo), signature, signing_input)
+          options[:pkey].verify(init_digest(algo), signature, signing_input)
     else
       raise DecodeError, "Algorithm not supported"
     end
@@ -82,17 +113,24 @@ class TokenCoder
   # Creates a new token en/decoder for a service that is associated with
   # the the audience_ids, the symmetrical token validation key, and the
   # public and/or private keys. Parameters:
-  # +audience_ids+:: an array or space separated strings. Should
-  #                  indicate values which indicate the token is intended for this service
-  #                  instance. It will be compared with tokens as they are decoded to
-  #                  ensure that the token was intended for this audience.
-  # +skey+:: is used to sign and validate tokens using symetrical key algoruthms
-  # +pkey+:: may be a string or File which includes public and
-  #          optionally private key data in PEM or DER formats. The private key
-  #          is used to sign tokens and the public key is used to validate tokens.
-  def initialize(audience_ids, skey, pkey = nil)
-    @audience_ids, @skey, @pkey = Util.arglist(audience_ids), skey, pkey
-    @pkey = OpenSSL::PKey::RSA.new(pkey) unless pkey.nil? || pkey.is_a?(OpenSSL::PKey::PKey)
+  # @param [Array<String>, String] audience_ids An array or space separated
+  #   strings of values which indicate the token is intended for this service
+  #   instance. It will be compared with tokens as they are decoded to ensure
+  #   that the token was intended for this audience.
+  # @param [String] skey is used to sign and validate tokens using symmetrical
+  #   key algoruthms
+  # @param [String, File, OpenSSL::PKey::PKey] pkey may be a String, File in
+  #   PEM or DER formats. May include public and/or private key data. The
+  #   private key is used to sign tokens and the public key is used to
+  #   validate tokens.
+  def initialize(options = {}, obsolete1 = nil, obsolete2 = nil)
+    unless options.is_a?(Hash) && obsolete1.nil? && obsolete2.nil?
+      # deprecated: def initialize(audience_ids, skey, pkey = nil)
+      warn "#{self.class}##{__method__} is deprecated with these parameters. Please use options hash."
+      options = {:audience_ids => options }
+      options[:skey], options[:pkey] = obsolete1, obsolete2
+    end
+    @options = self.class.normalize_options(options)
   end
 
   # Encode a JWT token. Takes a hash of values to use as the token body.
@@ -100,26 +138,30 @@ class TokenCoder
   # Algorithm may be HS256, HS384, HS512, RS256, RS384, RS512, or none --
   # assuming the TokenCoder instance is configured with the appropriate
   # key -- i.e. pkey must include a private key for the RS algorithms.
-  def encode(token_body = {}, algorithm = 'HS256')
-    token_body['aud'] = @audience_ids unless token_body['aud']
-    token_body['exp'] = Time.now.to_i + 7 * 24 * 60 * 60 unless token_body['exp']
-    self.class.encode(token_body, @skey, @pkey, algorithm)
+  # @param token_body (see TokenCoder.encode)
+  # @return (see TokenCoder.encode)
+  def encode(token_body = {}, algorithm = nil)
+    token_body[:aud] = @options[:audience_ids] if @options[:audience_ids] && !token_body[:aud] && !token_body['aud']
+    token_body[:exp] = Time.now.to_i + 7 * 24 * 60 * 60 unless token_body[:exp] || token_body['exp']
+    self.class.encode(token_body, algorithm ? @options.merge(:algorithm => algorithm) : @options)
   end
 
   # Returns hash of values decoded from the token contents. If the
-  # token contains audience ids in the +aud+ field and they do not contain one
-  # or more of the +audience_ids+ in this instance, an AuthError will be raised.
-  # AuthError is raised if the token has expired.
+  # audience_ids were specified in the options to this instance (see #initialize)
+  # and the token does not contain one or more of those audience_ids, an
+  # AuthError will be raised. AuthError is raised if the token has expired.
+  # @param [String] auth_header (see Scim.initialize#auth_header)
+  # @return (see TokenCoder.decode)
   def decode(auth_header)
-    unless auth_header && (tkn = auth_header.split).length == 2 && tkn[0] =~ /^bearer$/i
+    unless auth_header && (tkn = auth_header.split(' ')).length == 2 && tkn[0] =~ /^bearer$/i
       raise DecodeError, "invalid authentication header: #{auth_header}"
     end
-    reply = self.class.decode(tkn[1], @skey, @pkey)
-    auds = Util.arglist(reply["aud"])
-    if @audience_ids && (!auds || (auds & @audience_ids).empty?)
-      raise AuthError, "invalid audience: #{auds.join(' ')}"
+    reply = self.class.decode(tkn[1], @options)
+    auds = Util.arglist(reply[:aud] || reply['aud'])
+    if @options[:audience_ids] && (!auds || (auds & @options[:audience_ids]).empty?)
+      raise AuthError, "invalid audience: #{auds}"
     end
-    exp = reply["exp"]
+    exp = reply[:exp] || reply['exp']
     unless exp.is_a?(Integer) && exp > Time.now.to_i
       raise AuthError, "token expired"
     end

data/lib/uaa/token_issuer.rb

@@ -16,24 +16,28 @@ require 'uaa/http'
 
 module CF::UAA
 
-# The Token class is returned by various TokenIssuer methods. It holds access
+# The TokenInfo class is returned by various TokenIssuer methods. It holds access
 # and refresh tokens as well as token meta-data such as token type and
-# expiration time. See Token#info for contents.
-class Token
+# expiration time. See {TokenInfo#info} for contents.
+class TokenInfo
 
-  # Returns a hash of information about the current token. The info hash MUST include
+  # Information about the current token. The info hash MUST include
   # access_token, token_type and scope (if granted scope differs from requested
   # scope). It should include expires_in. It may include refresh_token, scope,
   # and other values from the auth server.
+  # @return [Hash]
   attr_reader :info
 
-  def initialize(info) # :nodoc:
-    @info = info
+  # Normally instantiated by {TokenIssuer}.
+  def initialize(info) @info = info  end
+
+  # Constructs a string for use in an authorization header from the contents of
+  # the TokenInfo.
+  # @return [String] Typically a string such as "bearer xxxx.xxxx.xxxx".
+  def auth_header
+    "#{@info[:token_type] || @info['token_type']} #{@info[:access_token] || @info['access_token']}"
   end
 
-  # Returns a string for use in an authorization header that is constructed
-  # from contents of the Token. Typically a string such as "bearer xxxx.xxxx.xxxx".
-  def auth_header; "#{info['token_type']} #{info['access_token']}" end
 end
 
 # Client Apps that want to get access to resource servers on behalf of their
@@ -42,51 +46,96 @@ end
 # class is for these use cases.
 #
 # In general most of this class is an implementation of the client pieces of
-# the OAuth2 protocol. See http://tools.ietf.org/html/rfc6749
+# the OAuth2 protocol. See {http://tools.ietf.org/html/rfc6749}
 class TokenIssuer
 
   include Http
 
-  # parameters:
-  # [+target+] The base URL of a UAA's oauth authorize endpoint. For example
-  #            the target would be \https://login.cloudfoundry.com if the
-  #            endpoint is \https://login.cloudfoundry.com/oauth/authorize.
-  #            The target would be \http://localhost:8080/uaa if the endpoint
-  #            is \http://localhost:8080/uaa/oauth/authorize.
-  # [+client_id+] The oauth2 client id. See http://tools.ietf.org/html/rfc6749#section-2.2
-  # [+client_secret+] needed to authenticate the client for all grant types
-  #                   except implicit.
-  # [+token_target+] The base URL of the oauth token endpoint. If not specified,
-  #                  +target+ is used.
-  def initialize(target, client_id, client_secret = nil, token_target = nil)
+  private
+
+  def random_state; SecureRandom.hex end
+
+  def parse_implicit_params(encoded_params, state)
+    params = Util.decode_form(encoded_params)
+    raise BadResponse, "mismatched state" unless state && params.delete('state') == state
+    raise TargetError.new(params), "error response from #{@target}" if params['error']
+    raise BadResponse, "no type and token" unless params['token_type'] && params['access_token']
+    exp = params['expires_in'].to_i
+    params['expires_in'] = exp if exp.to_s == params['expires_in']
+    TokenInfo.new(Util.hash_keys!(params, @key_style))
+  rescue URI::InvalidURIError, ArgumentError
+    raise BadResponse, "received invalid response from target #{@target}"
+  end
+
+  # returns a CF::UAA::TokenInfo object which includes the access token and metadata.
+  def request_token(params)
+    if scope = Util.arglist(params.delete(:scope))
+      params[:scope] = Util.strlist(scope)
+    end
+    headers = {'content-type' => 'application/x-www-form-urlencoded',
+        'accept' => 'application/json',
+        'authorization' => Http.basic_auth(@client_id, @client_secret) }
+    reply = json_parse_reply(@key_style, *request(@token_target, :post,
+        '/oauth/token', Util.encode_form(params), headers))
+    raise BadResponse unless reply[jkey :token_type] && reply[jkey :access_token]
+    TokenInfo.new(reply)
+  end
+
+  def authorize_path_args(response_type, redirect_uri, scope, state = random_state, args = {})
+    params = args.merge(:client_id => @client_id, :response_type => response_type,
+        :redirect_uri => redirect_uri, :state => state)
+    params[:scope] = scope = Util.strlist(scope) if scope = Util.arglist(scope)
+    params[:nonce], params[:response_type] = state, "#{response_type} id_token" if scope && scope.include?('openid')
+    "/oauth/authorize?#{Util.encode_form(params)}"
+  end
+
+  def jkey(k) @key_style ? k : k.to_s end
+
+  public
+
+  # @param [String] target The base URL of a UAA's oauth authorize endpoint.
+  #   For example the target would be {https://login.cloudfoundry.com} if the
+  #   endpoint is {https://login.cloudfoundry.com/oauth/authorize}.
+  #   The target would be {http://localhost:8080/uaa} if the endpoint
+  #   is {http://localhost:8080/uaa/oauth/authorize}.
+  # @param [String] client_id The oauth2 client id, see
+  #   {http://tools.ietf.org/html/rfc6749#section-2.2}
+  # @param [String] client_secret Needed to authenticate the client for all
+  #   grant types except implicit.
+  # @param [Hash] options can be
+  #   * +:token_target+, the base URL of the oauth token endpoint -- if
+  #     not specified, +target+ is used.
+  #   * +:symbolize_keys+, if true, returned hash keys are symbols.
+  def initialize(target, client_id, client_secret = nil, options = {})
     @target, @client_id, @client_secret = target, client_id, client_secret
-    @token_target = token_target || target
+    @token_target = options[:token_target] || target
+    @key_style = options[:symbolize_keys] ? :sym : nil
   end
 
   # Allows an app to discover what credentials are required for
-  # #implicit_grant_with_creds. Returns a hash of credential names with type
-  # and suggested prompt value, e.g.
-  #   {"username":["text","Email"],"password":["password","Password"]}
+  # {#implicit_grant_with_creds}.
+  # @return [Hash] of credential names with type and suggested prompt value,
+  #   e.g. !{"username":["text","Email"],"password":["password","Password"]}
   def prompts
-    reply = json_get @target, '/login'
-    return reply['prompts'] if reply && reply['prompts']
+    reply = json_get(@target, '/login')
+    return reply[jkey :prompts] if reply && reply[jkey :prompts]
     raise BadResponse, "No prompts in response from target #{@target}"
   end
 
   # Gets an access token in a single call to the UAA with the user
-  # credentials used for authentication. The +credentials+ should
-  # be an object such as a hash that can be converted to a json
-  # representation of the credential name/value pairs
-  # corresponding to the keys retrieved by #prompts.
-  # Returns a Token.
+  # credentials used for authentication.
+  # @param credentials should be an object such as a hash that can be converted
+  #   to a json representation of the credential name/value pairs corresponding to
+  #   the keys retrieved by {#prompts}.
+  # @return [TokenInfo]
   def implicit_grant_with_creds(credentials, scope = nil)
     # this manufactured redirect_uri is a convention here, not part of OAuth2
     redir_uri = "https://uaa.cloudfoundry.com/redirect/#{@client_id}"
-    uri = authorize_path_args("token", redir_uri, scope, state = SecureRandom.uuid)
+    uri = authorize_path_args("token", redir_uri, scope, state = random_state)
 
     # the accept header is only here so the uaa will issue error replies in json to aid debugging
     headers = {'content-type' => 'application/x-www-form-urlencoded', 'accept' => 'application/json' }
-    body = URI.encode_www_form(credentials.merge('source' => 'credentials'))
+    body = Util.encode_form(credentials.merge(:source => 'credentials'))
     status, body, headers = request(@target, :post, uri, body, headers)
     raise BadResponse, "status #{status}" unless status == 302
     req_uri, reply_uri = URI.parse(redir_uri), URI.parse(headers['location'])
@@ -98,141 +147,109 @@ class TokenIssuer
   end
 
   # Constructs a uri that the client is to return to the browser to direct
-  # the user to the authorization server to get an authcode. The +redirect_uri+
-  # is embedded in the returned uri so the authorization server can redirect
-  # the user back to the client app.
+  # the user to the authorization server to get an authcode.
+  # @param [String] redirect_uri (see #authcode_uri)
+  # @return [String]
   def implicit_uri(redirect_uri, scope = nil)
     @target + authorize_path_args("token", redirect_uri, scope)
   end
 
   # Gets a token via an implicit grant.
-  # [+authcode_uri+] must be from a previous call to #implicit_uri and contains
-  #                  state used to validate the contents of the reply from the
-  #                  Authorization Server.
-  # [+callback_fragment+] must be the fragment portion of the URL received by
-  #                       user's browser after the Authorization Server
-  #                       redirects back to the +redirect_uri+ that was given to
-  #                       #implicit_uri. How the application get's the contents
-  #                       of the fragment is application specific -- usually
-  #                       some javascript in the page at the +redirect_uri+.
-  #
-  # See http://tools.ietf.org/html/rfc6749#section-4.2 .
-  #
-  # Returns a Token.
+  # @param [String] implicit_uri must be from a previous call to
+  #   {#implicit_uri}, contains state used to validate the contents of the
+  #   reply from the server.
+  # @param [String] callback_fragment must be the fragment portion of the URL
+  #   received by the user's browser after the server redirects back to the
+  #   +redirect_uri+ that was given to {#implicit_uri}. How the application
+  #   gets the contents of the fragment is application specific -- usually
+  #   some javascript in the page at the +redirect_uri+.
+  # @see http://tools.ietf.org/html/rfc6749#section-4.2
+  # @return [TokenInfo]
   def implicit_grant(implicit_uri, callback_fragment)
-    in_params = Util.decode_form_to_hash(URI.parse(implicit_uri).query)
+    in_params = Util.decode_form(URI.parse(implicit_uri).query)
     unless in_params['state'] && in_params['redirect_uri']
       raise ArgumentError, "redirect must happen before implicit grant"
     end
-    parse_implicit_params callback_fragment, in_params['state']
+    parse_implicit_params(callback_fragment, in_params['state'])
   end
 
   # A UAA extension to OAuth2 that allows a client to pre-authenticate a
   # user at the start of an authorization code flow. By passing in the
-  # user's credentials (see #prompts) the Authorization Server can establish
-  # a session with the user's browser without reprompting for authentication.
-  # This is useful for user account management apps so that they can create
-  # a user account, or reset a password for the user, without requiring the
-  # user to type in their credentials again.
+  # user's credentials the server can establish a session with the user's
+  # browser without reprompting for authentication. This is useful for
+  # user account management apps so that they can create a user account,
+  # or reset a password for the user, without requiring the user to type
+  # in their credentials again.
+  # @param [String] credentials (see #implicit_grant_with_creds)
+  # @param [String] redirect_uri (see #authcode_uri)
+  # @return (see #authcode_uri)
   def autologin_uri(redirect_uri, credentials, scope = nil)
-    headers = {'content_type' => 'application/x-www-form-urlencoded', 'accept' => 'application/json',
+    headers = {'content-type' => 'application/x-www-form-urlencoded',
+        'accept' => 'application/json',
         'authorization' => Http.basic_auth(@client_id, @client_secret) }
-    body = URI.encode_www_form(credentials)
-    reply = json_parse_reply(*request(@target, :post, "/autologin", body, headers))
+    body = Util.encode_form(credentials)
+    reply = json_parse_reply(nil, *request(@target, :post, "/autologin", body, headers))
     raise BadResponse, "no autologin code in reply" unless reply['code']
-    @target + authorize_path_args('code', redirect_uri, scope, SecureRandom.uuid, code: reply[:code])
+    @target + authorize_path_args('code', redirect_uri, scope,
+        random_state, :code => reply['code'])
   end
 
   # Constructs a uri that the client is to return to the browser to direct
-  # the user to the authorization server to get an authcode. The redirect_uri
-  # is embedded in the returned uri so the authorization server can redirect
-  # the user back to the client app.
+  # the user to the authorization server to get an authcode.
+  # @param [String] redirect_uri is embedded in the returned uri so the server
+  #   can redirect the user back to the caller's endpoint.
+  # @return [String] uri which
   def authcode_uri(redirect_uri, scope = nil)
     @target + authorize_path_args('code', redirect_uri, scope)
   end
 
   # Uses the instance client credentials in addition to +callback_query+
   # to get a token via the authorization code grant.
-  # [+authcode_uri+] must be from a previous call to #authcode_uri and contains
-  #                  state used to validate the contents of the reply from the
-  #                  Authorization Server.
-  # [callback_query] must be the query portion of the URL received by the
-  #                  client after the user's browser is redirected back from
-  #                  the Authorization server. It contains the authorization
-  #                  code.
-  #
-  # See http://tools.ietf.org/html/rfc6749#section-4.1 .
-  #
-  # Returns a Token.
+  # @param [String] authcode_uri must be from a previous call to {#authcode_uri}
+  #   and contains state used to validate the contents of the reply from the
+  #   server.
+  # @param [String] callback_query must be the query portion of the URL
+  #   received by the client after the user's browser is redirected back from
+  #   the server. It contains the authorization code.
+  # @see http://tools.ietf.org/html/rfc6749#section-4.1
+  # @return [TokenInfo]
   def authcode_grant(authcode_uri, callback_query)
-    ac_params = Util.decode_form_to_hash(URI.parse(authcode_uri).query)
+    ac_params = Util.decode_form(URI.parse(authcode_uri).query)
     unless ac_params['state'] && ac_params['redirect_uri']
       raise ArgumentError, "authcode redirect must happen before authcode grant"
     end
     begin
-      params = Util.decode_form_to_hash(callback_query)
+      params = Util.decode_form(callback_query)
       authcode = params['code']
       raise BadResponse unless params['state'] == ac_params['state'] && authcode
     rescue URI::InvalidURIError, ArgumentError, BadResponse
       raise BadResponse, "received invalid response from target #{@target}"
     end
-    request_token('grant_type' => 'authorization_code', 'code' => authcode, 'redirect_uri' => ac_params['redirect_uri'])
+    request_token(:grant_type => 'authorization_code', :code => authcode,
+        :redirect_uri => ac_params['redirect_uri'])
   end
 
   # Uses the instance client credentials in addition to the +username+
   # and +password+ to get a token via the owner password grant.
-  # See http://tools.ietf.org/html/rfc6749#section-4.3 .
-  # Returns a Token.
+  # See {http://tools.ietf.org/html/rfc6749#section-4.3}.
+  # @return [TokenInfo]
   def owner_password_grant(username, password, scope = nil)
-    request_token('grant_type' => 'password', 'username' => username, 'password' => password, 'scope' => scope)
+    request_token(:grant_type => 'password', :username => username,
+        :password => password, :scope => scope)
   end
 
   # Uses the instance client credentials to get a token with a client
   # credentials grant. See http://tools.ietf.org/html/rfc6749#section-4.4
-  # Returns a Token.
+  # @return [TokenInfo]
   def client_credentials_grant(scope = nil)
-    request_token('grant_type' => 'client_credentials', 'scope' => scope)
+    request_token(:grant_type => 'client_credentials', :scope => scope)
   end
 
   # Uses the instance client credentials and the given +refresh_token+ to get
   # a new access token. See http://tools.ietf.org/html/rfc6749#section-6
-  # Returns a Token, which may include a new refresh token as well as an access token.
+  # @return [TokenInfo] which may include a new refresh token as well as an access token.
   def refresh_token_grant(refresh_token, scope = nil)
-    request_token('grant_type' => 'refresh_token', 'refresh_token' => refresh_token, 'scope' => scope)
-  end
-
-  private
-
-  def parse_implicit_params(encoded_params, state)
-    params = Util.decode_form_to_hash(encoded_params)
-    raise BadResponse, "mismatched state" unless state && params.delete('state') == state
-    raise TargetError.new(params), "error response from #{@target}" if params['error']
-    raise BadResponse, "no type and token" unless params['token_type'] && params['access_token']
-    exp = params['expires_in'].to_i
-    params['expires_in'] = exp if exp.to_s == params['expires_in']
-    Token.new params
-  rescue URI::InvalidURIError, ArgumentError
-    raise BadResponse, "received invalid response from target #{@target}"
-  end
-
-  # returns a CF::UAA::Token object which includes the access token and metadata.
-  def request_token(params)
-    if scope = Util.arglist(params.delete('scope'))
-      params['scope'] = Util.strlist(scope)
-    end
-    headers = {'content-type' => 'application/x-www-form-urlencoded', 'accept' => 'application/json',
-        'authorization' => Http.basic_auth(@client_id, @client_secret) }
-    body = URI.encode_www_form(params)
-    reply = json_parse_reply(*request(@token_target, :post, '/oauth/token', body, headers))
-    raise BadResponse unless reply['token_type'] && reply['access_token']
-    Token.new reply
-  end
-
-  def authorize_path_args(response_type, redirect_uri, scope, state = SecureRandom.uuid, args = {})
-    params = args.merge('client_id' => @client_id, 'response_type' => response_type, 'redirect_uri' => redirect_uri, 'state' => state)
-    params['scope'] = scope = Util.strlist(scope) if scope = Util.arglist(scope)
-    params['nonce'], params['response_type'] = state, "#{response_type} id_token" if scope && scope.include?('openid')
-    "/oauth/authorize?#{URI.encode_www_form(params)}"
+    request_token(:grant_type => 'refresh_token', :refresh_token => refresh_token, :scope => scope)
   end
 
 end