conjur-api 4.29.2 → 4.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3501dba172c6c99ebdc99ad7fef80634e39cf2c3
-  data.tar.gz: 620f5813442acedbcd510ac2756bd5a6e8d700a8
+  metadata.gz: bac541f4dc5eb324e42a7dce3dc436312b98ef18
+  data.tar.gz: 184c9e5ec253703bd0918b31145a4fa1c26d0d0f
 SHA512:
-  metadata.gz: a090764853263323c9d21afcde4069a9481aabb1dcd668c2407f0a8e349cf50439e6dd80924b51a86e35cf6dbc951ee93baa9e03524164452b95600955914c28
-  data.tar.gz: a6bb48a6b4fe8b4a505a847f7915904d00ddcd4e86a13e7b5dcd059ae269ef5dd82d565bb20431babc2d48992ded7227e85bb9381dbb355473edc5283340da01
+  metadata.gz: 25fc29905946cadcd53c6828eadc568cde3f05790a78987093d3219396130ab36cfc920c723e455126f0d573c1be85b7ff5b1c057facc50c9272fa6e7d7cf39b
+  data.tar.gz: ca362cd00b847a5269fe723b1c39eaee9798531d73e55b9e897f369a85165c98f8be2ebf3cac43befbdb1f7d4b392b26c51aa21328ec6e19d8a0ac713213ce31

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+# v4.30.0
+
+The following enhancements require Conjur server 4.9.1.0 or later:
+
+* Supports filter and pagination of role-listing methods.
+* Supports non-recursive retrieval of role memberships.
+* Supports the +role+ field on `Conjur::RoleGrant`.
+
+On older server versions, the new options will be ignored by the server.
+
 # v4.29.2
 
 * `Conjur::API#resources` now supports `:owner` to retrieve all resources owned (directly or indirectly) by the indicated role. This capability has always been provided by the service, but was not exposed by the Ruby API.

data/lib/conjur-api/version.rb

@@ -19,6 +19,6 @@
 
 module Conjur
   class API
-    VERSION = "4.29.2"
+    VERSION = "4.30.0"
   end
 end

data/lib/conjur/api/resources.rb

@@ -141,9 +141,14 @@ module Conjur
       opts = { host: Conjur::Authz::API.host, credentials: credentials }.merge opts
       opts[:account] ||= Conjur.account
       
-      Resource.all(opts).map do |result|
-        resource(result['id']).tap do |r|
-          r.attributes = result
+      result = Resource.all(opts)
+      if result.is_a?(Numeric)
+        result
+      else
+        result.map do |result|
+          resource(result['id']).tap do |r|
+            r.attributes = result
+          end
         end
       end
     end

data/lib/conjur/base.rb

@@ -22,6 +22,7 @@ require 'rest-client'
 require 'json'
 require 'base64'
 
+require 'conjur/query_string'
 require 'conjur/exists'
 require 'conjur/has_attributes'
 require 'conjur/has_owner'

data/lib/conjur/query_string.rb

@@ -0,0 +1,11 @@
+module QueryString
+  protected
+
+  def options_querystring options
+    if options.empty?
+      ""
+    else
+      "?#{options.to_query}"
+    end
+  end
+end

data/lib/conjur/resource.rb

@@ -33,6 +33,8 @@ module Conjur
     include HasAttributes
     include PathBased
     include Exists
+    include QueryString
+    extend QueryString
 
     alias resource_kind kind
     
@@ -89,10 +91,15 @@ module Conjur
       self.put(options)
     end
     
-    # Lists roles that have a specified permission on the resource.
+    # Lists roles that have a specified permission on the resource. 
     #
     # This will return only roles of which api.current_user is a member.
     #
+    # Options:
+    #
+    # * **offset** Zero-based offset into the result set.
+    # * **limit**  Total number of records returned.
+    #
     # @example
     #   resource = api.resource 'conjur:variable:example'
     #   resource.permitted_roles 'execute' # => ['conjur:user:admin']
@@ -100,10 +107,16 @@ module Conjur
     #   resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:user:jon']
     #
     # @param permission [String] the permission
-    # @param options [Hash, nil] extra options to pass to RestClient::Resource#get
-    # @return [Array<String>] the ids of roles that have `permission` on this resource.
+    # @param options [Hash, nil] extra parameters to pass to the webservice method.
+    # @return [Array<String>] the ids of roles that have `permission` on this resource, sorted 
+    # alphabetically.
     def permitted_roles(permission, options = {})
-      JSON.parse RestClient::Resource.new(Conjur::Authz::API.host, self.options)["#{account}/roles/allowed_to/#{permission}/#{path_escape kind}/#{path_escape identifier}"].get(options)
+      result = JSON.parse RestClient::Resource.new(Conjur::Authz::API.host, self.options)["#{account}/roles/allowed_to/#{permission}/#{path_escape kind}/#{path_escape identifier}#{options_querystring options}"].get
+      if result.is_a?(Hash) && ( count = result['count'] )
+        count
+      else
+        result
+      end
     end
     
     # Changes the owner of a resource.  You must be the owner of the resource
@@ -275,19 +288,22 @@ module Conjur
     # - search (optional),
     # - limit (optional),
     # - offset (optional).
-    def self.all opts = {}
-      host, credentials, account, kind = opts.values_at(*[:host, :credentials, :account, :kind])
+    def self.all options = {}
+      host, credentials, account, kind = options.values_at(*[:host, :credentials, :account, :kind])
       fail ArgumentError, "host and account are required" unless [host, account].all?
+      %w(host credentials account kind).each do |name|
+        options.delete(name.to_sym)
+      end
 
       credentials ||= {}
 
       path = "#{account}/resources" 
       path += "/#{kind}" if kind
-      query = opts.slice(:owner, :acting_as, :limit, :offset, :search, :has_annotation)
-      path += "?#{query.to_query}" unless query.empty?
-      resource = RestClient::Resource.new(host, credentials)[path]
-      
-      JSON.parse resource.get
+
+      result = JSON.parse(RestClient::Resource.new(host, credentials)[path][options_querystring options].get)
+
+      result = result['count'] if result.is_a?(Hash)
+      result
     end
 
     protected

data/lib/conjur/role.rb

@@ -33,6 +33,8 @@ module Conjur
   class Role < RestClient::Resource
     include Exists
     include PathBased
+    include QueryString
+
 
     # The *unqualified* identifier for this role.
     #
@@ -72,7 +74,7 @@ module Conjur
       self.put(options)
     end
 
-    # Find all roles of which this role is a member.  This relationship is recursively expanded,
+    # Find all roles of which this role is a member.  By default, role relationships are recursively expanded,
     # so if `a` is a member of `b`, and `b` is a member of `c`, `a.all` will include `c`.
     #
     # ### Permissions
@@ -81,6 +83,10 @@ module Conjur
     # You can restrict the roles returned to one or more role ids.  This feature is mainly useful
     # for checking whether this role is a member of any of a set of roles.
     #
+    # ### Options
+    #
+    # * **recursive** Defaults to +true+, performs recursive expansion of the memberships.
+    #
     # @example Show all roles of which `"conjur:group:pubkeys-1.0/key-managers"` is a member
     #   # Add alice to the group, so we see something interesting
     #   key_managers = api.group('pubkeys-1.0/key-managers')
@@ -94,18 +100,30 @@ module Conjur
     #   is_member = api.role('conjur:user:alice').all(filter: ['conjur:group:developers', 'conjur:group:ops']).any?
     #
     # @param [Hash] options options for the request
-    # @option options [String, #roleid, Array<String, #roleid>] :filter only return roles in this list
+    # @param options [Hash, nil] :filter only return roles in this list. Also, extra parameters to pass to the webservice method.
     # @return [Array<Conjur::Role>] Roles of which this role is a member
     def all(options = {})
-      query_string = "?all"
-      
+      request = if options.delete(:recursive) == false
+        options["memberships"] = true
+      else
+        options["all"] = true
+      end
       if filter = options.delete(:filter)
         filter = [filter] unless filter.is_a?(Array)
-        filter.map!{ |obj| cast(obj, :roleid) }
-        (query_string << "&" << filter.to_query("filter")) unless filter.empty?
+        options["filter"] = filter.map{ |obj| cast(obj, :roleid) }
       end
-      JSON.parse(self[query_string].get(options)).collect do |id|
-        Role.new(Conjur::Authz::API.host, self.options)[Conjur::API.parse_role_id(id).join('/')]
+
+      result = JSON.parse(self[options_querystring options].get)
+      if result.is_a?(Hash) && ( count = result['count'] )
+        count
+      else
+        result.collect do |item|
+          if item.is_a?(String)
+            Role.new(Conjur::Authz::API.host, self.options)[Conjur::API.parse_role_id(item).join('/')]
+          else
+            RoleGrant.parse_from_json(item, self.options)
+          end
+        end
       end
     end
     
@@ -300,17 +318,23 @@ module Conjur
     end
     
 
-    # Fetch the members of this role. The results are *not* recursively expanded (in contrast to {#memberships}).
+    # Fetch the direct members of this role. The results are *not* recursively expanded).
     #
     # ### Permissions
     # You must be a member of the role to call this method.
     # 
-    # @param [Hash] options unused and included only for backwards compatibility 
+    # @param options [Hash, nil] extra parameters to pass to the webservice method.
     # @return [Array<Conjur::RoleGrant>] the role memberships
     # @raise [RestClient::Forbidden] if you don't have permission to perform this operation
-    def members
-      JSON.parse(self["?members"].get(options)).collect do |json|
-        RoleGrant.parse_from_json(json, self.options)
+    def members options = {}
+      options["members"] = true
+      result = JSON.parse(self[options_querystring options].get)
+      if result.is_a?(Hash) && ( count = result['count'] )
+        count
+      else
+        result.collect do |json|
+          RoleGrant.parse_from_json(json, self.options)
+        end
       end
     end
   end

data/lib/conjur/role_grant.rb

@@ -27,23 +27,24 @@ module Conjur
   #   admin_role.members.map{|grant| grant.member}.include? alice # => true
   #
   class RoleGrant
-
+    # The role which was granted.
+    # @return [Conjur::Role]
+    attr_reader :role
 
     # The member role in the relationship
-    # @return [Conjur::Role] the member
+    # @return [Conjur::Role]
     attr_reader :member
 
     # The role that created this grant.
     #
-    # @return [Conjur::Role] the role that created the grant
+    # @return [Conjur::Role]
     attr_reader :grantor
 
     # When true, the role {#member} is allowed to give this grant to other roles
     #
-    # @return [Boolean] whether the role can grant the role to others
+    # @return [Boolean]
     attr_reader :admin_option
 
-
     # @api private
     #
     # Create a new RoleGrant instance.
@@ -51,12 +52,24 @@ module Conjur
     # @param [Conjur::Role] member the member to which the role was granted
     # @param [Conjur::Role] grantor  the role that created this grant
     # @param [Boolean] admin_option whether `member` can give the grant to other roles
-    def initialize member, grantor, admin_option
+    def initialize role, member, grantor, admin_option
+      @role = role
       @member = member
       @grantor = grantor
       @admin_option = admin_option
     end
 
+    # Representation of the role grant as a hash.
+    def to_h
+      {
+        member: member.roleid,
+        grantor: grantor.roleid,
+        admin_option: admin_option
+      }.tap do |h|
+        h[:role] = role.roleid if role
+      end
+    end
+
     #@!attribute member
     #   The member thing
     #   @return [Conjur::Role] a ret?
@@ -70,9 +83,15 @@ module Conjur
       # @param [Hash] credentials the credentials used to create APIs for the member and grantor role objects
       # @return [Conjur::RoleGrant]
       def parse_from_json(json, credentials)
+        # The 'role' field is introduced after Conjur 4.9.0.0.
+        role = if ( role_json = json['role'] )
+          Role.new(Conjur::Authz::API.host, credentials)[Conjur::API.parse_role_id(role_json).join('/')]
+        else
+          nil
+        end
         member = Role.new(Conjur::Authz::API.host, credentials)[Conjur::API.parse_role_id(json['member']).join('/')]
         grantor = Role.new(Conjur::Authz::API.host, credentials)[Conjur::API.parse_role_id(json['grantor']).join('/')]
-        RoleGrant.new(member, grantor, json['admin_option'])
+        RoleGrant.new(role, member, grantor, json['admin_option'])
       end
     end
   end

data/spec/api/resources_spec.rb

@@ -1,6 +1,9 @@
 require 'spec_helper'
+require 'helpers/request_helpers'
 
 describe Conjur::API, api: :dummy do
+  include RequestHelpers
+
   describe '#create_resource' do
     it "passes to resource#create" do
       allow(api).to receive(:resource).with(:id).and_return(resource = double)
@@ -31,6 +34,12 @@ describe Conjur::API, api: :dummy do
         { 'id' => id }
       end
     }
+    it "counts resources" do
+      expect(Conjur::Resource).to receive(:all)
+        .with(host: authz_host, account: account, credentials: api.credentials, count: true).and_return(100)
+
+      expect(api.resources(count: true)).to eq(100)
+    end
     it "lists all resources" do
       expect(Conjur::Resource).to receive(:all)
         .with(host: authz_host, account: account, credentials: api.credentials).and_return(resources)

data/spec/lib/resource_spec.rb

@@ -1,6 +1,9 @@
 require 'spec_helper'
+require 'helpers/request_helpers'
 
 describe Conjur::Resource, api: :dummy, logging: :temp do
+  include RequestHelpers
+
   let(:account) { "the-account" }
   let(:uuid) { "ddd1f59a-494d-48fb-b045-0374c4a6eef9" }
 
@@ -59,6 +62,26 @@ describe Conjur::Resource, api: :dummy, logging: :temp do
 
       expect(subject.permitted_roles("nuke")).to eq(['foo', 'bar'])
     end
+
+    it 'supports counting' do
+      expect_request(
+        method: :get,
+        url: "http://authz.example.com/some-account/roles/allowed_to/nuke/the-kind/resource-id?count=true",
+        headers: {}
+      ).and_return({count: 12}.to_json)
+
+      expect(subject.permitted_roles("nuke", count: true)).to eq(12)
+    end
+
+    it 'supports filtering' do
+      expect_request(
+        method: :get,
+        url: "http://authz.example.com/some-account/roles/allowed_to/nuke/the-kind/resource-id?search=hamsters",
+        headers: {}
+      ).and_return '["foo", "bar"]'
+
+      expect(subject.permitted_roles("nuke", search: 'hamsters')).to eq(['foo', 'bar'])
+    end
   end
 
   describe '#give_to' do
@@ -155,7 +178,7 @@ describe Conjur::Resource, api: :dummy, logging: :temp do
     it "calls /account/resources" do
       expect_request(
         method: :get,
-        url: "http://authz.example.com/the-account/resources",
+        url: "http://authz.example.com/the-account/resources/",
         headers: {}
       ).and_return '["foo", "bar"]'
 
@@ -165,7 +188,7 @@ describe Conjur::Resource, api: :dummy, logging: :temp do
     it "can filter by owner" do
       expect_request(
         method: :get,
-        url: "http://authz.example.com/the-account/resources/chunky?owner=alice",
+        url: "http://authz.example.com/the-account/resources/chunky/?owner=alice",
         headers: {}
       ).and_return '["foo", "bar"]'
 
@@ -176,7 +199,7 @@ describe Conjur::Resource, api: :dummy, logging: :temp do
     it "can filter by kind" do
       expect_request(
         method: :get,
-        url: "http://authz.example.com/the-account/resources/chunky",
+        url: "http://authz.example.com/the-account/resources/chunky/",
         headers: {}
       ).and_return '["foo", "bar"]'
 
@@ -184,11 +207,21 @@ describe Conjur::Resource, api: :dummy, logging: :temp do
         .to eql(%w(foo bar))
     end
     
+    it "can count" do
+      expect_request(
+        method: :get,
+        url: "http://authz.example.com/the-account/resources/?count=true",
+        headers: {}
+      ).and_return({count: 12}.to_json)
+
+      expect(Conjur::Resource.all host: authz_host, account: account, count: true).to eq(12)
+    end
+
     it "passes search, limit, and offset params" do
       expect_request(
         method: :get,
         # Note that to_query sorts the keys
-        url: "http://authz.example.com/the-account/resources?limit=5&offset=6&search=something",
+        url: "http://authz.example.com/the-account/resources/?limit=5&offset=6&search=something",
         headers: {}
       ).and_return '["foo", "bar"]'
       expect(Conjur::Resource.all(host: authz_host, account: account, search: 'something', limit:5, offset:6)).to eq(%w(foo bar))
@@ -197,7 +230,7 @@ describe Conjur::Resource, api: :dummy, logging: :temp do
     it "uses the given authz url" do
       expect_request(
         method: :get,
-        url: "http://otherhost.example.com/the-account/resources",
+        url: "http://otherhost.example.com/the-account/resources/",
         headers: {}
       ).and_return '["foo", "bar"]'
 

data/spec/lib/role_grant_spec.rb

@@ -2,9 +2,10 @@ require 'spec_helper'
 
 describe Conjur::RoleGrant, api: :dummy do
   describe '::parse_from_json' do
-    it "creates member and grantor roles" do
-      rg = Conjur::RoleGrant::parse_from_json({member: 'acc:k:r', grantor: 'acc:k:g', admin_option: true}.stringify_keys, {})
-      expect(rg.member.url).to eq("#{authz_host}/acc/roles/k/r")
+    it "creates role, member and grantor roles" do
+      rg = Conjur::RoleGrant::parse_from_json({role: 'acc:k:r', member: 'acc:k:m', grantor: 'acc:k:g', admin_option: true}.stringify_keys, {})
+      expect(rg.role.url).to eq("#{authz_host}/acc/roles/k/r")
+      expect(rg.member.url).to eq("#{authz_host}/acc/roles/k/m")
       expect(rg.grantor.url).to eq("#{authz_host}/acc/roles/k/g")
       expect(rg.admin_option).to eq(true)
     end

data/spec/lib/role_spec.rb

@@ -93,7 +93,7 @@ describe Conjur::Role, api: :dummy do
       roles = ['foo:k:bar', 'baz:k:xyzzy'] 
       expect_request(
         method: :get,
-        url: role.url + "/?all",
+        url: role.url + "/?all=true",
         headers: {}
       ).and_return roles.to_json
       all = role.all
@@ -102,6 +102,26 @@ describe Conjur::Role, api: :dummy do
       expect(all[1].account).to eq('baz')
       expect(all[1].id).to eq('xyzzy')
     end
+
+    it "handles 'count' parameter" do
+      expect_request(
+        method: :get,
+        url: role.url + "/?all=true&count=true",
+        headers: {}
+      ).and_return({count: 12}.to_json)
+      expect(role.all(count: true)).to eq(12)
+    end
+
+    describe "direct memberships" do
+      it 'routes to ?memberships' do
+        expect_request(
+          method: :get,
+          url: role.url + "/?memberships=true",
+          headers: {}
+        ).and_return("[]")
+        role.all(recursive: false)
+      end
+    end
     
     describe "filter param" do
       it "applies #cast to the filter" do
@@ -115,7 +135,7 @@ describe Conjur::Role, api: :dummy do
         it "calls ?all&#{query_string}" do
           expect_request(
             method: :get,
-            url: role.url + "/?all&#{query_string}",
+            url: role.url + "/?all=true&#{query_string}",
             headers:{}
           ).and_return([].to_json)
           role.all filter: filter
@@ -186,11 +206,20 @@ describe Conjur::Role, api: :dummy do
   end
 
   describe '#members' do
+    it "can count the grants" do
+      expect_request(
+        method: :get,
+        url: role.url + "/?count=true&members=true"
+      ).and_return({count: 12}.to_json)
+
+      expect(subject.members(count: true)).to eq(12)
+    end
+
     it "gets ?members and turns each into RoleGrant" do
       grants = %w(foo bar)
       expect_request(
         method: :get,
-        url: role.url + "/?members"
+        url: role.url + "/?members=true"
       ).and_return grants.to_json
       grants.each do |g|
         expect(Conjur::RoleGrant).to receive(:parse_from_json).with(g, anything).and_return g

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conjur-api
 version: !ruby/object:Gem::Version
-  version: 4.29.2
+  version: 4.30.0
 platform: ruby
 authors:
 - Rafal Rzepecki
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-22 00:00:00.000000000 Z
+date: 2017-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -402,6 +402,7 @@ files:
 - lib/conjur/log_source.rb
 - lib/conjur/path_based.rb
 - lib/conjur/pubkeys-api.rb
+- lib/conjur/query_string.rb
 - lib/conjur/resource.rb
 - lib/conjur/role.rb
 - lib/conjur/role_grant.rb