conjur-api 4.14.0 → 4.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa094471717dc9bb39477d76468d2663895d9fd4
-  data.tar.gz: d688adf16203e25c50646994bc619170d5633b89
+  metadata.gz: 5364b2c4521be8b3f6b3fce20269873ac72a5ec8
+  data.tar.gz: e4e22c72cae8780bfe0263525156e5c57c0d5510
 SHA512:
-  metadata.gz: 434da500b0bb392deb9f0e8380dab357394aa2b16f28bb5063f2619a484646c1a1912267ee48eed7e3cea4d9e88ac256e23c466f6bd25faf1123294cce68af58
-  data.tar.gz: d9097541c2faff292c2f2c201a5b2d7dac162ca4c023b45d52093215acb310a17ce295762dc221d3a7c2952554c0efff59b911518853eea4282feca61648e330
+  metadata.gz: 982cbf720ebb14461e0868a0c8281d14a6561b5335004270780ff45e393fbe93f5ddd755b60c127ab90aedf9b3f051a01f16b1bcb2a733293cb7199ef4f1f766
+  data.tar.gz: 9fbb761715f485f823b20a4493a53a753bca25d1217632c126bc03ced49fab69bb81922bb132dbaebb49d2e81c901f8567c9c26683031448214101725e86aad1

data/.gitignore

@@ -23,3 +23,6 @@ tmp
 
 # rspec
 .rspec
+
+# Script to connect to jon's lxc appliances
+lxcsh.rb

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# v4.15.0
+ * Extensive documentation improvements
+ * A few additional methoods, for example `Conjur::API#public_key_names`.
+
 # v4.14.0
 
 * Bump rest-client version, remove the troublesome mime-types patch

data/lib/conjur-api/version.rb

@@ -19,6 +19,6 @@
 
 module Conjur
   class API
-    VERSION = "4.14.0"
+    VERSION = "4.15.0"
   end
 end

data/lib/conjur/acts_as_asset.rb

@@ -19,6 +19,7 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # A mixin used by Conjur asset classes such as {Conjur::User} and {Conjur::Group}.
   module ActsAsAsset
     include HasId
     include Exists
@@ -26,17 +27,57 @@ module Conjur
     include ActsAsResource
     include HasAttributes
 
-      
+    # Add an internal grant on this asset's resource.  This method allows you to grant permissions on all members of
+    # a container asset (for example, all hosts in a layer) to the given role.  Currently this method
+    # is only useful for `layer` assets, and corresponds to the
+    # {http://developer.conjur.net/reference/services/directory/layer/hosts-permit.html `hosts permit`} CLI
+    # command.  In particular, to permit `'update'` on all hosts in a layer, `role_name` should be
+    # `'admin_host'`, and to permit `'execute'` it should be `'use_host'`.
+    #
+    # @example Allow group 'ops' to admin hosts in the 'dev/database' layer
+    #   ops = api.create_group 'ops'
+    #   dev_database = api.create_layer 'dev/database'
+    #
+    #   # Create and add a host to the databasees layer
+    #   host = api.create_host 'ec2/i-123ab23f'
+    #   dev_databases.add_host host
+    #
+    #   # Ops can't update the hosts
+    #   host.resource.permitted? 'update', acting_as: 'conjur:group:ops'
+    #   # => false
+    #
+    #   # Allow 'group:ops' to admin all hosts in the layer
+    #   layer.add_member 'admin_host', ops
+    #
+    #   # Now 'group:ops' is allowed to `'update'` the role.`
+    #   host.resource.permitted? 'update', acting_as: 'group:ops'
+    #   # => true
+    #
+    # @param [String] role_name name of the internal role to grant (for layers, it must be `'use_host'` or `'admin_host'`)
+    # @param [String, #roleid] member the role to receive the grant
+    # @param [Hash] options Unused, included for backwards compatibility
+    # @return [void]
     def add_member(role_name, member, options = {})
       owned_role(role_name).grant_to member, options
     end
-    
+
+    # Remove a grant created with {#add_member}.  When an internal grant has been created on this asset's resource
+    # with {#add_member}, you can remove it with this method.
+    #
+    # @see #add_member
+    # @param [String] role_name name of the internal grant role (for layers, it must be `'use_host'` or `'admin_host'`).
+    # @param [String, #roleid] member the role to remove
+    # @return [void]
     def remove_member(role_name, member)
       owned_role(role_name).revoke_from member
     end
     
     protected
-    
+
+    # Return the internal role for an add/remove member grant.
+    #
+    # @param [String] role_name the name of the internal role
+    # @return [Conjur::Role] the internal role
     def owned_role(role_name)
       tokens = [ resource_kind, resource_id, role_name ]
       grant_role = [ core_conjur_account, '@', tokens.join('/') ].join(':')

data/lib/conjur/acts_as_resource.rb

@@ -23,34 +23,83 @@ require 'active_support/dependencies/autoload'
 require 'active_support/core_ext'
 
 module Conjur
+
+  # This module is included in asset classes that have an associated resource.
   module ActsAsResource
+    # Return the {Conjur::Resource} associated with this asset.
+    #
+    # @return [Conjur::Resource] the resource associated with this asset
     def resource
       require 'conjur/resource'
       # NOTE: should we use specific class to build sub-url below?
       Conjur::Resource.new(Conjur::Authz::API.host, self.options)[[ core_conjur_account, 'resources', path_escape(resource_kind), path_escape(resource_id) ].join('/')]
     end
-    
+
+    # Return the *qualified* id of the resource associated with this asset.
+    #
+    # @return [String] the qualified id of the resource associated with this asset.
     def resourceid
       [ core_conjur_account, resource_kind, resource_id ].join(':')
     end
-    
+
+    # The kind of resource underlying the asset.  The kind is the second token in
+    # a Conjur id like `"account:kind:id"`.
+    #
+    # @see Conjur:Resource#kind
+    # @return [String] the resource kind for the underlying resource
     def resource_kind
       self.class.name.split("::")[-1].underscore.split('/').join('-')
     end
 
+    # @api private
+    #
+    # Confusingly, this method returns the *unqualified* resource id, as opposed to the *qualified*
+    # resource id returned by {#resourceid}.
+    #
+    # @return [String] the *unqualified* resource id.
     def resource_id
       id
     end
 
+    # @api private
+    # Delete a resource
+    # This doesn't typically work ;-)
+    # @return [void]
     def delete
       resource.delete
       super
     end
-    
+
+    # Permit `role` to perform `privilege` on this resource.  A
+    # {http://developer.conjur.net/reference/services/authorization/permission.html permission} represents an ability
+    # to perform certain (application defined) actions on this resource.
+    #
+    # This method is equivalent to calling `resource.permit`.
+    #
+    # @example Allow a group and its members to get the value of a Conjur variable
+    #   group = api.group 'some-project/developers'
+    #   variable = api.variable 'some-project/development/postgres-uri'
+    #   variable.permit 'execute', group
+    #
+    # @see Conjur::Resource#permit
+    # @param [String] privilege the privilege to grant
+    # @param [String, #roleid] role the role to which the privilege is granted
+    # @param options [Hash, nil] options to pass through to `RestClient::Resource#post`
+    # @return [void]
+    # @raise [RestClient::Forbidden] if you don't have permission to perform this operation.
     def permit(privilege, role, options = {})
       resource.permit privilege, role, options
     end
-    
+
+
+    # Deny `role` permission to perform actions corresponding to `privilege` on the underlying resource.
+    #
+    # @see Conjur::Resource#deny
+    # @param privilege [String, #each] A permission name or an `Enumerable` of permissions to deny.  In the
+    #   later, all permissions will be denied.
+    # @param role [String, :roleid] A full role id or a role-ish object whose permissions we will deny.
+    #
+    # @return [void]
     def deny(privilege, role)
       resource.deny privilege, role
     end

data/lib/conjur/acts_as_user.rb

@@ -19,17 +19,27 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
+  # This module provides methods for things that are like users (specifically, those that have
+  # api keys).
   module ActsAsUser
-    def self.included(base)
-      base.instance_eval do
-        include ActsAsRole
-      end
-    end
-    
+    include ActsAsRole
+
+    # Returns a newly created user's api_key.
+    #
+    # @note this method can only be called on newly created user-like things (those returned from, for example,)
+    #   {Conjur::API#create_user}.
+    #
+    # @return [String] the api key
+    # @raise [Exception] when the object isn't newly created.
     def api_key
       attributes['api_key'] or raise "api_key is only available on a newly created #{self.class.name.downcase}"
     end
-    
+
+    # Create an api logged in as this user-like thing.
+    #
+    # @note As with {#api_key}, this method only works on newly created instances.
+    # @see #api_key
+    # @return [Conjur::API] an api logged in as this user-like thing.
     def api
       Conjur::API.new_from_key login, api_key
     end

data/lib/conjur/annotations.rb

@@ -17,7 +17,9 @@
 # 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.
-#
+
+require 'forwardable'
+
 module Conjur
   # Conjur allows {http://developer.conjur.net/reference/services/authorization/resource Resource}
   #   instances to be {http://developer.conjur.net/reference/services/authorization/resource/annotate.html annotated}
@@ -69,6 +71,49 @@ module Conjur
       self
     end
 
+    # Return a *copy* of the annotation values
+    #
+    # @example Changing values has no effectannotations_hash
+    #   resource.annotations.values ["Some Value"]
+    #   resource.annotations.values.each do |v|
+    #     v << "HI"
+    #   end
+    #   resource.annotations.values # => ["Some Value"]
+    #
+    #    # Notice that this is different from ordinary Hash behavior
+    #    h = {"Some Key" => "Some Value"}
+    #    h.values.each do |v|
+    #       v << "HI"
+    #    end
+    #    h.values # "Some ValueHI"
+    #
+    # @example Show the values of a resources annotations
+    #   resource.annotations # => {'Name' => 'The Best Resource EVAR',
+    #                        #  'Story' => 'The Coolest!' }
+    #   resource.annotations.values # => ['The Best Resource EVAR', 'The Coolest!']
+    #
+    # @return [Array<String>] the annotation values
+    def values
+      annotations_hash.values.map(&:dup)
+    end
+
+    # Return the annotation names.
+    #
+    # This has exactly the same behavior as {Hash#keys}, in that the
+    # returned keys are immutable, and modifications to the array have no
+    # effect.
+    #
+    # @return [Array<String, Symbol>] the annotation names
+    def keys
+      annotations_hash.keys
+    end
+    alias names keys
+
+    def to_a
+      to_h.to_a
+    end
+
+
     # Set annotations from key,value pairs in `hash`.
     #
     # @note this is currently no more efficient than setting each
@@ -77,7 +122,9 @@ module Conjur
     # @param [Hash, #each] hash
     # @return [Conjur::Annotations] self
     def merge! hash
-      hash.each{|k,v| self[k] = v }
+      hash.each do |k, v|
+        self[k] = v unless self[k] == v
+      end
       self
     end
     
@@ -118,7 +165,6 @@ module Conjur
         RestClient::Resource.new(Conjur::Authz::API.host, @resource.options)[path].put name: name, value: value
       end
     end
-
     # @api private
     # Our internal {Hash} of annotations.  Lazily loaded.
     def annotations_hash

data/lib/conjur/api.rb

@@ -60,18 +60,42 @@ class RestClient::Resource
     }
   end
   
+  # @api private
+  # @deprecated
+  # The account used by the core service.  This  is deprecated in favor of {Conjur.account} and
+  # {Conjur::Configuration#account}.
+  # @return [String] the core account
   def core_conjur_account
     Conjur::Core::API.conjur_account
   end
-  
+
+  # @api private
+  # This method exists so that all {RestClient::Resource}s support JSON serialization.  It returns an
+  # empty hash.
+  # @return [Hash] the empty hash
   def to_json(options = {})
     {}
   end
-  
+
+  # Creates a Conjur API from this resource's authorization header.
+  #
+  # The new API is created using the token, so it will not be able to refresh
+  # when the token expires (after about 8 minutes).  This is equivalent to creating
+  # an {Conjur::API} instance with {Conjur::API.new_from_token}.
+  #
+  # @return {Conjur::API} the new api
   def conjur_api
     Conjur::API.new_from_token token
   end
-  
+
+  # Get an authentication token from the clients Authorization header.
+  #
+  # Useful fields in the token include `"data"`, which holds the username for which the
+  # token was issued, and `"timestamp"`, which contains the time at which the token was issued.
+  # The token will expire 8 minutes after timestamp, but we recommend you treat the lifespan as
+  # about 5  minutes to account for time differences.
+  #
+  # @return [Hash] the parsed authentication token
   def token
     authorization = options[:headers][:authorization]
     if authorization && authorization.to_s[/^Token token="(.*)"/]
@@ -81,6 +105,9 @@ class RestClient::Resource
     end
   end
 
+  # The username this resource authenticates as.
+  #
+  # @return [String] the username
   def username
     options[:user] || options[:username]
   end

data/lib/conjur/api/deputies.rb

@@ -22,10 +22,34 @@ require 'conjur/deputy'
 
 module Conjur
   class API
+    #@!group Directory: Deputies
+
+    # @api internal
+    #
+    # Create a Conjur deputy.
+    #
+    # Deputies are used internally by Conjur services that need to perform
+    # actions as a particular role.  While the deputies API is stable,
+    # it isn't intended for use by end users.
+    #
+    # @param [Hash] options options for deputy creation
+    # @option options [String] :id the *unqualified* id for the new deputy.  If not present,
+    #   the deputy will be given a randomly generated id.
+    # @return [Conjur::Deputy] the new deputy
+    # @raise [RestClient::Conflict] if a deputy already exists with the given id.
     def create_deputy options = {}
       standard_create Conjur::Core::API.host, :deputy, nil, options
     end
-    
+
+    # @api internal
+    #
+    # Find a Conjur deputy by id.
+    # Deputies are used internally by Conjur services that need to perform
+    # actions as a particular role.  While the deputies API is stable,
+    # it isn't intended for use by end users.
+    #
+    # @param [String] id the deputy's *unqualified* id
+    # @return [Conjur::Deputy] the deputy, which may or may not exist.
     def deputy id
       standard_show Conjur::Core::API.host, :deputy, id
     end

data/lib/conjur/api/resources.rb

@@ -22,18 +22,122 @@ require 'conjur/resource'
 
 module Conjur
   class API
+
+    #@!group Authorization: Resources
+
+    # Create a {http://developer.conjur.net/reference/services/authorization/resource Conjur Resource}.
+    # Resources are entities on which roles have permissions.  A resource might represent a secret, a
+    # web service route, or be part of a higher level construct such as a user or group.
+    #
+    # If `:acting_as` is not present in `options`, you will be the owner of the new role.  If it is present,
+    # your role must be a member of the given role (see {Conjur::Role#member_of?}).
+    #
+    # @example Create an abstract resource to represent a web service route
+    #   # Notice that we can omit the account in the identifier
+    #   service_resource = api.create_resource 'web-service:list-gadgets'
+    #   service_resource.resource_id # => 'conjur:web-service:list-gadgets'
+    #
+    #   # In a gatekeeper for the web service, we can use the resource to control access
+    #   get '/gadgets' do
+    #     # We'll assume that we've verified the Conjur authn token in the request, and stored the
+    #     # corresponding identifier in `request_role_id`
+    #     halt(403) unless api.resource('conjur:web-service:list-gadgets').permitted? 'read', request_role_id
+    #     render_json find_gadgets
+    #   end
+    #
+    # @example Create a role owned by another role
+    #   alice = api.role('user:alice')
+    #   api.current_role.member_of? alice # true, the operation will fail if this is false
+    #   res = api.create_resource 'example:owned', acting_as: 'user:alice'
+    #   res.owner # "conjur:user:alice"
+    #
+    # @param [String] identifier an id of the form `"<account>:<kind>:<id>"` or `"<kind>:<id>"`
+    # @param options [Hash] options for the request
+    # @option options [String, #role_id] :acting_as the role-ish thing or role id that will own the new resource
+    # @return [Conjur::Role] the new role
     def create_resource(identifier, options = {})
       resource(identifier).tap do |r|
         r.create(options)
       end
     end
-    
-    def resource resource
-      Resource.new(Conjur::Authz::API.host, credentials)[self.class.parse_resource_id(resource).join('/')]
+
+    # Find a resource by it's id.  The id given to this method must be qualified by a kind, but the account is
+    # optional.
+    #
+    # ### Permissions
+    #
+    # The resource **must** be visible to the current role.  This is the case if the current role is the owner of
+    # the resource, or has any privilege on it.
+    #
+    # @example Find or create a resource
+    #    def find_or_create_resource resource_id
+    #       resource = api.resource resource_id
+    #       unless resource.exists?
+    #         resource = api.create_resource resource_id
+    #       end
+    #       resource
+    #     end
+    #
+    #     # ...
+    #     example_resource = find_or_create_resource 'example:find-or-create'
+    #     example_resource.exists? # always true
+    #
+    # @param identifier [String] a qualified resource identifier, optionally including an account
+    # @return [Conjur::Resource] the resource, which may or may not exist
+     def resource identifier
+      Resource.new(Conjur::Authz::API.host, credentials)[self.class.parse_resource_id(identifier).join('/')]
     end
 
-    # Return all visible resources.
-    # In opts you should pass an account to filter by, and optionally a kind.
+    # Find all resources visible to the current role that match the given search criteria.
+    #
+    # ## Full Text Search
+    # Conjur supports full text search over the identifiers and annotation *values*
+    # of resources.  For example, if `opts[:search]` is `"pubkeys"`, any resource with
+    # an id containing `"pubkeys"` or an annotation whose value contains `"pubkeys"` will match.
+    #
+    # **Notes**
+    #   * Annotation *keys* are *not* indexed for full text search.
+    #   * Conjur indexes the content of ids and annotation values by word.
+    #   * Only resources visible to the current role (either owned by that role or
+    #       having a privilege on it) are returned.
+    #   * If you do not provide `:offset` or `:limit`, all records will be returned. For systems
+    #       with a huge number of resources, you may want to paginate as shown in the example below.
+    #   * If `:offset` is provided and `:limit` is not, 10 records starting at `:offset` will be
+    #       returned.  You may choose an arbitrarily large number for `:limit`, but the same performance
+    #       considerations apply as when omitting `:offset` and `:limit`.
+    #
+    # @example Search for resources annotated with the text "WebService Route"
+    #    webservice_routes = api.resources search: "WebService Route"
+    #
+    #    # Check that it worked:
+    #    webservice_routes.each do |resource|
+    #       searchable = [resource.annotations.to_h.values, resource.resource_id]
+    #       raise "FAILED" unless searchable.flatten.any?{|s| s.include? "WebService Route"}
+    #    end
+    #
+    # @example Restrict the search to 'group' resources
+    #   groups = api.resources kind: 'group'
+    #
+    #   # Correct behavior:
+    #   expect(groups.all?{|g| g.kind == 'group'}).to be_true
+    #
+    #
+    # @example Get every single resource in a performant way
+    #   resources = []
+    #   limit = 25
+    #   offset = 0
+    #   until (batch = api.resources limit: limit, offset: offset).empty?
+    #     offset += batch.length
+    #     resources.concat results
+    #   end
+    #   # do something with your resources
+    #
+    # @param opts [Hash] search criteria
+    # @option opts [String]   :search find resources whose ids or annotations contain this string
+    # @option opts [String]   :kind find resources whose `kind` matches this string
+    # @option opts [Integer]  :limit the maximum number of records to return (Conjur may return fewer)
+    # @option opts [Integer]  :offset offset of the first record to return
+    # @return [Array<Conjur::Resource>] the resources matching the criteria given
     def resources opts = {}
       opts = { host: Conjur::Authz::API.host, credentials: credentials }.merge opts
       opts[:account] ||= Conjur.account