cloulu 0.0.0 → 0.1.1

data/lib/uaa/token_coder.rb

@@ -0,0 +1,196 @@
+#--
+# Cloud Foundry 2012.02.03 Beta
+# Copyright (c) [2009-2012] VMware, Inc. All Rights Reserved.
+#
+# This product is licensed to you under the Apache License, Version 2.0 (the "License").
+# You may not use this product except in compliance with the License.
+#
+# This product includes a number of subcomponents with
+# separate copyright notices and license terms. Your use of these
+# subcomponents is subject to the terms and conditions of the
+# subcomponent's license, as noted in the LICENSE file.
+#++
+
+require "openssl"
+require "uaa/util"
+
+module CF::UAA
+
+# this code does not support the given token signature algorithim
+class SignatureNotSupported < DecodeError; end
+
+# this instance policy does not accept the given token signature algorithim
+class SignatureNotAccepted < DecodeError; end
+
+class InvalidSignature < DecodeError; end
+class InvalidTokenFormat < DecodeError; end
+class TokenExpired < AuthError; end
+class InvalidAudience < AuthError; end
+
+# This class is for OAuth Resource Servers.
+# Resource Servers get tokens and need to validate and decode them,
+# 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}
+#
+# 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
+# with a secret or public key, and they can also enforce that the token
+# is for a particular audience.
+class TokenCoder
+
+  def self.init_digest(algo) # @private
+    OpenSSL::Digest::Digest.new(algo.sub('HS', 'sha').sub('RS', 'sha'))
+  end
+
+  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[:accept_algorithms] = Util.arglist(opts[:accept_algorithms],
+        ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512"])
+    opts
+  end
+
+  # Constructs a signed JWT.
+  # @param token_body Contents of the token in any object that can be converted to JSON.
+  # @param options (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), options[:skey], segments.join('.'))
+    elsif ["RS256", "RS384", "RS512"].include?(algo)
+      sig = options[:pkey].sign(init_digest(algo), segments.join('.'))
+    elsif algo == "none"
+      sig = ""
+    else
+      raise SignatureNotSupported, "unsupported signing method"
+    end
+    segments << Util.encode64(sig)
+    segments.join('.')
+  end
+
+  # 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).
+  # @param [String] token A JWT token as returned by {TokenCoder.encode}
+  # @param options (see #initialize)
+  # @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 InvalidTokenFormat, "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, (:sym if options[:symbolize_keys]))
+    return payload unless options[:verify]
+    raise SignatureNotAccepted, "Signature algorithm not accepted" unless
+        options[:accept_algorithms].include?(algo = header["alg"])
+    return payload if algo == 'none'
+    signature = Util.decode64(crypto_segment)
+    if ["HS256", "HS384", "HS512"].include?(algo)
+      raise InvalidSignature, "Signature verification failed" unless
+          options[:skey] && signature == OpenSSL::HMAC.digest(init_digest(algo), options[:skey], signing_input)
+    elsif ["RS256", "RS384", "RS512"].include?(algo)
+      raise InvalidSignature, "Signature verification failed" unless
+          options[:pkey] && options[:pkey].verify(init_digest(algo), signature, signing_input)
+    else
+      raise SignatureNotSupported, "Algorithm not supported"
+    end
+    payload
+  end
+
+  # 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.
+  # @param [Hash] options Supported options:
+  #   * :audience_ids [Array<String>, String] -- An array or space separated
+  #     string 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.
+  #   * :skey [String] -- used to sign and validate tokens using symmetrical
+  #     key algoruthms
+  #   * :pkey [String, File, OpenSSL::PKey::PKey] -- may be a String or 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.
+  #   * :algorithm [String] -- Sets default used for encoding. May be HS256,
+  #     HS384, HS512, RS256, RS384, RS512, or none.
+  #   * :verify [String] -- Verifies signatures when decoding tokens. Defaults
+  #     to +true+.
+  #   * :accept_algorithms [String, Array<String>] -- An Array or space separated
+  #     string of values which list what algorthms are accepted for token
+  #     signatures. Defaults to all possible values of :algorithm except 'none'.
+  # @note the TokenCoder instance must be configured with the appropriate
+  #   key material to support particular algorithm families and operations
+  #   -- i.e. :pkey must include a private key in order to sign tokens with
+  #   the RS algorithms.
+  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.
+  # Returns a signed token in JWT format (header, body, signature).
+  # @param token_body (see TokenCoder.encode)
+  # @param [String] algorithm -- overrides default. See {#initialize} for possible values.
+  # @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
+  # 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
+      raise InvalidTokenFormat, "invalid authentication header: #{auth_header}"
+    end
+    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 InvalidAudience, "invalid audience: #{auds}"
+    end
+    exp = reply[:exp] || reply['exp']
+    unless exp.is_a?(Integer) && exp > Time.now.to_i
+      raise TokenExpired, "token expired"
+    end
+    reply
+  end
+
+end
+
+end

data/lib/uaa/token_issuer.rb

@@ -0,0 +1,255 @@
+#--
+# Cloud Foundry 2012.02.03 Beta
+# Copyright (c) [2009-2012] VMware, Inc. All Rights Reserved.
+#
+# This product is licensed to you under the Apache License, Version 2.0 (the "License").
+# You may not use this product except in compliance with the License.
+#
+# This product includes a number of subcomponents with
+# separate copyright notices and license terms. Your use of these
+# subcomponents is subject to the terms and conditions of the
+# subcomponent's license, as noted in the LICENSE file.
+#++
+
+require 'securerandom'
+require 'uaa/http'
+
+module CF::UAA
+
+# 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 {TokenInfo#info} for contents.
+class TokenInfo
+
+  # 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
+
+  # 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
+
+end
+
+# Client Apps that want to get access to resource servers on behalf of their
+# users need to get tokens via authcode and implicit flows,
+# request scopes, etc., but they don't need to process tokens. This
+# 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}
+class TokenIssuer
+
+  include Http
+
+  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' => FORM_UTF8, 'accept' => JSON_UTF8,
+        '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 = 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}.
+  # @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[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.
+  # @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 = random_state)
+
+    # the accept header is only here so the uaa will issue error replies in json to aid debugging
+    headers = {'content-type' => FORM_UTF8, 'accept' => JSON_UTF8 }
+    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'])
+    fragment, reply_uri.fragment = reply_uri.fragment, nil
+    raise BadResponse, "bad location header" unless req_uri == reply_uri
+    parse_implicit_params(fragment, state)
+  rescue URI::Error => e
+    raise BadResponse, "bad location header in reply: #{e.message}"
+  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.
+  # @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.
+  # @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(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'])
+  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 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' => FORM_UTF8, 'accept' => JSON_UTF8,
+        'authorization' => Http.basic_auth(@client_id, @client_secret) }
+    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,
+        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.
+  # @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.
+  # @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(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(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'])
+  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}.
+  # @return [TokenInfo]
+  def owner_password_grant(username, password, scope = nil)
+    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
+  # @return [TokenInfo]
+  def client_credentials_grant(scope = nil)
+    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
+  # @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
+
+end
+
+end

data/lib/uaa/util.rb

@@ -0,0 +1,235 @@
+#--
+# Cloud Foundry 2012.02.03 Beta
+# Copyright (c) [2009-2012] VMware, Inc. All Rights Reserved.
+#
+# This product is licensed to you under the Apache License, Version 2.0 (the "License").
+# You may not use this product except in compliance with the License.
+#
+# This product includes a number of subcomponents with
+# separate copyright notices and license terms. Your use of these
+# subcomponents is subject to the terms and conditions of the
+# subcomponent's license, as noted in the LICENSE file.
+#++
+
+require 'multi_json'
+require "base64"
+require 'logger'
+require 'uri'
+
+# Cloud Foundry namespace
+module CF
+  # Namespace for User Account and Authentication service
+  module UAA end
+end
+
+class Logger # @private
+  Severity::TRACE = Severity::DEBUG - 1
+  def trace(progname, &blk); add(Logger::Severity::TRACE, nil, progname, &blk) end
+  def trace? ; @level <= Logger::Severity::TRACE end
+end
+
+module CF::UAA
+
+# Useful parent class. All CF::UAA exceptions are derived from this.
+class UAAError < RuntimeError; end
+
+# Indicates an authentication error.
+class AuthError < UAAError; end
+
+# Indicates an error occurred decoding a token, base64 decoding, or JSON.
+class DecodeError < UAAError; end
+
+# Helper functions useful to the UAA client APIs
+class Util
+
+  # General method to transform a hash key to a given style. Useful when
+  # dealing with HTTP headers and various protocol tags that tend to contain
+  # '-' characters and are case-insensitive and want to use them as keys in
+  # ruby hashes. Useful for dealing with {http://www.simplecloud.info/ SCIM}
+  # case-insensitive attribute names to normalize all attribute names (downcase).
+  #
+  # @param [String, Symbol] key current key
+  # @param [Symbol] style can be sym, downsym, down, str, [un]dash, [un]camel, nil, none
+  # @return [String, Symbol] new key
+  def self.hash_key(key, style)
+    case style
+    when nil, :none then key
+    when :downsym then key.to_s.downcase.to_sym
+    when :sym then key.to_sym
+    when :str then key.to_s
+    when :down then key.to_s.downcase
+    when :dash then key.to_s.downcase.tr('_', '-')
+    when :undash then key.to_s.downcase.tr('-', '_').to_sym
+    when :uncamel then key.to_s.gsub(/([A-Z])([^A-Z]*)/,'_\1\2').downcase.to_sym
+    when :camel then key.to_s.gsub(/(_[a-z])([^_]*)/) { $1[1].upcase + $2 }
+    else raise ArgumentError, "unknown hash key style: #{style}"
+    end
+  end
+
+  # Modifies obj in place changing any hash keys to style. Recursively modifies
+  # subordinate hashes.
+  # @param style (see Util.hash_key)
+  # @return modified obj
+  def self.hash_keys!(obj, style = nil)
+    return obj if style == :none
+    return obj.each {|o| hash_keys!(o, style)} if obj.is_a? Array
+    return obj unless obj.is_a? Hash
+    newkeys, nk = {}, nil
+    obj.delete_if { |k, v|
+      hash_keys!(v, style)
+      newkeys[nk] = v unless (nk = hash_key(k, style)) == k
+      nk != k
+    }
+    obj.merge!(newkeys)
+  end
+
+  # Makes a new copy of obj with hash keys to style. Recursively modifies
+  # subordinate hashes.
+  # @param style (see Util.hash_key)
+  # @return obj or new object if hash keys were changed
+  def self.hash_keys(obj, style = nil)
+    return obj.collect {|o| hash_keys(o, style)} if obj.is_a? Array
+    return obj unless obj.is_a? Hash
+    obj.each_with_object({}) {|(k, v), h|
+      h[hash_key(k, style)] = hash_keys(v, style)
+    }
+  end
+
+  # handle ruby 1.8.7 compatibility for form encoding
+  if URI.respond_to?(:encode_www_form_component)
+    def self.encode_component(str) URI.encode_www_form_component(str) end #@private
+    def self.decode_component(str) URI.decode_www_form_component(str) end #@private
+  else
+    def self.encode_component(str) # @private
+      str.to_s.gsub(/([^ a-zA-Z0-9*_.-]+)/) {
+        '%' + $1.unpack('H2' * $1.size).join('%').upcase
+      }.tr(' ', '+')
+    end
+    def self.decode_component(str) # @private
+      str.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/) {[$1.delete('%')].pack('H*')}
+    end
+  end
+
+  # Takes an x-www-form-urlencoded string and returns a hash of utf-8 key/value
+  # pairs. Useful for OAuth parameters. Raises ArgumentError if a key occurs
+  # more than once, which is a restriction of OAuth query strings.
+  # OAuth parameters are case sensitive, scim parameters are case-insensitive.
+  # @see http://tools.ietf.org/html/rfc6749#section-3.1
+  # @param [String] url_encoded_pairs in an x-www-form-urlencoded string
+  # @param style (see Util.hash_key)
+  # @return [Hash] of key value pairs
+  def self.decode_form(url_encoded_pairs, style = nil)
+    pairs = {}
+    url_encoded_pairs.split(/[&;]/).each do |pair|
+      k, v = pair.split('=', 2).collect { |v| decode_component(v) }
+      raise "duplicate keys in form parameters" if pairs.key?(k = hash_key(k, style))
+      pairs[k] = v
+    end
+    pairs
+  rescue Exception => e
+    raise ArgumentError, e.message
+  end
+
+  # Encode an object into x-www-form-urlencoded string suitable for oauth2.
+  # @note that ruby 1.9.3 converts form components to utf-8. Ruby 1.8.7
+  #   users must ensure all data is in utf-8 format before passing to form encode.
+  # @param [Hash] obj a hash of key/value pairs to be encoded.
+  # @see http://tools.ietf.org/html/rfc6749#section-3.1
+  def self.encode_form(obj)
+    obj.map {|k, v| encode_component(k) << '=' << encode_component(v)}.join('&')
+  end
+
+  # Converts +obj+ to JSON
+  # @return [String] obj in JSON form.
+  def self.json(obj) MultiJson.dump(obj) end
+
+  # Converts +obj+ to nicely formatted JSON
+  # @return [String] obj in formatted json
+  def self.json_pretty(obj) MultiJson.dump(obj, :pretty => true) end
+
+  # Converts +obj+ to a URL-safe base 64 encoded string
+  # @return [String]
+  def self.json_encode64(obj = {}) encode64(json(obj)) end
+
+  # Decodes base64 encoding of JSON data.
+  # @param [String] str
+  # @param style (see Util.hash_key)
+  # @return [Hash]
+  def self.json_decode64(str, style = nil) json_parse(decode64(str), style) end
+
+  # Encodes +obj+ as a URL-safe base 64 encoded string, with trailing padding removed.
+  # @return [String]
+  def self.encode64(obj)
+    str = Base64.respond_to?(:urlsafe_encode64)? Base64.urlsafe_encode64(obj):
+        [obj].pack("m").tr("+/", "-_")
+    str.gsub!(/(\n|=*$)/, '')
+    str
+  end
+
+  # Decodes a URL-safe base 64 encoded string. Adds padding if necessary.
+  # @return [String] decoded string
+  def self.decode64(str)
+    return unless str
+    pad = str.length % 4
+    str = str + '=' * (4 - pad) if pad > 0
+    Base64.respond_to?(:urlsafe_decode64) ?
+        Base64.urlsafe_decode64(str) : Base64.decode64(str.tr('-_', '+/'))
+  rescue ArgumentError
+    raise DecodeError, "invalid base64 encoding"
+  end
+
+  # Parses a JSON string.
+  # @param style (see Util.hash_key)
+  # @return [Hash] parsed data
+  def self.json_parse(str, style = nil)
+    hash_keys!(MultiJson.load(str), style) if str && !str.empty?
+  rescue MultiJson::DecodeError
+    raise DecodeError, "json decoding error"
+  end
+
+  # Converts obj to a string and truncates if over limit.
+  # @return [String]
+  def self.truncate(obj, limit = 50)
+    return obj.to_s if limit == 0
+    limit = limit < 5 ? 1 : limit - 4
+    str = obj.to_s[0..limit]
+    str.length > limit ? str + '...': str
+  end
+
+  # Converts common input formats into array of strings.
+  # Many parameters in these classes can be given as arrays, or as a list of
+  # arguments separated by spaces or commas. This method handles the possible
+  # inputs and returns an array of strings.
+  # @return [Array<String>]
+  def self.arglist(arg, default_arg = nil)
+    arg = default_arg unless arg
+    return arg if arg.nil? || arg.respond_to?(:join)
+    raise ArgumentError, "arg must be Array or space|comma delimited strings" unless arg.respond_to?(:split)
+    arg.split(/[\s\,]+/).reject { |e| e.empty? }
+  end
+
+  # Joins arrays of strings into a single string. Reverse of {Util.arglist}.
+  # @param [Object, #join] arg
+  # @param [String] delim delimiter to put between strings.
+  # @return [String]
+  def self.strlist(arg, delim = ' ')
+    arg.respond_to?(:join) ? arg.join(delim) : arg.to_s if arg
+  end
+
+  # Set the default logger used by the higher level classes.
+  # @param [String, Symbol] level such as info, debug trace.
+  # @param [IO] sink output for log messages, defaults to $stdout
+  # @return [Logger]
+  def self.default_logger(level = nil, sink = nil)
+    if sink || !@default_logger
+      @default_logger = Logger.new(sink || $stdout)
+      level = :info unless level
+      @default_logger.formatter = Proc.new { |severity, time, pname, msg| puts msg }
+    end
+    @default_logger.level = Logger::Severity.const_get(level.to_s.upcase) if level
+    @default_logger
+  end
+
+end
+
+end