cf-uaa-lib 1.3.1 → 1.3.2

data/NOTICE.TXT

@@ -0,0 +1,10 @@
+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. 

data/README.md

@@ -2,6 +2,8 @@
 
 Client gem for interacting with the [CloudFoundry UAA server](https://github.com/cloudfoundry/uaa)
 
+For documentation see: https://rubygems.org/gems/cf-uaa-lib
+
 ## Install from rubygems
 
     $ gem install cf-uaa-lib
@@ -17,7 +19,7 @@ Client gem for interacting with the [CloudFoundry UAA server](https://github.com
     #!/usr/bin/env ruby
     require 'uaa'
     token_issuer = CF::UAA::TokenIssuer.new("https://uaa.cloudfoundry.com", "vmc")
-    puts token\_issuer.prompts.inspect
+    puts token_issuer.prompts.inspect
     token = token_issuer.implicit_grant_with_creds(username: "<your_username>", password: "<your_password>")
     token_info = TokenCoder.decode(token.info["access_token"], nil, nil, false) #token signature not verified
     puts token_info["user_name"]

data/Rakefile

@@ -10,10 +10,10 @@
 # subcomponent's license, as noted in the LICENSE file.
 #
 
-require "rdoc/task"
 require "rspec/core/rake_task"
 require "bundler/gem_tasks" # only available in bundler >= 1.0.15
 require "ci/reporter/rake/rspec"
+require "yard"
 
 ENV['CI_REPORTS'] = File.expand_path("spec_reports")
 COV_REPORTS = File.expand_path("coverage")
@@ -22,16 +22,17 @@ task :default => [:test]
 task :tests => [:test]
 task :spec => [:test]
 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'LICENSE.TXT', 'NOTICE.TXT']
+  t.options = ['--main', 'README.md', '--no-private',
+              '--title', 'Cloud Foundry UAA Client API']
+end
+
 RSpec::Core::RakeTask.new("test") do |t|
   t.rspec_opts = ["--format", "documentation", "--colour"]
   t.pattern = "spec/**/*_spec.rb"
 end
 
-RDoc::Task.new do |rd|
-  rd.rdoc_files.include("lib/**/*.rb")
-  rd.rdoc_dir = "doc"
-end
-
 task :ci => [:pre_coverage, :rcov_reports, "ci:setup:rspec", :test]
 task :cov => [:pre_coverage, :test, :view_coverage]
 task :coverage => [:pre_coverage, :test]

data/cf-uaa-lib.gemspec

@@ -36,10 +36,12 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "bundler"
   s.add_development_dependency "rake"
-  s.add_development_dependency "rdoc"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "redcarpet"
   s.add_development_dependency "rspec"
   s.add_development_dependency "simplecov"
   s.add_development_dependency "simplecov-rcov"
   s.add_development_dependency "ci_reporter"
+  s.add_development_dependency "json_pure"
 
 end

data/lib/uaa/http.rb

@@ -17,19 +17,19 @@ require 'uaa/util'
 
 module CF::UAA
 
-# Indicates URL for the target is bad or not accessible
+# Indicates URL for the target is bad or not accessible.
 class BadTarget < UAAError; end
 
-# Error indicating the resource within the target server was not found
+# Indicates the resource within the target server was not found.
 class NotFound < UAAError; end
 
 # Indicates a syntax error in a response from the UAA, e.g. missing required response field.
 class BadResponse < UAAError; end
 
-# Indicates a token is malformed or expired
+# Indicates a token is malformed or expired.
 class InvalidToken < UAAError; end
 
-# Indicates an error from the http client stack
+# Indicates an error from the http client stack.
 class HTTPException < UAAError; end
 
 # An application level error from the UAA which includes error info in the reply.
@@ -43,46 +43,51 @@ end
 # Utility accessors and methods for objects that want to access JSON web APIs.
 module Http
 
-  # Sets the current logger instance to recieve error messages
+  # Sets the current logger instance to recieve error messages.
+  # @param [Logger] logr
+  # @return [Logger]
   def logger=(logr); @logger = logr end
 
-  # Returns the current logger or CF::UAA::Util.default_logger is none has been set.
-  def logger ; @logger ||= Util.default_logger end
+  # The current logger or {Util.default_logger} if none has been set.
+  # @return [Logger]
+  def logger ; @logger || Util.default_logger end
 
-  # Returns true if the current logger is set to +:trace+ level
-  def trace? ; @logger && @logger.respond_to?(:trace?) && @logger.trace? end
+  # Indicates if the current logger is set to +:trace+ level.
+  # @return [Boolean]
+  def trace? ; (lgr = logger).respond_to?(:trace?) && lgr.trace? end
 
-  # Sets handler for outgoing http requests. If not set, an internal cache of
-  # net/http connections is used.
-  # Arguments to handler are url, method, body, headers.
-  def set_request_handler(&blk) @req_handler = blk end
+  # Sets a handler for outgoing http requests. If no handler is set, an
+  # internal cache of net/http connections is used. Arguments to the handler
+  # are url, method, body, headers.
+  # @param [Proc] blk handler block
+  # @return [nil]
+  def set_request_handler(&blk) @req_handler = blk; nil end
 
-  # Returns a string for use in an http basic authentication header
+  # Constructs an http basic authentication header.
+  # @return [String]
   def self.basic_auth(name, password)
-    "Basic " + Base64::strict_encode64("#{name}:#{password}")
+    str = "#{name}:#{password}"
+    "Basic " + (Base64.respond_to?(:strict_encode64)?
+        Base64.strict_encode64(str): [str].pack("m").gsub(/\n/, ''))
   end
 
   private
 
-  def add_auth_json(auth, headers, jsonhdr = "content-type")
-    headers["authorization"] = auth if auth
-    headers.merge!(jsonhdr => "application/json")
+  def json_get(target, path = nil, style = nil, headers = {})
+    raise ArgumentError unless style.nil? || style.is_a?(Symbol)
+    json_parse_reply(style, *http_get(target, path, headers.merge("accept" => "application/json")))
   end
 
-  def json_get(target, path = nil, authorization = nil, key_style = :none, headers = {})
-    json_parse_reply(*http_get(target, path,
-        add_auth_json(authorization, headers, "accept")), key_style)
+  def json_post(target, path, body, headers = {})
+    http_post(target, path, Util.json(body), headers.merge("content-type" => "application/json"))
   end
 
-  def json_post(target, path, body, authorization, headers = {})
-    http_post(target, path, Util.json(body), add_auth_json(authorization, headers))
+  def json_put(target, path, body, headers = {})
+    http_put(target, path, Util.json(body), headers.merge("content-type" => "application/json"))
   end
 
-  def json_put(target, path, body, authorization = nil, headers = {})
-    http_put(target, path, Util.json(body), add_auth_json(authorization, headers))
-  end
-
-  def json_parse_reply(status, body, headers, key_style = :none)
+  def json_parse_reply(style, status, body, headers)
+    raise ArgumentError unless style.nil? || style.is_a?(Symbol)
     unless [200, 201, 204, 400, 401, 403].include? status
       raise (status == 404 ? NotFound : BadResponse), "invalid status response: #{status}"
     end
@@ -90,8 +95,8 @@ module Http
           headers["content-type"] !~ /application\/json/i)
       raise BadResponse, "received invalid response content or type"
     end
-    parsed_reply = Util.json_parse(body, key_style)
-    if status >= 400
+    parsed_reply = Util.json_parse(body, style)
+  if status >= 400
       raise parsed_reply && parsed_reply["error"] == "invalid_token" ?
           InvalidToken : TargetError.new(parsed_reply), "error response"
     end
@@ -131,8 +136,8 @@ module Http
   end
 
   def net_http_request(url, method, body, headers)
-    raise ArgumentError unless reqtype = {delete: Net::HTTP::Delete,
-        get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put}[method]
+    raise ArgumentError unless reqtype = {:delete => Net::HTTP::Delete,
+        :get => Net::HTTP::Get, :post => Net::HTTP::Post, :put => Net::HTTP::Put}[method]
     headers["content-length"] = body.length if body
     uri = URI.parse(url)
     req = reqtype.new(uri.request_uri)

data/lib/uaa/misc.rb

@@ -15,7 +15,7 @@ require 'uaa/http'
 
 module CF::UAA
 
-# interfaces to UAA endpoints that are not in the context
+# Provides interfaces to various UAA endpoints that are not in the context
 # of an overall class of operations like SCIM resources or OAuth2 tokens.
 class Misc
 
@@ -23,55 +23,84 @@ class Misc
     include Http
   end
 
-  # Returns a hash of information about the user authenticated by the token in
-  # the +auth_header+. It calls the +/userinfo+ endpoint and returns a hash of
-  # user information as specified by OpenID Connect.
-  # See: http://openid.net/connect/
-  # Specifically: http://openid.net/specs/openid-connect-standard-1_0.html#userinfo_ep
-  # and: http://openid.net/specs/openid-connect-messages-1_0.html#anchor9
-  def self.whoami(target, auth_header) 
-    json_get(target, "/userinfo?schema=openid", auth_header) 
+  # sets whether the keys in returned hashes should be symbols.
+  # @return [Boolean] the new state
+  def self.symbolize_keys=(bool) !!(@key_style = bool ? :sym : nil) end
+
+  # Gets information about the user authenticated by the token in the
+  # +auth_header+. It GETs from the +target+'s +/userinfo+ endpoint and
+  # returns user information as specified by OpenID Connect.
+  # @see http://openid.net/connect/
+  # @see http://openid.net/specs/openid-connect-standard-1_0.html#userinfo_ep
+  # @see http://openid.net/specs/openid-connect-messages-1_0.html#anchor9
+  # @param (see Misc.server)
+  # @param [String] auth_header see {TokenInfo#auth_header}
+  # @return [Hash]
+  def self.whoami(target, auth_header)
+    json_get(target, "/userinfo?schema=openid", @key_style, "authorization" => auth_header)
   end
 
-  # Returns a hash of various monitoring and status variables from the UAA.
-  # Authenticates to the UAA with basic authentication. Name and pwd 
-  # must be configured in the UAA.
-  def self.varz(target, name, pwd) 
-    json_get(target, "/varz", Http.basic_auth(name, pwd)) 
+  # Gets various monitoring and status variables from the server.
+  # Authenticates using +name+ and +pwd+ for basic authentication.
+  # @param (see Misc.server)
+  # @return [Hash]
+  def self.varz(target, name, pwd)
+    json_get(target, "/varz", @key_style, "authorization" => Http.basic_auth(name, pwd))
   end
 
-  # returns a hash of basic information about the target server, including
-  # version number, commit ID, and links to API endpoints.
+  # Gets basic information about the target server, including version number,
+  # commit ID, and links to API endpoints.
+  # @param [String] target The base URL of the server. For example the target could
+  #   be {https://login.cloudfoundry.com}, {https://uaa.cloudfoundry.com}, or
+  #   {http://localhost:8080/uaa}.
+  # @return [Hash]
   def self.server(target)
-    reply = json_get(target, '/login')
-    return reply if reply && reply["prompts"]
+    reply = json_get(target, '/login', @key_style)
+    return reply if reply && (reply[:prompts] || reply['prompts'])
     raise BadResponse, "Invalid response from target #{target}"
   end
 
+  # Gets the key from the server that is used to validate token signatures. If
+  # the server is configured to use a symetric key, the caller must authenticate
+  # by providing a a +client_id+ and +client_secret+. If the server
+  # is configured to sign with a private key, this call will retrieve the
+  # public key and +client_id+ must be nil.
+  # @param (see Misc.server)
+  # @return [Hash]
   def self.validation_key(target, client_id = nil, client_secret = nil)
-    json_get(target, "/token_key", (client_id && client_secret ? Http.basic_auth(client_id, client_secret) : nil))
+    hdrs = client_id && client_secret ?
+        { "authorization" => Http.basic_auth(client_id, client_secret)} : {}
+    json_get(target, "/token_key", @key_style, hdrs)
   end
 
-  # Sends the token to the UAA to validate. Returns hash of values that are 
-  # associated with the token. Authenticates with client_id and client_secret.
-  # If audience_ids are specified, raises AuthError token is not for this
-  # audience -- i.e. the token's 'aud' attribute does not contain one or more 
-  # of the specified audience_ids.
+  # Sends +token+ to the server to validate and decode. Authenticates with
+  # +client_id+ and +client_secret+. If +audience_ids+ are specified and the
+  # token's "aud" attribute does not contain one or more of the audience_ids,
+  # raises AuthError -- meaning the token is not for this audience.
+  # @param (see Misc.server)
+  # @param [String] token an access token as retrieved by {TokenIssuer}. See
+  #   also {TokenInfo}.
+  # @param [String] token_type as retrieved by {TokenIssuer}. See {TokenInfo}.
+  # @return [Hash] contents of the token
   def self.decode_token(target, client_id, client_secret, token, token_type = "bearer", audience_ids = nil)
     reply = json_get(target, "/check_token?token_type=#{token_type}&token=#{token}",
-        Http.basic_auth(client_id, client_secret))
-    auds = Util.arglist(reply["aud"])
+        @key_style, "authorization" => Http.basic_auth(client_id, client_secret))
+    auds = Util.arglist(reply[:aud] || reply['aud'])
     if audience_ids && (!auds || (auds & audience_ids).empty?)
       raise AuthError, "invalid audience: #{auds.join(' ')}"
     end
     reply
   end
 
-  # Returns a hash of information about the given password, including a
-  # strength score and an indication of what strength it required by the UAA.
+  # Gets information about the given password, including a strength score and
+  # an indication of what strength is required.
+  # @param (see Misc.server)
+  # @return [Hash]
   def self.password_strength(target, password)
-    json_parse_reply(*request(target, :post, '/password/score', URI.encode_www_form("password" => password),
-        "content-type" => "application/x-www-form-urlencoded", "accept" => "application/json"))
+    json_parse_reply(@key_style, *request(target, :post, '/password/score',
+        Util.encode_form(:password => password),
+        "content-type" => "application/x-www-form-urlencoded",
+        "accept" => "application/json"))
   end
 
 end

data/lib/uaa/scim.rb

@@ -19,7 +19,20 @@ module CF::UAA
 # Client Registrations. It provides access to the SCIM endpoints on the UAA.
 # For more information about SCIM -- the IETF's System for Cross-domain
 # Identity Management (formerly known as Simple Cloud Identity Management) --
-# see http://www.simplecloud.info
+# see {http://www.simplecloud.info}.
+#
+# The types of objects and links to their schema are as follows:
+# * +:user+ -- {http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#user-resource}
+#   or {http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#anchor8}
+# * +:group+ -- {http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#group-resource}
+#   or {http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#anchor10}
+# * +:client+
+# * +:user_id+ -- {https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#converting-userids-to-names}
+#
+# Naming attributes by type of object:
+# * +:user+ is "username"
+# * +:group+ is "displayname"
+# * +:client+ is "client_id"
 class Scim
 
   include Http
@@ -49,13 +62,15 @@ class Scim
   def force_case(obj)
     return obj.collect {|o| force_case(o)} if obj.is_a? Array
     return obj unless obj.is_a? Hash
-    obj.each_with_object({}) {|(k, v), h| h[force_attr(k)] = force_case(v) }
+    new_obj = {}
+    obj.each {|(k, v)| new_obj[force_attr(k)] = force_case(v) }
+    new_obj
   end
 
   # an attempt to hide some scim and uaa oddities
   def type_info(type, elem)
-    scimfo = {user: ["/Users", "userName"], group: ["/Groups", "displayName"],
-      client: ["/oauth/clients", 'client_id'], user_id: ["/ids/Users", 'userName']}
+    scimfo = {:user => ["/Users", "userName"], :group => ["/Groups", "displayName"],
+      :client => ["/oauth/clients", 'client_id'], :user_id => ["/ids/Users", 'userName']}
     unless elem == :path || elem == :name_attr
       raise ArgumentError, "scim schema element must be :path or :name_attr"
     end
@@ -65,174 +80,199 @@ class Scim
     ary[elem == :path ? 0 : 1]
   end
 
-  def prep_request(type, info = nil)
-    [type_info(type, :path), force_case(info)]
+  def jkey(k) @key_style == :down ? k.to_s : k end
+
+  def fake_client_id(info)
+    idk, ck = jkey(:id), jkey(:client_id)
+    info[idk] = info[ck] if info[ck] && !info[idk]
   end
 
   public
 
-  # The +auth_header+ parameter refers to a string that can be used in an
-  # authorization header. For OAuth2 with JWT tokens this would be something
-  # like "bearer xxxx.xxxx.xxxx". The Token class provides
-  # CF::UAA::Token#auth_header for this purpose.
-  def initialize(target, auth_header) @target, @auth_header = target, auth_header end
-
-  # creates a SCIM resource. For possible values for the +type+ parameter, and links
-  # to the schema of each type see #query
-  # info is a hash structure converted to json and sent to the scim endpoint
-  # A hash of the newly created object is returned, including its ID
-  # and meta data.
-  def add(type, info)
-    path, info = prep_request(type, info)
-    reply = json_parse_reply(*json_post(@target, path, info, @auth_header), :down)
-
-    # hide client endpoints that are not scim compatible
-    reply['id'] = reply['client_id'] if type == :client && reply['client_id'] && !reply['id']
+  # @param (see Misc.server)
+  # @param [String] auth_header a string that can be used in an
+  #   authorization header. For OAuth2 with JWT tokens this would be something
+  #   like "bearer xxxx.xxxx.xxxx". The {TokenInfo} class provides
+  #   {TokenInfo#auth_header} for this purpose.
+  # @param style (see Util.hash_key)
+  def initialize(target, auth_header, options = {})
+    @target, @auth_header = target, auth_header
+    @key_style = options[:symbolize_keys] ? :downsym : :down
+  end
 
-    return reply if reply && reply["id"]
-    raise BadResponse, "no id returned by add request to #{@target}#{path}"
+  # Creates a SCIM resource.
+  # @param [Symbol] type can be :user, :group, :client, :user_id.
+  # @param [Hash] info converted to json and sent to the scim endpoint. For schema of
+  #   each type of object see {Scim}.
+  # @return [Hash] contents of the object, including its +id+ and meta-data.
+  def add(type, info)
+    path, info = type_info(type, :path), force_case(info)
+    reply = json_parse_reply(@key_style, *json_post(@target, path, info,
+        "authorization" => @auth_header))
+    fake_client_id(reply) if type == :client # hide client reply, not quite scim
+    reply
   end
 
-  # Deletes a SCIM resource identified by +id+. For possible values for type, see #query
+  # Deletes a SCIM resource
+  # @param type (see #add)
+  # @param [String] id the id attribute of the SCIM object
+  # @return [nil]
   def delete(type, id)
-    path, _ = prep_request(type)
-    http_delete @target, "#{path}/#{URI.encode(id)}", @auth_header
+    http_delete @target, "#{type_info(type, :path)}/#{URI.encode(id)}", @auth_header
   end
 
-  # +info+ is a hash structure converted to json and sent to a scim endpoint
-  # For possible types, see #query
+  # Replaces the contents of a SCIM object.
+  # @param (see #add)
+  # @return (see #add)
   def put(type, info)
-    path, info = prep_request(type, info)
+    path, info = type_info(type, :path), force_case(info)
     ida = type == :client ? 'client_id' : 'id'
-    raise ArgumentError, "scim info must include #{ida}" unless id = info[ida]
-    hdrs = info && info["meta"] && info["meta"]["version"] ?
-        {'if-match' => info["meta"]["version"]} : {}
-    reply = json_parse_reply(*json_put(@target, "#{path}/#{URI.encode(id)}",
-        info, @auth_header, hdrs), :down)
+    raise ArgumentError, "info must include #{ida}" unless id = info[ida]
+    hdrs = {'authorization' => @auth_header}
+    if info && info['meta'] && (etag = info['meta']['version'])
+      hdrs.merge!('if-match' => etag)
+    end
+    reply = json_parse_reply(@key_style,
+        *json_put(@target, "#{path}/#{URI.encode(id)}", info, hdrs))
 
-    # hide client endpoints that are not scim compatible
-    type == :client && !reply ? get(type, info["client_id"]): reply
+    # hide client endpoints that are not quite scim compatible
+    type == :client && !reply ? get(type, info['client_id']): reply
   end
 
-  # Queries for objects and returns a selected list of attributes for each
-  # a given filter. Possible values for +type+ and links to the schema of
-  # corresponding object type are:
-  # +:user+::   http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#user-resource
-  # ::          http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#anchor8
-  # +:group+::  http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#group-resource
-  # ::          http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#anchor10
-  # +:client+::
-  # +:user_id+:: https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#converting-userids-to-names
-  #
-  # The +query+ hash may contain the following keys:
-  # attributes:: a comma or space separated list of attribute names to be
-  #              returned for each object that matches the filter. If no attribute
-  #              list is given, all attributes are returned.
-  # filter:: a filter to select which objects are returned. See
-  #          http://www.simplecloud.info/specs/draft-scim-api-01.html#query-resources
-  # startIndex:: for paged output, start index of requested result set.
-  # count:: maximum number of results per reply
+  # Gets a set of attributes for each object that matches a given filter.
+  # @param (see #add)
+  # @param [Hash] query may contain the following keys:
+  #   * +attributes+: a comma or space separated list of attribute names to be
+  #     returned for each object that matches the filter. If no attribute
+  #     list is given, all attributes are returned.
+  #   * +filter+: a filter to select which objects are returned. See
+  #     {http://www.simplecloud.info/specs/draft-scim-api-01.html#query-resources}
+  #   * +startIndex+: for paged output, start index of requested result set.
+  #   * +count+: maximum number of results per reply
+  # @return [Hash] including a +resources+ array of results and
+  #   pagination data.
   def query(type, query = {})
-    path, query = prep_request(type, query)
-    query = query.reject {|k, v| v.nil? }
+    query = force_case(query).reject {|k, v| v.nil? }
     if attrs = query['attributes']
       attrs = Util.arglist(attrs).map {|a| force_attr(a)}
       query['attributes'] = Util.strlist(attrs, ",")
     end
-    qstr = query.empty?? '': "?#{URI.encode_www_form(query)}"
-    info = json_get(@target, "#{path}#{qstr}", @auth_header, :down)
-    unless info.is_a?(Hash) && info['resources'].is_a?(Array)
+    qstr = query.empty?? '': "?#{Util.encode_form(query)}"
+    info = json_get(@target, "#{type_info(type, :path)}#{qstr}", @key_style, 'authorization' => @auth_header)
+    unless info.is_a?(Hash) && info[rk = jkey(:resources)].is_a?(Array)
 
       # hide client endpoints that are not scim compatible
-      return {'resources' => info.values } if type == :client && info.is_a?(Hash)
+      if type == :client && info.is_a?(Hash)
+        info.each { |k, v| fake_client_id(v) }
+        return {rk => info.values }
+      end
 
-      raise BadResponse, "invalid reply to query of #{@target}#{path}"
+      raise BadResponse, "invalid reply to #{type} query of #{@target}"
     end
     info
   end
 
-  # Returns a hash of information about a specific object.
-  # [type] For possible values of type, see #add
-  # [id] the id attribute of the object assigned by the UAA
+  # Get information about a specific object.
+  # @param (see #delete)
+  # @return (see #add)
   def get(type, id)
-    path, _ = prep_request(type)
-    info = json_get(@target, "#{path}/#{URI.encode(id)}", @auth_header, :down)
+    info = json_get(@target, "#{type_info(type, :path)}/#{URI.encode(id)}",
+        @key_style, 'authorization' => @auth_header)
 
-    # hide client endpoints that are not scim compatible
-    info["id"] = info["client_id"] if type == :client && !info["id"]
+    fake_client_id(info) if type == :client # hide client reply, not quite scim
     info
   end
 
-  # Collects all pages of entries from a query, returns array of results.
-  # For descriptions of the +type+ and +query+ parameters, see #query.
+  # Collects all pages of entries from a query
+  # @param type (see #query)
+  # @param [Hash] query may contain the following keys:
+  #   * +attributes+: a comma or space separated list of attribute names to be
+  #     returned for each object that matches the filter. If no attribute
+  #     list is given, all attributes are returned.
+  #   * +filter+: a filter to select which objects are returned. See
+  #     {http://www.simplecloud.info/specs/draft-scim-api-01.html#query-resources}
+  # @return [Array] results
   def all_pages(type, query = {})
-    query = query.reject {|k, v| v.nil? }
-    query["startindex"], info = 1, []
+    query = force_case(query).reject {|k, v| v.nil? }
+    query["startindex"], info, rk = 1, [], jkey(:resources)
     while true
       qinfo = query(type, query)
-      raise BadResponse unless qinfo["resources"]
-      return info if qinfo["resources"].empty?
-      info.concat(qinfo["resources"])
-      return info unless qinfo["totalresults"] && qinfo["totalresults"] > info.length
-      unless qinfo["startindex"] && qinfo["itemsperpage"]
-        raise BadResponse, "incomplete pagination data from #{@target}#{path}"
+      raise BadResponse unless qinfo[rk]
+      return info if qinfo[rk].empty?
+      info.concat(qinfo[rk])
+      total = qinfo[jkey :totalresults]
+      return info unless total && total > info.length
+      unless qinfo[jkey :startindex] && qinfo[jkey :itemsperpage]
+        raise BadResponse, "incomplete #{type} pagination data from #{@target}"
       end
       query["startindex"] = info.length + 1
     end
   end
 
-  # Queries for objects by name. Returns array of name/id hashes for each
-  # name found. For possible values of +type+, see #query
+  # Gets id/name pairs for given names.
+  # @param type (see #add)
+  # @param [Array<String>] names. For naming attribute of each object type see {Scim}
+  # @return [Array] array of name/id hashes for each object found
   def ids(type, *names)
     na = type_info(type, :name_attr)
-    filter = names.each_with_object([]) { |n, o| o << "#{na} eq \"#{n}\""}
-    all_pages(type, attributes: "id,#{na}", filter: filter.join(" or "))
+    filter = names.map { |n| "#{na} eq \"#{n}\""}
+    all_pages(type, :attributes => "id,#{na}", :filter => filter.join(" or "))
   end
 
-  # Convenience method to query for single object by name. Returns its id.
-  # Raises error if not found. For possible values of +type+, see #query
+  # Convenience method to query for single object by name.
+  # @param type (see #add)
+  # @param [String] name Value of the Scim object's name attribue. For naming
+  #   attribute of each type of object see {Scim}.
+  # @return [String] the +id+ attribute of the object
   def id(type, name)
     res = ids(type, name)
 
     # hide client endpoints that are not scim compatible
-    if type == :client && res && res.length > 0
-      if res.length > 1 || res[0]["id"].nil?
-        cr = res.find { |o| o['client_id'] && name.casecmp(o['client_id']) == 0 }
-        return cr['id'] || cr['client_id'] if cr
-      end
+    ik, ck = jkey(:id), jkey(:client_id)
+    if type == :client && res && res.length > 0 && (res.length > 1 || res[0][ik].nil?)
+      cr = res.find { |o| o[ck] && name.casecmp(o[ck]) == 0 }
+      return cr[ik] || cr[ck] if cr
     end
 
     unless res && res.is_a?(Array) && res.length == 1 &&
-        res[0].is_a?(Hash) && (id = res[0]["id"])
+        res[0].is_a?(Hash) && (id = res[0][jkey :id])
       raise NotFound, "#{name} not found in #{@target}#{type_info(type, :path)}"
     end
     id
   end
 
-  # [For a user to change their own password] Token must contain "password.write" scope and the
-  #                                           correct +old_password+ must be given.
-  # [For an admin to set a user's password] Token must contain "uaa.admin" scope.
-  #
-  # For more information see:
-  # https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#change-password-put-useridpassword
-  # or https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-Security.md#password-change
+  # Change password.
+  # * For a user to change their own password, the token in @auth_header must
+  #   contain "password.write" scope and the correct +old_password+ must be given.
+  # * For an admin to set a user's password, the token in @auth_header must
+  #   contain "uaa.admin" scope.
+  # @see https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#change-password-put-useridpassword
+  # @see https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-Security.md#password-change
+  # @param [String] user_id the {Scim} +id+ attribute of the user
+  # @return [Hash] success message from server
   def change_password(user_id, new_password, old_password = nil)
-    password_request = {"password" => new_password}
-    password_request["oldPassword"] = old_password if old_password
-    json_parse_reply(*json_put(@target, "/Users/#{URI.encode(user_id)}/password", password_request, @auth_header))
+    req = {"password" => new_password}
+    req["oldPassword"] = old_password if old_password
+    json_parse_reply(@key_style, *json_put(@target,
+        "#{type_info(:user, :path)}/#{URI.encode(user_id)}/password", req,
+        'authorization' => @auth_header))
   end
 
-  # [For a client to change its own secret] Token must contain "uaa.admin,client.secret" scope and the
-  #                                         correct +old_secret+ must be given.
-  # [For an admin to set a client secret] Token must contain "uaa.admin" scope.
-  #
-  # For more information see:
-  # https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#change-client-secret-put-oauthclientsclient_idsecret
-  # or https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-Security.md#client-secret-mangagement
+  # Change client secret.
+  # * For a client to change its own secret, the token in @auth_header must contain
+  #   "uaa.admin,client.secret" scope and the correct +old_secret+ must be given.
+  # * For an admin to set a client secret, the token in @auth_header must contain
+  #   "uaa.admin" scope.
+  # @see https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-APIs.rst#change-client-secret-put-oauthclientsclient_idsecret
+  # @see https://github.com/cloudfoundry/uaa/blob/master/docs/UAA-Security.md#client-secret-mangagement
+  # @param [String] client_id the {Scim} +id+ attribute of the client
+  # @return [Hash] success message from server
   def change_secret(client_id, new_secret, old_secret = nil)
     req = {"secret" => new_secret }
     req["oldSecret"] = old_secret if old_secret
-    json_parse_reply(*json_put(@target, "/oauth/clients/#{URI.encode(client_id)}/secret", req, @auth_header))
+    json_parse_reply(@key_style, *json_put(@target,
+        "#{type_info(:client, :path)}/#{URI.encode(client_id)}/secret", req,
+        'authorization' => @auth_header))
   end
 
 end