cf-uaa-lib 1.3.0 → 1.3.1

data/README.md

@@ -1,43 +1,34 @@
 # CloudFoundry UAA Gem
 
-Client gem for interacting with the CloudFoundry UAA server.
+Client gem for interacting with the [CloudFoundry UAA server](https://github.com/cloudfoundry/uaa)
 
-Set up a local ruby environment (so sudo not required):
+## Install from rubygems
 
-  `$ rvm use 1.9.2`
+    $ gem install cf-uaa-lib
 
-or
+## Build from source
 
-  `$ rbenv global 1.9.2-p180`
+    $ bundle install
+    $ gem build cf-uaa-lib.gemspec
+    $ gem install cf-uaa-lib<version>.gem
 
-see: https://rvm.io/ or http://rbenv.org/
+## Use the gem
 
-Build the gem
-
-  `$ bundle install`
-  `$ gem build cf-uaa-lib.gemspec`
-
-Install it
-
-  `$ gem install cf-uaa-lib<version>.gem`
-
-Use the gem:
-
-  `#!/usr/bin/env ruby`
-  `require 'uaa'`
-  `token_issuer = CF::UAA::TokenIssuer.new("https://uaa.cloudfoundry.com", "vmc")`
-  `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"]`
+    #!/usr/bin/env ruby
+    require 'uaa'
+    token_issuer = CF::UAA::TokenIssuer.new("https://uaa.cloudfoundry.com", "vmc")
+    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"]
 
 ## Tests
 
 Run the tests with rake:
 
-  `$ bundle exec rake test`
+    $ bundle exec rake test
 
 Run the tests and see a fancy coverage report:
 
-  `$ bundle exec rake cov`
+    $ bundle exec rake cov
 

data/lib/uaa/http.rb

@@ -17,11 +17,22 @@ require 'uaa/util'
 
 module CF::UAA
 
+# 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
 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
 class InvalidToken < UAAError; end
+
+# 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.
 class TargetError < UAAError
   attr_reader :info
   def initialize(error_info = {})
@@ -32,24 +43,34 @@ 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
   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
+
+  # Returns true if the current logger is set to +:trace+ level
   def trace? ; @logger && @logger.respond_to?(:trace?) && @logger.trace? end
 
-  # sets handler for outgoing http requests. If not set, net/http is used. :yields: url, method, body, headers
+  # 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
 
+  # Returns a string for use in an http basic authentication header
   def self.basic_auth(name, password)
     "Basic " + Base64::strict_encode64("#{name}:#{password}")
   end
 
-  def add_auth_json(auth, headers, jsonhdr = "content-type") # :nodoc:
+  private
+
+  def add_auth_json(auth, headers, jsonhdr = "content-type")
     headers["authorization"] = auth if auth
     headers.merge!(jsonhdr => "application/json")
   end
 
   def json_get(target, path = nil, authorization = nil, key_style = :none, headers = {})
-    json_parse_reply(*http_get(target, path, 
+    json_parse_reply(*http_get(target, path,
         add_auth_json(authorization, headers, "accept")), key_style)
   end
 
@@ -61,15 +82,11 @@ module Http
     http_put(target, path, Util.json(body), add_auth_json(authorization, headers))
   end
 
-  def json_patch(target, path, body, authorization = nil, headers = {})
-    http_patch(target, path, Util.json(body), add_auth_json(authorization, headers))
-  end
-
   def json_parse_reply(status, body, headers, key_style = :none)
     unless [200, 201, 204, 400, 401, 403].include? status
       raise (status == 404 ? NotFound : BadResponse), "invalid status response: #{status}"
     end
-    if body && !body.empty? && (status == 204 || headers.nil? || 
+    if body && !body.empty? && (status == 204 || headers.nil? ||
           headers["content-type"] !~ /application\/json/i)
       raise BadResponse, "received invalid response content or type"
     end
@@ -86,7 +103,6 @@ module Http
   def http_get(target, path = nil, headers = {}) request(target, :get, path, nil, headers) end
   def http_post(target, path, body, headers = {}) request(target, :post, path, body, headers) end
   def http_put(target, path, body, headers = {}) request(target, :put, path, body, headers) end
-  def http_patch(target, path, body, headers = {}) request(target, :patch, path, body, headers) end
 
   def http_delete(target, path, authorization)
     status = request(target, :delete, path, nil, "authorization" => authorization)[0]
@@ -95,15 +111,13 @@ module Http
     end
   end
 
-  private
-
   def request(target, method, path, body = nil, headers = {})
     headers["accept"] = headers["content-type"] if headers["content-type"] && !headers["accept"]
     url = "#{target}#{path}"
 
     logger.debug { "--->\nrequest: #{method} #{url}\n" +
         "headers: #{headers}\n#{'body: ' + Util.truncate(body.to_s, trace? ? 50000 : 50) if body}" }
-    status, body, headers = @req_handler ? @req_handler.call(url, method, body, headers) : 
+    status, body, headers = @req_handler ? @req_handler.call(url, method, body, headers) :
         net_http_request(url, method, body, headers)
     logger.debug { "<---\nresponse: #{status}\nheaders: #{headers}\n" +
         "#{'body: ' + Util.truncate(body.to_s, trace? ? 50000: 50) if body}" }
@@ -117,7 +131,7 @@ module Http
   end
 
   def net_http_request(url, method, body, headers)
-    raise ArgumentError unless reqtype = {delete: Net::HTTP::Delete, 
+    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)

data/lib/uaa/misc.rb

@@ -11,30 +11,37 @@
 # subcomponent's license, as noted in the LICENSE file.
 #++
 
-# This class is for Web Client Apps (in the OAuth2 sense) that want
-# access to authenticated user information.  Basically this class is
-# an OpenID Connect client.
-
 require 'uaa/http'
 
 module CF::UAA
 
-# everything is miscellaneous
-#
-# this class provides interfaces to UAA endpoints that are not in the context
-# of an overall class of operations, like "user accounts" or "tokens". It's
-# also for some apis like "change user password" or "change client secret" that
-# use different forms of authentication than other operations on those types
-# of resources.
+# interfaces to UAA endpoints that are not in the context
+# of an overall class of operations like SCIM resources or OAuth2 tokens.
 class Misc
 
   class << self
     include Http
   end
 
-  def self.whoami(target, auth_header) json_get(target, "/userinfo?schema=openid", auth_header) end
-  def self.varz(target, name, pwd) json_get(target, "/varz", Http.basic_auth(name, pwd)) 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) 
+  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)) 
+  end
 
+  # returns a hash of basic information about the target server, including
+  # version number, commit ID, and links to API endpoints.
   def self.server(target)
     reply = json_get(target, '/login')
     return reply if reply && reply["prompts"]
@@ -45,8 +52,11 @@ class Misc
     json_get(target, "/token_key", (client_id && client_secret ? Http.basic_auth(client_id, client_secret) : nil))
   end
 
-  # Returns hash of values from the Authorization Server that are associated
-  # with the opaque token.
+  # 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.
   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))
@@ -57,6 +67,8 @@ class Misc
     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.
   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"))

data/lib/uaa/scim.rb

@@ -15,8 +15,11 @@ require 'uaa/http'
 
 module CF::UAA
 
-# This class is for apps that need to manage User Accounts, Groups, or OAuth Client Registrations.
-# It provides access to the SCIM endpoints on the UAA.
+# This class is for apps that need to manage User Accounts, Groups, or OAuth
+# 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
 class Scim
 
   include Http
@@ -25,9 +28,9 @@ class Scim
 
   def force_attr(k)
     kd = k.to_s.downcase
-    kc = {"username" => "userName", "familyname" => "familyName", 
-      "givenname" => "givenName", "middlename" => "middleName", 
-      "honorificprefix" => "honorificPrefix", 
+    kc = {"username" => "userName", "familyname" => "familyName",
+      "givenname" => "givenName", "middlename" => "middleName",
+      "honorificprefix" => "honorificPrefix",
       "honorificsuffix" => "honorificSuffix", "displayname" => "displayName",
       "nickname" => "nickName", "profileurl" => "profileUrl",
       "streetaddress" => "streetAddress", "postalcode" => "postalCode",
@@ -62,19 +65,23 @@ class Scim
     ary[elem == :path ? 0 : 1]
   end
 
-  def prep_request(type, info = nil) 
-    [type_info(type, :path), force_case(info)] 
+  def prep_request(type, info = nil)
+    [type_info(type, :path), force_case(info)]
   end
 
   public
 
-  # the auth_header parameter refers to a string that can be used in an
-  # authorization header. For oauth with jwt tokens this would be something
-  # like "bearer xxxx.xxxx.xxxx". The Token class returned by TokenIssuer
-  # provides an auth_header method for this purpose.
+  # 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
 
-  # info is a hash structure converted to json and sent to the scim /Users endpoint
+  # 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)
@@ -86,34 +93,45 @@ class Scim
     raise BadResponse, "no id returned by add request to #{@target}#{path}"
   end
 
-  def delete(type, id) 
+  # Deletes a SCIM resource identified by +id+. For possible values for type, see #query
+  def delete(type, id)
     path, _ = prep_request(type)
     http_delete @target, "#{path}/#{URI.encode(id)}", @auth_header
   end
 
-    # info is a hash structure converted to json and sent to the scim /Users endpoint
+  # +info+ is a hash structure converted to json and sent to a scim endpoint
+  # For possible types, see #query
   def put(type, info)
     path, info = prep_request(type, 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"] ? 
+    hdrs = info && info["meta"] && info["meta"]["version"] ?
         {'if-match' => info["meta"]["version"]} : {}
-    reply = json_parse_reply(*json_put(@target, "#{path}/#{URI.encode(id)}", 
+    reply = json_parse_reply(*json_put(@target, "#{path}/#{URI.encode(id)}",
         info, @auth_header, hdrs), :down)
 
     # hide client endpoints that are not scim compatible
     type == :client && !reply ? get(type, info["client_id"]): reply
   end
 
-  # TODO: fix this when the UAA supports patch
-  # info is a hash structure converted to json and sent to the scim /Users endpoint
-  #def patch(path, id, info, attributes_to_delete = nil)
-  #  info = info.merge(meta: { attributes: Util.arglist(attributes_to_delete) }) if attributes_to_delete
-  #  json_parse_reply(*json_patch(@target, "#{path}/#{URI.encode(id)}", info, @auth_header))
-  #end
-
-  # supported query keys are: attributes, filter, startIndex, count
-  # output hash keys are: resources, totalResults, itemsPerPage
+  # 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
   def query(type, query = {})
     path, query = prep_request(type, query)
     query = query.reject {|k, v| v.nil? }
@@ -133,7 +151,10 @@ class Scim
     info
   end
 
-  def get(type, id) 
+  # 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
+  def get(type, id)
     path, _ = prep_request(type)
     info = json_get(@target, "#{path}/#{URI.encode(id)}", @auth_header, :down)
 
@@ -143,7 +164,7 @@ class Scim
   end
 
   # Collects all pages of entries from a query, returns array of results.
-  # Type can be any scim resource type
+  # For descriptions of the +type+ and +query+ parameters, see #query.
   def all_pages(type, query = {})
     query = query.reject {|k, v| v.nil? }
     query["startindex"], info = 1, []
@@ -160,16 +181,16 @@ class Scim
     end
   end
 
-  # Queries for objects by name. returns array of name/id hashes for each
-  # name found.
+  # Queries for objects by name. Returns array of name/id hashes for each
+  # name found. For possible values of +type+, see #query
   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 "))
   end
 
-  # Convenience method to query for single object by name. 
-  # Returns its id. Raises error if not found.
+  # Convenience method to query for single object by name. Returns its id.
+  # Raises error if not found. For possible values of +type+, see #query
   def id(type, name)
     res = ids(type, name)
 
@@ -188,12 +209,26 @@ class Scim
     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
   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))
   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
   def change_secret(client_id, new_secret, old_secret = nil)
     req = {"secret" => new_secret }
     req["oldSecret"] = old_secret if old_secret

data/lib/uaa/token_coder.rb

@@ -19,20 +19,23 @@ module CF::UAA
 # 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 it for Resource Servers which accept Bearer JWT tokens.  An
-# instance of this class can be used to decode and verify the contents
-# of a bearer token.  The Authorization Server will have signed the
-# token and shared a secret key so that the Resource Server can verify
-# the signature.  The Authorization Server may also have given the
-# Resource Server an id, in which case it must verify a matching value
-# is in the access token.
+# 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) # :nodoc:
     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
+  # 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')
     segments = [Util.json_encode64("typ" => "JWT", "alg" => algo)]
     segments << Util.json_encode64(token_body)
@@ -49,6 +52,11 @@ 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
+  # 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)
     segments = token.split('.')
@@ -71,18 +79,17 @@ class TokenCoder
     payload
   end
 
-  # Create a new token en/decoder for a service that is associated with
+  # 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 and 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 - 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.
+  # +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)
@@ -100,9 +107,9 @@ class TokenCoder
   end
 
   # Returns hash of values decoded from the token contents. If the
-  # token contains resource ids and they do not contain the id of the
-  # caller there will be an AuthError. If the token has expired there
-  # will also be an AuthError.
+  # 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.
   def decode(auth_header)
     unless auth_header && (tkn = auth_header.split).length == 2 && tkn[0] =~ /^bearer$/i
       raise DecodeError, "invalid authentication header: #{auth_header}"

data/lib/uaa/token_issuer.rb

@@ -11,51 +11,74 @@
 # subcomponent's license, as noted in the LICENSE file.
 #++
 
-# Web or Native Clients (in the OAuth2 sense) would use this class to get tokens
-# that they can use to get access to resources
-
-# Client Apps that want to get access on behalf of their users to
-# resource servers 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.
-
 require 'securerandom'
 require 'uaa/http'
 
 module CF::UAA
 
-# The Token class holds access and refresh tokens as well as token meta-data
-# such as token type and expiration time. 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.
+# The Token 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
+
+  # Returns a hash of 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.
   attr_reader :info
-  def initialize(info); @info = info end
+
+  def initialize(info) # :nodoc:
+    @info = info
+  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
+# 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
 
+  # 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)
     @target, @client_id, @client_secret = target, client_id, client_secret
     @token_target = token_target || target
   end
 
-  # login prompts for use by app to collect credentials for implicit grant
+  # 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"]}
   def prompts
     reply = json_get @target, '/login'
     return reply['prompts'] if reply && reply['prompts']
     raise BadResponse, "No prompts in response from target #{@target}"
   end
 
-  # gets an access token in a single call to the UAA with the client
-  # credentials used for authentication. The credentials arg should
+  # 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
-  # as specified by the information retrieved by #prompts
+  # corresponding to the keys retrieved by #prompts.
+  # Returns a Token.
   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}"
@@ -74,22 +97,43 @@ class TokenIssuer
     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. The redirect_uri
+  # 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.
   def implicit_uri(redirect_uri, scope = nil)
     @target + authorize_path_args("token", redirect_uri, scope)
   end
 
-  def implicit_grant(implicit_uri, callback_query)
+  # 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.
+  def implicit_grant(implicit_uri, callback_fragment)
     in_params = Util.decode_form_to_hash(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_query, 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.
   def autologin_uri(redirect_uri, credentials, scope = nil)
     headers = {'content_type' => 'application/x-www-form-urlencoded', 'accept' => 'application/json',
         'authorization' => Http.basic_auth(@client_id, @client_secret) }
@@ -99,7 +143,7 @@ class TokenIssuer
     @target + authorize_path_args('code', redirect_uri, scope, SecureRandom.uuid, code: reply[:code])
   end
 
-  # constructs a uri that the client is to return to the browser to direct
+  # 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.
@@ -107,6 +151,19 @@ class TokenIssuer
     @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.
   def authcode_grant(authcode_uri, callback_query)
     ac_params = Util.decode_form_to_hash(URI.parse(authcode_uri).query)
     unless ac_params['state'] && ac_params['redirect_uri']
@@ -122,14 +179,24 @@ class TokenIssuer
     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.
   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
+  # Returns a Token.
   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
+  # Returns a Token, 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

data/lib/uaa/util.rb

@@ -18,7 +18,7 @@ require 'uri'
 
 # :nodoc:
 module CF
-  # Namespace for Cloudfoundry UAA 
+  # Namespace for Cloudfoundry User Account and Authentication service Ruby APIs
   module UAA end
 end
 
@@ -30,30 +30,40 @@ end
 
 module CF::UAA
 
-# all CF::UAA exceptions are derived from UAAError
+# Useful parent class. All CF::UAA exceptions are derived from this.
 class UAAError < RuntimeError; end
 
-# Authentication error
+# Indicates an authentication error
 class AuthError < UAAError; end
 
-# error for decoding tokens, base64 encoding, or json
+# Indicates an error occurred decoding a token, base64 decoding, or JSON
 class DecodeError < UAAError; end
 
-# low level helper functions useful to the UAA client APIs
+# Low level helper functions useful to the UAA client APIs
 class Util
 
-  # http headers and various protocol tags tend to contain '-' characters,
+  # HTTP headers and various protocol tags tend to contain '-' characters,
   # are intended to be case-insensitive, and often end up as keys in ruby
-  # hashes. The :undash style converts to lowercase for at least
-  # consistent case if not exactly case insensitive, and with '_' instead
-  # of '-' for ruby convention. :todash reverses :undash (except for case).
-  # :uncamel and :tocamel provide similar translations for camel-case keys.
+  # hashes. SCIM[http://www.simplecloud.info/] specifies that attribute
+  # names are case-insensitive and this code downcases such strings using
+  # this method.
+  #
+  # The various +styles+ convert +key+ as follows:
+  # [+:undash+] to lowercase, '-' to  '_', and to a symbol
+  # [+:todash+] to string, '_' to '-'
+  # [+:uncamel+] uppercase to underscore-lowercase, to symbol
+  # [+:tocamel+] reverse of +uncamel+
+  # [+:tosym+] to symbol
+  # [+:tostr+] to string
+  # [+:down+] to lowercase
+  # [+:none+] leave the damn key alone
+  #
   # returns new key
   def self.hash_key(k, style)
     case style
     when :undash then k.to_s.downcase.tr('-', '_').to_sym
     when :todash then k.to_s.downcase.tr('_', '-')
-    when :uncamel then k.to_s.downcase.gsub(/([A-Z])([^A-Z]*)/,'_\1\2').to_sym
+    when :uncamel then k.to_s.gsub(/([A-Z])([^A-Z]*)/,'_\1\2').downcase.to_sym
     when :tocamel then k.to_s.gsub(/(_[a-z])([^_]*)/) { $1[1].upcase + $2 }
     when :tosym then k.to_sym
     when :tostr then k.to_s
@@ -63,28 +73,28 @@ class Util
     end
   end
 
-  # modifies obj in place changing any hash keys to style (see hash_key). 
+  # Modifies obj in place changing any hash keys to style (see hash_key).
   # Recursively modifies subordinate hashes. Returns modified obj
   def self.hash_keys!(obj, style = :none)
     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| 
+    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 (see hash_key). 
+
+  # Makes a new copy of obj with hash keys to style (see hash_key).
   # Recursively modifies subordinate hashes. Returns modified obj
   def self.hash_keys(obj, style = :none)
     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) 
+    obj.each_with_object({}) {|(k, v), h|
+      h[hash_key(k, style)] = hash_keys(v, style)
     }
   end
 
@@ -103,10 +113,22 @@ class Util
     raise ArgumentError, e.message
   end
 
+  # Converts +obj+ to JSON
   def self.json(obj) MultiJson.dump(obj) end
+
+  # Converts +obj+ to nicely formatted JSON
+  def self.json_pretty(obj) MultiJson.dump(obj, pretty: true) end
+
+  # Converts +obj+ to a URL-safe base 64 encoded string
   def self.json_encode64(obj = {}) encode64(json(obj)) end
+
+  # Converts +str+ from base64 encoding of a JSON string to a (returned) hash.
   def self.json_decode64(str) json_parse(decode64(str)) end
+
+  # encodes +obj+ as a URL-safe base 64 encoded string, with trailing padding removed.
   def self.encode64(obj) Base64::urlsafe_encode64(obj).gsub(/=*$/, '') end
+
+  # adds proper padding to a URL-safe base 64 encoded string, and then returns the decoded string.
   def self.decode64(str)
     return unless str
     pad = str.length % 4
@@ -116,20 +138,22 @@ class Util
     raise DecodeError, "invalid base64 encoding"
   end
 
+  # Parses a JSON string into the returned hash. For possible values of +style+
+  # see #hask_key
   def self.json_parse(str, style = :none)
     hash_keys!(MultiJson.load(str), style) if str && !str.empty?
   rescue MultiJson::DecodeError
     raise DecodeError, "json decoding error"
   end
 
-  def self.truncate(obj, limit = 50)
+  def self.truncate(obj, limit = 50) # :nodoc:
     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
 
-  # many parameters in these classes can be given as arrays, or as a list of
+  # 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 arguments.
   def self.arglist(arg, default_arg = nil)
@@ -139,11 +163,12 @@ class Util
     arg.split(/[\s\,]+/).reject { |e| e.empty? }
   end
 
-  # reverse of arglist, puts arrays of strings into a single, space-delimited string
+  # Reverse of arglist, puts arrays of strings into a single, space-delimited 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.
   def self.default_logger(level = nil, sink = nil)
     if sink || !@default_logger
       @default_logger = Logger.new(sink || $stdout)

data/lib/uaa/version.rb

@@ -13,6 +13,6 @@
 
 module CF
   module UAA
-    VERSION = "1.3.0"
+    VERSION = "1.3.1"
   end
 end

data/spec/scim_spec.rb

@@ -43,13 +43,13 @@ describe Scim do
       check_headers(headers, :json, :json)
       [200, '{"ID":"id12345"}', {"content-type" => "application/json"}]
     end
-    result = subject.add(:user, hair: "brown", shoe_size: "large", 
+    result = subject.add(:user, hair: "brown", shoe_size: "large",
         eye_color: ["blue", "green"], name: "fred")
     result["id"].should == "id12345"
   end
 
   it "replaces an object" do
-    obj = {hair: "black", shoe_size: "medium", eye_color: ["hazel", "brown"], 
+    obj = {hair: "black", shoe_size: "medium", eye_color: ["hazel", "brown"],
           name: "fredrick", meta: {version: 'v567'}, id: "id12345"}
     subject.set_request_handler do |url, method, body, headers|
       url.should == "#{@target}/Users/id12345"
@@ -78,7 +78,7 @@ describe Scim do
       url.should =~ %r{^#{@target}/Users\?attributes=id&startIndex=[12]$}
       method.should == :get
       check_headers(headers, nil, :json)
-      reply = url =~ /1$/ ? 
+      reply = url =~ /1$/ ?
         '{"TotalResults":2,"ItemsPerPage":1,"StartIndex":1,"RESOURCES":[{"id":"id12345"}]}' :
         '{"TotalResults":2,"ItemsPerPage":1,"StartIndex":2,"RESOURCES":[{"id":"id67890"}]}'
       [200, reply, {"content-type" => "application/json"}]

data/spec/token_issuer_spec.rb

@@ -141,7 +141,7 @@ describe TokenIssuer do
             "expires_in=98765&scope=openid+logs.read&state=bad_state"
         [302, nil, {"content-type" => "application/json", "location" => location}]
       end
-      expect {token = subject.implicit_grant_with_creds(username: "joe+admin", 
+      expect {token = subject.implicit_grant_with_creds(username: "joe+admin",
               password: "?joe's%password$@ ")}.to raise_exception BadResponse
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cf-uaa-lib
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-05 00:00:00.000000000 Z
+date: 2012-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -191,7 +191,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2445597345483257892
+      hash: -3747087268217165493
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -200,7 +200,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2445597345483257892
+      hash: -3747087268217165493
 requirements: []
 rubyforge_project: cf-uaa-lib
 rubygems_version: 1.8.21