conjur-api 4.11.2 → 4.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c0dbb6eee708c58cc9e04487c2695e4c1c7c152
-  data.tar.gz: f7e5de492037f8ad72fd058533b8cc643153b823
+  metadata.gz: e4158ca28a27fd311f677a695b2f551e9f0f7984
+  data.tar.gz: 4acd4da34ae508e0d91260d37ea93f48b20dc315
 SHA512:
-  metadata.gz: 1ba62b5de107208b2334e8755bb3ea2ae15fffd630eabecfc97acf0fea6956f9b7c7f7e71bbd3e3cf0c0cbb8cb243a5530e8ad49cc127b0312e7ba552feeb2e9
-  data.tar.gz: c47e6fa447d74ae465c57fbaeaffc417df0fbde69bbac91582563129c119ac7c62da33626230a34512bf881617e416ecb0102bdf4d8470116d3fa5240133daed
+  metadata.gz: b8f8e9e4833429a08b95c04d002c3163e99dd5af85127418ec50b742d7f8ab3da41149bb607816bf44af3b66a1f6c168277f8c81459505dcf617076f137f5d3e
+  data.tar.gz: 184f448ab7eee155ff9b52bcb23b71bbda1e739bf714f04578c90ba69d0049d4359ff5bb7c91a2f9bde99755347e7741bc86fdc8ec84da2ff5a0406f4cf2cf5b

data/.gitignore

@@ -20,3 +20,6 @@ tmp
 .kateproject.d
 .rvmrc
 .idea
+
+# rspec
+.rspec

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# v4.12.0
+
+* Add the API method `role_graph` for retrieving role relationships in bulk
+
+# v4.11.2
+
 * Patch rest-client's patch of mime-types to support lazy loading
 * Remove 'wrong' dependency for faster loading
 

data/Gemfile

@@ -4,3 +4,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in conjur-api.gemspec
 gemspec
+
+group :development do
+  gem 'pry'
+end
+

data/lib/conjur/api/roles.rb

@@ -19,9 +19,32 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 require 'conjur/role'
+require 'conjur/graph'
 
 module Conjur
   class API
+    ##
+    # Fetch a digraph (or a forest of digraphs) representing of
+    #   role memberships related transitively to any of a list of roles.
+    #
+    # @param [Array<Conjur::Role, String>] roles the  digraph (or forest thereof) of
+    #   the ancestors and descendants of these roles or role ids will be returned
+    # @param [Hash] options options determining the graph returned
+    # @option opts [Boolean] :ancestors Whether to return ancestors of the given roles (true by default)
+    # @option opts [Boolean] :descendants Whether to return descendants of the given roles (true by default)
+    # @option opts [Conjur::Role, String] :as_role Only roles visible to this role will be included in the graph
+    # @return [Conjur::Graph] An object representing the role memberships digraph
+    def role_graph roles, options = {}
+      roles.map!{|r| normalize_roleid(r) }
+      options[:as_role] = normalize_roleid(options[:as_role]) if options.include?(:as_role)
+      options.reverse_merge! as_role: normalize_roleid(current_role), descendants: true, ancestors: true
+
+      query = {from_role: options.delete(:as_role)}
+        .merge(options.slice(:ancestors, :descendants))
+        .merge(roles: roles).to_query
+      Conjur::Graph.new RestClient::Resource.new(Conjur::Authz::API.host, credentials)["#{Conjur.account}/roles?#{query}"].get
+    end
+
     def create_role(role, options = {})
       role(role).tap do |r|
         r.create(options)
@@ -39,7 +62,7 @@ module Conjur
     def role_from_username username
       role(role_name_from_username username)
     end
-    
+
     def role_name_from_username username = self.username
       tokens = username.split('/')
       if tokens.size == 1
@@ -48,5 +71,14 @@ module Conjur
         [ tokens[0], tokens[1..-1].join('/') ].join(':')
       end
     end
+    
+    private
+    def normalize_roleid role
+      case role
+        when String then role
+        when Role then role.roleid
+          else raise "Can't normalize #{role}@#{role.class}"
+      end
+    end
   end
 end

data/lib/conjur/graph.rb

@@ -0,0 +1,194 @@
+#
+# Copyright (C) 2015 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+  class Graph
+
+    include Enumerable
+
+    # @!attribute r edges
+    #   @return [Array<Conjur::Graph::Edge>] the edges of this graph
+    attr_reader :edges
+
+    # @api private
+    def initialize val
+      @edges = case val
+        when String then JSON.parse(val)['graph']
+        when Hash then val['graph']
+        when Array then val
+        when Graph then val.edges
+        else raise ArgumentError, "don't know how to turn #{val}:#{val.class} into a Graph"
+      end.map{|pair| Edge.new(*pair) }.freeze
+      @next_node_id = 0
+      @node_ids = Hash.new{ |h,k| h[k] = next_node_id }
+    end
+
+    # Enumerates the edges of this graph.
+    # @yieldparam [Conjur::Graph::Edge] each edge of the graph
+    # @return edge [Conjur::Graph] this graph
+    def each_edge
+      return enum_for(__method__) unless block_given?
+      edges.each{|e| yield e}
+      self
+    end
+
+    alias each each_edge
+
+    # Enumerates the vertices (roles) of this graph
+    # @yieldparam vertex [Conjur::Role] each vertex in this graph
+    # @return [Conjur::Graph] this graph
+    def each_vertex
+      return enum_for(__method__) unless block_given?
+      vertices.each{|v| yield v}
+    end
+
+
+    def to_json short =  false
+      as_json(short).to_json
+    end
+
+    def as_json short = false
+      edges = self.edges.map{|e| e.as_json(short)}
+      short ? edges : {'graph' => edges}
+    end
+
+    # @param [String, NilClass] name to assign to the graph. Usually this can be omitted unless you
+    # are writing multiple graphs to a single file.  Must be in the ID format specified by
+    # http://www.graphviz.org/content/dot-language
+    #
+    # @return [String] the dot format (used by graphvis, among others) representation of this graph.
+    def to_dot name = nil
+      dot = "digraph #{name || ''} {"
+      vertices.each do |v|
+        dot << "\n\t" << dot_node(v)
+      end
+      edges.each do |e|
+        dot << "\n\t" << dot_edge(e)
+      end
+      dot << "\n}"
+    end
+    
+    def vertices
+      @vertices ||= edges.inject([]) {|a, pair| a.concat pair.to_a }.uniq
+    end
+
+    alias roles vertices
+
+    private
+
+    def node_id_for role
+      role = role.id if role.respond_to?(:id)
+      @node_ids[role]
+    end
+
+    def next_node_id
+      id = @next_node_id
+      @next_node_id += 1
+      "node_#{id}"
+    end
+
+    def node_label_for role
+      role = role.id if role.respond_to? :id
+      if single_account?
+        role = role.split(':', 2).last
+        if single_kind?
+          role = role.split(':', 2).last
+        end
+      end
+      role
+    end
+
+    def single_account?
+      if @single_account.nil?
+        @single_account = roles.map do |role|
+          role = role.id if role.respond_to?(:id)
+          role.split(':').first
+        end.uniq.size == 1
+      end
+      @single_account
+    end
+
+    def single_kind?
+      if @single_kind.nil?
+        return @single_kind = false unless single_account?
+        @single_kind = roles.map do |role|
+          role = role.id if role.respond_to?(:id)
+          role.split(':')[1]
+        end.uniq.size == 1
+      end
+      @single_kind
+    end
+
+    def dot_node v
+      id = node_id_for v
+      label = node_label_for v
+      "#{id} [label=\"#{label}\"]"
+    end
+
+    def dot_edge e
+      parent_id = node_id_for(e.parent)
+      child_id = node_id_for(e.child)
+      "#{parent_id} -> #{child_id}"
+    end
+
+    # an edge consisting of a parent & child, both of which are Conjur::Role instances
+    class Edge
+      attr_reader :parent
+      attr_reader :child
+
+      def initialize parent, child
+        @parent = parent
+        @child = child
+      end
+
+      def to_json short = false
+        as_json(short).to_json
+      end
+
+      def as_json short = false
+        short ? to_a : to_h
+      end
+
+      def to_h
+        # return string keys to make testing less brittle
+        {'parent' => @parent, 'child' => @child}
+      end
+
+      def to_a
+        [@parent, @child]
+      end
+
+      def to_s
+        "<Edge #{parent.id} --> #{child.id}>"
+      end
+
+      def hash
+        @hash ||= to_a.map(&:to_s).hash
+      end
+
+      def == other
+        other.kind_of?(self.class) and other.parent == parent and other.child == child
+      end
+
+      alias eql? ==
+    end
+
+  end
+end

data/lib/conjur-api/version.rb

@@ -19,6 +19,6 @@
 
 module Conjur
   class API
-    VERSION = "4.11.2"
+    VERSION = "4.12.0"
   end
 end

data/spec/api/graph_spec.rb

@@ -0,0 +1,102 @@
+require 'spec_helper'
+
+describe Conjur::Graph do
+  let(:edges){ [
+    [ 'a', 'b' ],
+    [ 'a', 'c'],
+    [ 'c', 'd'],
+    ['b', 'd'],
+    [ 'd', 'e'],
+    # make two connected components
+    ['o', 'q'],
+    ['x', 'o']
+  ]}
+  let(:hash_graph){ {'graph' => edges} }
+  let(:json_graph){ hash_graph.to_json }
+  let(:short_json_graph){ edges.to_json }
+  let(:long_edges){ edges.map{|e| {'parent' => e[0], 'child' => e[1]}} }
+  let(:long_hash_graph){ {'graph' => long_edges} }
+  let(:long_json_graph){ long_hash_graph.to_json }
+  let(:edge_objects){ edges.map{|e| Conjur::Graph::Edge.new(*e) }}
+
+  describe "json methods" do
+    subject{described_class.new edges}
+    it "converts to long json correctly" do
+      expect(subject.to_json).to eq(long_json_graph)
+      expect(subject.as_json).to eq(long_hash_graph)
+    end
+
+    it "converts to short json correctly" do
+      expect(subject.to_json(true)).to eq(short_json_graph)
+      expect(subject.as_json(true)).to eq(edges)
+    end
+  end
+
+  describe "#vertices" do
+    subject{Conjur::Graph.new(edges).vertices.to_set}
+    it "contains all unique members of edges" do
+      expect(subject.to_set).to eq(edges.flatten.uniq.to_set)
+    end
+  end
+
+  describe "#to_dot" do
+    let(:name){ nil }
+    subject{ Conjur::Graph.new(edges).to_dot(name) }
+    before do
+      File.write('/tmp/conjur-graph-spec.dot', subject)
+    end
+
+    let(:role_to_node_id) do
+      {}.tap do |h|
+        edges.flatten.uniq.each do |v|
+          expect(subject =~ /^\s*([a-z][0-9a-z_\-]*)\s*\[label\="(#{v})"\]/i).to be_truthy
+          h[$2] = $1
+        end
+      end
+    end
+
+    context "when given a name" do
+      let(:name){ 'foo' }
+      it "names the digraph" do
+        expect(subject).to match(/\A\s*digraph\s+foo\s*\{/)
+      end
+    end
+
+    it "defines all the vertices in the graph" do
+      edges.flatten.uniq.each do |v|
+        expect(subject).to match(/^\s*[a-z][0-9a-z_\-]*\s*\[label\="#{v}"\]/i)
+      end
+    end
+
+    it "defines all the edges in the graph" do
+      edges.each do |e|
+        parent_id = role_to_node_id[e[0]]
+        child_id  = role_to_node_id[e[1]]
+        expect(subject).to match(/^\s*#{parent_id}\s*\->\s*#{child_id}/)
+      end
+    end
+  end
+
+  describe "Graph.new" do
+    let(:arg){ edges }
+    subject{ described_class.new arg }
+    def self.it_accepts_the_argument
+      it "accepts the argument" do
+        expect(subject.edges.to_set).to eq(edge_objects.to_set)
+      end
+    end
+    describe "given an array of edges" do
+      it_accepts_the_argument
+    end
+
+    describe "given a hash of {'graph' => <array of edges>}" do
+      let(:arg){ hash_graph }
+      it_accepts_the_argument
+    end
+
+    describe "given a JSON string" do
+      let(:arg){ json_graph }
+      it_accepts_the_argument
+    end
+  end
+end

data/spec/api/roles_spec.rb

@@ -1,14 +1,85 @@
 require 'spec_helper'
 
 describe Conjur::API, api: :dummy do
+  subject { api }
+
+  describe 'role_graph' do
+    let(:roles){ [ 'acct:user:alice', 'acct:user:bob', 'acct:user:eve' ] }
+    let(:options){ {} }
+    let(:current_role){ 'some-role' }
+    let(:graph){
+      [
+          [ 'acct:user:alice', 'acct:user:eve' ],
+          [ 'acct:user:bob',   'acct:user:eve']
+      ]
+    }
+    let(:response){ {
+        graph: graph
+    }.to_json }
+
+    let(:graph_edges){
+      graph.map{|e| Conjur::Graph::Edge.new *e}
+    }
+
+    before do
+      allow(api).to receive(:current_role).and_return current_role
+    end
+
+    subject{ api.role_graph roles, options }
+
+    def role_graph_url_for roles, options, current_role
+      qs = options.reverse_merge(ancestors: true, descendants: true)
+             .merge(from_role: current_role, roles: roles).slice(:from_role, :ancestors, :descendants, :roles).to_query
+      "http://authz.example.com/#{account}/roles?#{qs}"
+    end
+
+    def expect_request_with_params params={}
+      expect(RestClient::Request).to receive(:execute)
+        .with(headers: credentials[:headers], method: :get, url: role_graph_url_for(roles, options, current_role))
+        .and_return(response)
+    end
+
+    it "gets /roles with the correct params" do
+      expect_request_with_params ancestors: true, descendants: true, from_role: current_role
+      subject
+    end
+
+    context "when options[:ancestors] and options[:descendants] are false" do
+      let(:options){ { ancestors: false, descendants: false } }
+      it "gets /roles with the correct params" do
+        expect_request_with_params ancestors: false, descendants: false, from_role: current_role
+        subject
+      end
+    end
+
+    context "when given options[:as_role] = 'foo'" do
+      it "sets the from_role param to 'foo'" do
+        expect_request_with_params from_role: 'foo'
+        subject
+      end
+    end
+
+    describe "the result" do
+      it "is a Conjur::Graph" do
+        expect_request_with_params
+        expect(subject).to be_kind_of(Conjur::Graph)
+      end
+      it "has the right edges" do
+        expect_request_with_params
+        expect(subject.edges.to_set).to eq(graph_edges.to_set)
+      end
+    end
+
+  end
+
   describe '#role_name_from_username' do
-    subject { api }
+
     before {
       allow(api).to receive(:username) { username }
     }
     context "username is" do
-      [ 
-        [ 'the-user', 'user:the-user' ], 
+      [
+        [ 'the-user', 'user:the-user' ],
         [ 'host/the-host', 'host:the-host' ],
         [ 'host/a/quite/long/host/name', 'host:a/quite/long/host/name' ],
         [ 'newkind/host/name', 'newkind:host/name' ],

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conjur-api
 version: !ruby/object:Gem::Version
-  version: 4.11.2
+  version: 4.12.0
 platform: ruby
 authors:
 - Rafal Rzepecki
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-22 00:00:00.000000000 Z
+date: 2015-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -232,6 +232,7 @@ files:
 - lib/conjur/escape.rb
 - lib/conjur/event_source.rb
 - lib/conjur/exists.rb
+- lib/conjur/graph.rb
 - lib/conjur/group.rb
 - lib/conjur/has_attributes.rb
 - lib/conjur/has_id.rb
@@ -254,6 +255,7 @@ files:
 - lib/conjur/variable.rb
 - reqspeed.rb
 - spec/api/authn_spec.rb
+- spec/api/graph_spec.rb
 - spec/api/groups_spec.rb
 - spec/api/hosts_spec.rb
 - spec/api/layer_spec.rb
@@ -317,6 +319,7 @@ test_files:
 - features/ping_as_server.feature
 - features/ping_as_user.feature
 - spec/api/authn_spec.rb
+- spec/api/graph_spec.rb
 - spec/api/groups_spec.rb
 - spec/api/hosts_spec.rb
 - spec/api/layer_spec.rb