cf-uaa-lib 1.3.0

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/
+doc/
+coverage/
+spec_reports/
+vendor/

data/Gemfile

@@ -0,0 +1,16 @@
+# 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.
+#
+
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in uaa.gemspec
+gemspec

data/README.md

@@ -0,0 +1,43 @@
+# CloudFoundry UAA Gem
+
+Client gem for interacting with the CloudFoundry UAA server.
+
+Set up a local ruby environment (so sudo not required):
+
+  `$ rvm use 1.9.2`
+
+or
+
+  `$ rbenv global 1.9.2-p180`
+
+see: https://rvm.io/ or http://rbenv.org/
+
+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"]`
+
+## Tests
+
+Run the tests with rake:
+
+  `$ bundle exec rake test`
+
+Run the tests and see a fancy coverage report:
+
+  `$ bundle exec rake cov`
+

data/Rakefile

@@ -0,0 +1,50 @@
+# 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 "rdoc/task"
+require "rspec/core/rake_task"
+require "bundler/gem_tasks" # only available in bundler >= 1.0.15
+require "ci/reporter/rake/rspec"
+
+ENV['CI_REPORTS'] = File.expand_path("spec_reports")
+COV_REPORTS = File.expand_path("coverage")
+
+task :default => [:test]
+task :tests => [:test]
+task :spec => [:test]
+
+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]
+
+task :pre_coverage do
+  rm_rf COV_REPORTS
+  ENV['COVERAGE'] = "exclude-spec exclude-vendor"
+end
+
+task :rcov_reports do
+  ENV['COVERAGE'] += " rcov"
+end
+
+task :view_coverage do
+  `firefox #{File.join(COV_REPORTS, 'index.html')}`
+end

data/cf-uaa-lib.gemspec

@@ -0,0 +1,45 @@
+# -*- encoding: utf-8 -*-
+#
+# 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.
+#
+
+$:.push File.expand_path("../lib", __FILE__)
+require "uaa/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cf-uaa-lib"
+  s.version     = CF::UAA::VERSION
+  s.authors     = ["Dave Syer", "Dale Olds", "Joel D'sa", "Vidya Valmikinathan", "Luke Taylor"]
+  s.email       = ["dsyer@vmware.com", "olds@vmware.com", "jdsa@vmware.com", "vidya@vmware.com", "ltaylor@vmware.com"]
+  s.homepage    = "https://github.com/cloudfoundry/cf-uaa-lib"
+  s.summary     = %q{Client library for CloudFoundry UAA}
+  s.description = %q{Client library for interacting with the CloudFoundry User Account and Authorization (UAA) server.  The UAA is an OAuth2 Authorization Server so it can be used by webapps and command line apps to obtain access tokens to act on behalf of users.  The tokens can then be used to access protected resources in a Resource Server.  This library is for use by UAA client applications or resource servers.}
+
+  s.rubyforge_project = "cf-uaa-lib"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # dependencies
+  s.add_dependency "multi_json"
+
+  s.add_development_dependency "bundler"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rdoc"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "simplecov-rcov"
+  s.add_development_dependency "ci_reporter"
+
+end

data/lib/uaa.rb

@@ -0,0 +1,18 @@
+#--
+# 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 "uaa/version"
+require "uaa/misc"
+require "uaa/token_issuer"
+require "uaa/token_coder"
+require "uaa/scim"

data/lib/uaa/http.rb

@@ -0,0 +1,147 @@
+#--
+# 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 'base64'
+require 'net/http'
+require 'uaa/util'
+
+module CF::UAA
+
+class BadTarget < UAAError; end
+class NotFound < UAAError; end
+class BadResponse < UAAError; end
+class InvalidToken < UAAError; end
+class HTTPException < UAAError; end
+class TargetError < UAAError
+  attr_reader :info
+  def initialize(error_info = {})
+    @info = error_info
+  end
+end
+
+# Utility accessors and methods for objects that want to access JSON web APIs.
+module Http
+
+  def logger=(logr); @logger = logr end
+  def logger ; @logger ||= Util.default_logger end
+  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
+  def set_request_handler(&blk) @req_handler = blk end
+
+  def self.basic_auth(name, password)
+    "Basic " + Base64::strict_encode64("#{name}:#{password}")
+  end
+
+  def add_auth_json(auth, headers, jsonhdr = "content-type") # :nodoc:
+    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, 
+        add_auth_json(authorization, headers, "accept")), key_style)
+  end
+
+  def json_post(target, path, body, authorization, headers = {})
+    http_post(target, path, Util.json(body), add_auth_json(authorization, headers))
+  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_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? || 
+          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
+      raise parsed_reply && parsed_reply["error"] == "invalid_token" ?
+          InvalidToken : TargetError.new(parsed_reply), "error response"
+    end
+    parsed_reply
+  rescue DecodeError
+    raise BadResponse, "invalid JSON response"
+  end
+
+  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]
+    unless [200, 204].include?(status)
+      raise (status == 404 ? NotFound : BadResponse), "invalid response from #{path}: #{status}"
+    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) : 
+        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}" }
+
+    [status, body, headers]
+
+  rescue Exception => e
+    e.message.replace "Target #{target}, #{e.message}"
+    logger.debug { "<---- no response due to exception: #{e}" }
+    raise e
+  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]
+    headers["content-length"] = body.length if body
+    uri = URI.parse(url)
+    req = reqtype.new(uri.request_uri)
+    headers.each { |k, v| req[k] = v }
+    http_key = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+    @http_cache ||= {}
+    unless http = @http_cache[http_key]
+      @http_cache[http_key] = http = Net::HTTP.new(uri.host, uri.port)
+      if uri.is_a?(URI::HTTPS)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+    end
+    reply, outhdrs = http.request(req, body), {}
+    reply.each_header { |k, v| outhdrs[k] = v }
+    [reply.code.to_i, reply.body, outhdrs]
+
+  rescue URI::Error, SocketError, SystemCallError => e
+    raise BadTarget, "error: #{e.message}"
+  rescue Net::HTTPBadResponse => e
+    raise HTTPException, "HTTP exception: #{e.class}: #{e}"
+  end
+
+end
+
+end

data/lib/uaa/misc.rb

@@ -0,0 +1,67 @@
+#--
+# 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.
+#++
+
+# 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.
+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
+
+  def self.server(target)
+    reply = json_get(target, '/login')
+    return reply if reply && reply["prompts"]
+    raise BadResponse, "Invalid response from target #{target}"
+  end
+
+  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))
+  end
+
+  # Returns hash of values from the Authorization Server that are associated
+  # with the opaque 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"])
+    if audience_ids && (!auds || (auds & audience_ids).empty?)
+      raise AuthError, "invalid audience: #{auds.join(' ')}"
+    end
+    reply
+  end
+
+  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"))
+  end
+
+end
+
+end

data/lib/uaa/scim.rb

@@ -0,0 +1,206 @@
+#--
+# 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 '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.
+class Scim
+
+  include Http
+
+  private
+
+  def force_attr(k)
+    kd = k.to_s.downcase
+    kc = {"username" => "userName", "familyname" => "familyName", 
+      "givenname" => "givenName", "middlename" => "middleName", 
+      "honorificprefix" => "honorificPrefix", 
+      "honorificsuffix" => "honorificSuffix", "displayname" => "displayName",
+      "nickname" => "nickName", "profileurl" => "profileUrl",
+      "streetaddress" => "streetAddress", "postalcode" => "postalCode",
+      "usertype" => "userType", "preferredlanguage" => "preferredLanguage",
+      "x509certificates" => "x509Certificates", "lastmodified" => "lastModified",
+      "externalid" => "externalId", "phonenumbers" => "phoneNumbers",
+      "startindex" => "startIndex"}[kd]
+    kc || kd
+  end
+
+  # This is very inefficient and should be unnecessary. SCIM (1.1 and early
+  # 2.0 drafts) specify that attribute names are case insensitive. However
+  # in the UAA attribute names are currently case sensitive. This hack takes
+  # a hash with keys as symbols or strings and with any case, and forces
+  # the attribute name to the case that the uaa expects.
+  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) }
+  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']}
+    unless elem == :path || elem == :name_attr
+      raise ArgumentError, "scim schema element must be :path or :name_attr"
+    end
+    unless ary = scimfo[type]
+      raise ArgumentError, "scim resource type must be one of #{scimfo.keys.inspect}"
+    end
+    ary[elem == :path ? 0 : 1]
+  end
+
+  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.
+  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
+  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']
+
+    return reply if reply && reply["id"]
+    raise BadResponse, "no id returned by add request to #{@target}#{path}"
+  end
+
+  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
+  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"] ? 
+        {'if-match' => info["meta"]["version"]} : {}
+    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
+  def query(type, query = {})
+    path, query = prep_request(type, query)
+    query = 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)
+
+      # hide client endpoints that are not scim compatible
+      return {'resources' => info.values } if type == :client && info.is_a?(Hash)
+
+      raise BadResponse, "invalid reply to query of #{@target}#{path}"
+    end
+    info
+  end
+
+  def get(type, id) 
+    path, _ = prep_request(type)
+    info = json_get(@target, "#{path}/#{URI.encode(id)}", @auth_header, :down)
+
+    # hide client endpoints that are not scim compatible
+    info["id"] = info["client_id"] if type == :client && !info["id"]
+    info
+  end
+
+  # Collects all pages of entries from a query, returns array of results.
+  # Type can be any scim resource type
+  def all_pages(type, query = {})
+    query = query.reject {|k, v| v.nil? }
+    query["startindex"], info = 1, []
+    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}"
+      end
+      query["startindex"] = info.length + 1
+    end
+  end
+
+  # Queries for objects by name. returns array of name/id hashes for each
+  # name 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 "))
+  end
+
+  # Convenience method to query for single object by name. 
+  # Returns its id. Raises error if not found.
+  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
+    end
+
+    unless res && res.is_a?(Array) && res.length == 1 &&
+        res[0].is_a?(Hash) && (id = res[0]["id"])
+      raise NotFound, "#{name} not found in #{@target}#{type_info(type, :path)}"
+    end
+    id
+  end
+
+  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
+
+  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))
+  end
+
+end
+
+end
+