conjur-api 4.31.0 → 5.0.0.rc1

data/lib/conjur/group.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2013-2015 Conjur Inc.
+# Copyright 2013-2017 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
@@ -19,73 +19,17 @@
 #
 module Conjur
 
-  # A Conjur {http://developer.conjur.net/reference/services/directory/group Group} represents a collection of
-  #   Conjur {http://developer.conjur.net/reference/services/directory/user Users}.
-  #   This class represents Conjur group assets and operations on them.
+  # A Conjur Group represents a collection of Conjur Users, Groups and Layers.
   #
-  # You should not create instances of this class directly.  Instead, you can get them from
-  # API methods like {Conjur::API#group} and {Conjur::API#groups}.
-  #
-  class Group < RestClient::Resource
-    include ActsAsAsset
-    include ActsAsRole
-
-    # Add a user to the group or change whether an existing member can manage other members.
-    #
-    # @example
-    #   # create an empty group
-    #   group = api.create_group 'hoommans'
-    #   # put a user in the group, with the ability to manage members
-    #   group.add_member 'conjur:user:bob', admin_option: True
-    #   # Hmm, bob is getting a little suspicious, better lower his privileges.
-    #   group.add_member 'conjur:user:bob', admin_option: False
-    #
-    #   # Notice that this method is idempotent:
-    #   group.add_member 'alice'
-    #   group.add_member 'alice' # Does nothing, alice is already a member
-    #
-    #
-    # @param [String, Conjur::User, Conjur::Role] member the member to add.  If a String is given, it must
-    #   be a *fully qualified* Conjur id.
-    # @param [Hash] options
-    # @option options [Boolean] :admin_option (False) determines whether the member is able to manage members
-    #   of this group.
-    # @return [void]
-    def add_member(member, options = {})
-      role.grant_to member, options
-    end
-
-    # Remove a member from this group.
-    #
-    # ### Notes
-    # *  Unlike {#add_member}, this method is *not* idempotent.
-    #   This means that calling it twice with the same user will raise a `RestClient::ResourceNotFound`
-    #   exception.
-    # * The member may be represented as a *qualified* conjur id or a {Conjur::User} instance.  Although
-    #   it will accept anything that responds to `#roleid`, the behavior when adding or removing a non-user
-    #   role is **undefined**.
-    #
-    # @example
-    #   group = api.group 'admins'
-    #   group.add_member 'bob'
-    #   group.remove_member 'bob' # OK, bob is a member
-    #   group.remove_member 'bob' # raises RestClient::ResourceNotFound
-    #
-    # @param [String, Conjur::User,Conjur::Role] member
-    # @return [void]
-    # @raise [RestClient::ResourceNotFound] when you try to remove a user who is not a member of the group.
-    def remove_member(member)
-      role.revoke_from member
-    end
+  class Group < BaseObject
+    include ActsAsRolsource
 
-    # Update group properties.  Currently the only supported property is `:gidnumber`.
+    # Get the group's gidnumber, which can be used by LDAP and SSH login, among other things.
     #
-    # @param [Hash] props new property values
-    # @option props [Integer] :gidnumber new GID number
-    # @return [void]
-    def update props
-      # not an alias because doc
-      put props
+    # @return [Fixnum] the gidnumber
+    # @raise [RestClient::Forbidden] if you don't have permission to `show` the group.
+    def gidnumber
+      annotation_value 'conjur/gidnumber'
     end
   end
 end

data/lib/conjur/has_attributes.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013 Conjur Inc
+# Copyright 2013-2017 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
@@ -23,13 +23,16 @@ module Conjur
   # methods on specific asset classes (for example, {Conjur::Resource#owner}), the are available as
   # a `Hash` on all types supporting attributes.
   module HasAttributes
-    # Returns this objects {#attributes}.  This is primarily to support
-    # simple JSON serialization of Conjur assets.
-    #
-    # @param options [Hash,nil] unused, kept for compatibility reasons
-    # @see #attributes
-    def to_json(options = {})
-      attributes
+    def as_json options={}
+      result = super(options)
+      if @attributes
+        result.merge!(@attributes.as_json(options))
+      end
+      result
+    end
+    
+    def to_s
+      to_json.to_s
     end
 
     # @api private
@@ -38,15 +41,8 @@ module Conjur
     # @return [Hash] the new attributes
     def attributes=(attributes); @attributes = attributes; end
 
-    # Get the attributes for this asset.
-    #
-    # Although the `Hash` returned by this method is mutable, you should treat as immutable unless you know
-    # exactly what you're doing.  Each asset's attributes are constrained by a server side schema, which means
-    # that you will get an error if you violate the schema. and then try to save the asset.
-    #
-    #
-    # @note this method will use a cached copy of the objects attributes instead of fetching them
-    # with each call.  To ensure that the attributes are fresh, you can use the {#refresh} method
+    # Get the attributes for this asset. This is an immutable Hash, unless the attributes
+    # are changed via policy update.
     #
     # @return [Hash] the asset's attributes.
     def attributes
@@ -54,45 +50,6 @@ module Conjur
       fetch
     end
 
-
-    # Update this asset's attributes on the server.
-    #
-    #
-    # @note If the objects attributes haven't been fetched (for example, by calling {#attributes}),
-    #   this method is a no-op.
-    #
-    # Although you can manipulate an assets attributes and then call {#save}, the attributes are constrained
-    # by a server side schema, and attempting to set an attribute that doesn't exist will result in
-    # a 422 Unprocessable Entity error.
-    #
-    # If you want to set arbitrary metadata on an asset, you might consider using the {Conjur::Resource#tags}
-    # method instead.
-    #
-    # @return [void]
-    def save
-      if @attributes
-        self.put(attributes.to_json)
-      end
-    end
-    
-    # Reload this asset's attributes. This method can be used to guarantee a current view of the entity in the case
-    # that it has been modified by an update method or by an external party.
-    #
-    # @note any changes to {#attributes} without a call to #save will be overwritten by this method.
-    #
-    # @example
-    #   res = api.resources.firs
-    #   res.attributes # => {  ... }
-    #   res.attributes['hello'] = 'blah'
-    #   res.refresh
-    #   res.attributes['hello'] # => nil
-    #
-    #
-    # @return [Hash] the asset's attributes.
-    def refresh
-      fetch
-    end
-
     # Call a block that will perform actions that might change the asset's attributes.
     # No matter what happens in the block, this method ensures that the cached attributes
     # will be invalidated.
@@ -106,18 +63,24 @@ module Conjur
       @attributes = nil
     end
 
+
     protected
 
+    def annotation_value name
+      (attributes['annotations'].find{|a| a['name'] == name} || {})['value']
+    end
+
     # @api private
     # Fetch the attributes, overwriting any current ones.
     def fetch
       @attributes ||= fetch_attributes
     end
 
-    def fetch_attributes # :nodoc:
-      cache_key = Conjur.cache_key self.username, self.url
+    # @api private
+    def fetch_attributes
+      cache_key = Conjur.cache_key username, rbac_resource_resource.url
       Conjur.cache.fetch_attributes cache_key do
-        JSON.parse(get.body)
+        JSON.parse(rbac_resource_resource.get.body)
       end
     end
   end

data/lib/conjur/host.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013-2015 Conjur Inc
+# Copyright 2013-2017 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
@@ -19,39 +19,9 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
-  # This class represents a {http://developer.conjur.net/reference/services/directory/host
-  # Conjur Host} asset.  You should not create {Conjur::Host} instances directly, but use {Conjur::API}
-  # methods such as {Conjur::API#create_host} and {Conjur::API#host}.
-  class Host < Deputy
-
-    # @api private
-    # @deprecated
-    #
-    # This method was used before conjurize came along.  It's no longer in use.
-    def enrollment_url
-      log do |logger|
-        logger << "Fetching enrollment_url for #{id}"
-      end
-      self['enrollment_url'].head{|response, request, result| response }.headers[:location]
-    end
-
-    # Assign new attributes to the host.  Currently, this method only lets you change the
-    # `:cidr` attribute.
-    #
-    # ### Permissions
-    # You must have update permission on the hosts's resource or be the host to
-    # update CIDR restrictions.
-    #
-    # @note This feature requires Conjur server version 4.6 or later.
-    #
-    # @param [Hash] options attributes to change
-    # @option options [Array<String, IPAddr>] :cidr the network restrictions for this host
-    # @return [void]
-    # @raise [ArgumentError] if cidr isn't valid
-    def update options
-      if cidr = options[:cidr]
-        set_cidr_restrictions cidr
-      end
-    end
+  # This class represents a Conjur Host. Hosts are created in Conjur policy, or with
+  # {Conjur::HostFactory}.
+  class Host < BaseObject
+    include ActsAsUser
   end
 end

data/lib/conjur/host_factory.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2014 Conjur Inc
+# Copyright 2013-2017 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
@@ -21,54 +21,54 @@
 require 'conjur/host_factory_token'
 
 module Conjur
-  class HostFactory < RestClient::Resource
-    include ActsAsAsset
+  # A Host Factory is a way to allow clients to create Conjur hosts without giving them
+  # any other access to Conjur.
+  #
+  # Each Host Factory can have 0 or more tokens, each of which is a random string that
+  # has an associated expiration and optional CIDR restriction. A user or machine who has
+  # a host factory token can use it to create new hosts, or to rotate the API keys of 
+  # existing hosts.
+  #
+  # @see API#host_factory_create_host
+  # @see HostFactoryToken
+  class HostFactory < BaseObject
+    include ActsAsRolsource
     
-    def roleid
-      attributes['roleid']
-    end
-    
-    def role
-      Role.new(Conjur::Authz::API.host, self.options)[Conjur::API.parse_role_id(roleid).join('/')]
-    end
-    
-    def deputy
-      Conjur::Deputy.new(Conjur::API.core_asset_host, options)["deputies/#{fully_escape id}"]
-    end
-
-    def deputy_api_key
-      attributes['deputy_api_key']
-    end
-    
-    def create_token(expiration, options = {})
-      create_tokens(expiration, 1, options)[0]
+    # Create one or more host factory tokens. Each token can be used to create
+    # hosts, using {API#host_factory_create_host}. 
+    #
+    # @param expiration [Time] the future time at which the token will stop working.
+    # @param count [Integer] the number of (identical) tokens to create (default: 1).
+    # @param cidr [String] a CIDR restriction on the usage of the token.
+    # @return [Array<HostFactoryToken>] the token or tokens.
+    def create_tokens expiration, count: 1, cidr: nil
+      options = {}
+      options[:expiration] = expiration.iso8601
+      options[:host_factory] = id
+      options[:count] = count
+      options[:cidr] = cidr if cidr
+      response = JSON.parse core_resource['host_factory_tokens'].post(options)
+      response.map do |data|
+        HostFactoryToken.new data, credentials
+      end
     end
     
-    def create_tokens(expiration, count, options = {})
-      parameters = options.merge({
-        expiration: expiration.iso8601,
-        count: count
-      })
-      response = RestClient::Resource.new(Conjur::API.host_factory_asset_host, self.options)[fully_escape id]["tokens"].post(parameters).body
-      JSON.parse(response).map do |attrs|
-        build_host_factory_token attrs
-      end
+    # Create a new token.
+    #
+    # @see #create_tokens
+    def create_token expiration, cidr: nil
+      create_tokens(expiration, cidr: cidr).first
     end
 
+    # Enumerate the tokens on the host factory.
+    #
+    # @return [Array<HostFactoryToken>] the token or tokens.
     def tokens
       # Tokens list is not returned by +show+ if the caller doesn't have permission
       return nil unless self.attributes['tokens']
 
-      self.attributes['tokens'].collect do |attrs|
-        build_host_factory_token attrs
-      end
-    end
-    
-    protected
-    
-    def build_host_factory_token attrs
-      Conjur::HostFactoryToken.new(Conjur::API.host_factory_asset_host, self.options)["tokens"][attrs['token']].tap do |token|
-        token.attributes = attrs
+      self.attributes['tokens'].collect do |data|
+        HostFactoryToken.new data, credentials
       end
     end
   end

data/lib/conjur/host_factory_token.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2014 Conjur Inc
+# Copyright 2013-2017 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
@@ -19,45 +19,60 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
-  class HostFactoryToken < RestClient::Resource
-    include HasAttributes
+  class HostFactoryToken
+    def initialize data, credentials
+      @data = data
+      @credentials = credentials
+    end
     
+    # Convert the object to JSON.
+    #
+    # Fields:
+    #
+    # * token
+    # * expiration
+    # * cidr
     def to_json(options = {})
       { token: token, expiration: expiration, cidr: cidr }
     end
   
+    # Format the token as a string, using JSON format.
+    def to_s
+      to_json.to_s
+    end
+  
+    # Gets the token string.
+    #
+    # @return [String]
     def token
-      self.url.split('/')[-1]
+      @data['token']
     end    
     
-    alias id token
-    
+    # Gets the expiration.
+    #
+    # @return [DateTime]
     def expiration
-      DateTime.iso8601(attributes['expiration'])
+      DateTime.iso8601(@data['expiration'])
     end
     
-    def host_factory
-      Conjur::HostFactory.new(Conjur::API.host_factory_asset_host, options)[fully_escape attributes['host_factory']['id']]
-    end
-
+    # Gets the CIDR restriction.
+    #
+    # @return [String]
     def cidr
-      attributes['cidr']
+      @data['cidr']
     end
 
-    def revoke!
-      invalidate do
-        RestClient::Resource.new(self['revoke'].url, options).post
-      end
+    # Revokes the token, after which it cannot be used any more.
+    def revoke
+      Conjur::API.revoke_host_factory_token @credentials, token
     end
 
-    def save
-      raise "HostFactoryToken attributes are not updatable"
+    def ==(other)
+      other.class == self.class &&
+        other.token == self.token &&
+        other.expiration == self.expiration &&
+        other.cidr == self.cidr
     end
 
-    protected
-    
-    def fetch
-      raise "HostFactoryToken attributes are not fetchable"
-    end
   end
 end

data/lib/conjur/id.rb

@@ -0,0 +1,63 @@
+#
+# Copyright 2013-2017 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
+  # Encapsulates a Conjur id, which consists of account, kind, and identifier.
+  class Id
+    attr_reader :id
+    
+    def initialize id
+      @id = id
+    end
+    
+    # The organization account, obtained from the first component of the id.
+    def account; id.split(':', 3)[0]; end
+    # The object kind, obtained from the second component of the id.
+    def kind; id.split(':', 3)[1]; end
+    # The object identifier, obtained from the third component of the id. The
+    # identifier must be unique within the `account` and `kind`.
+    def identifier; id.split(':', 3)[2]; end
+    
+    # Defines id equivalence using the string representation.
+    def == other
+      if other.is_a?(String)
+        to_s == other
+      else
+        super
+      end
+    end
+
+    # @return [String] the id string.
+    def as_json options={}
+      @id
+    end
+
+    # Splits the id into 3 components, and then joins them with a forward-slash `/`.
+    def to_url_path
+      id.split(':', 3).join('/')
+    end
+    
+    # @return [String] the id string
+    def to_s
+      id
+    end
+  end
+end

data/lib/conjur/layer.rb

@@ -1,84 +1,9 @@
 module Conjur
 
-  # A {http://developer.conjur.net/reference/services/directory/layer Conjur Layer}
-  # represents a collection of
-  # {http://developer.conjur.net/reference/services/directory/host Conjur Hosts} with the
-  # ssame permissions on other Conjur resources.
-  #
-  # @example Allow hosts in the layer `dev/database` to access a `dev/database_uri` secret
-  #   # Create the layer and add a couple of EC2 hosts
-  #   layer = api.create_layer 'dev/database'
-  #   hosts = ['ec2-iac5ed', 'ec2-iadc31'].map{ |hostid| api.create_host id: hostid }
-  #   hosts.each{ |host| layer.add_host host }
-  #
-  #   # A Variable representing the database uri secret
-  #   database_uri  = api.variable 'dev/database_uri'
-  #
-  #   # Currently none of the hosts can access it:
-  #   hosts.any?{ |host| host.role.permitted? database_uri, 'execute' } # => false
-  #
-  #   # Grant permission on the layer
-  #   database_uri.resource.permit 'execute', layer
-  #
-  #   # Now all hosts in the layer have the execute permission on the secret through the layer
-  #   hosts.all?{ |host| host.role.permitted? database_uri, 'execute' } # => true
-  #
-  class Layer < RestClient::Resource
-    include ActsAsAsset
-    include ActsAsRole
-
-    # Add a host to this layer.  The host's role will become a member of the layer's role, and have
-    # all privileges of the layer.
-    #
-    # @param [String, Conjur::Host] hostid A *qualified* Conjur id for the host, or a {Conjur::Host} instance.
-    # @return [void]
-    def add_host(hostid)
-      hostid = cast(hostid, :roleid)
-      log do |logger|
-        logger << "Adding host #{hostid} to layer #{id}"
-      end
-      invalidate do
-        RestClient::Resource.new(self['hosts'].url, options).post(hostid: hostid) 
-      end
-    end
-
-    # Remove a host from this layer.  The host will lose all privileges it had through this
-    # layer.
-    #
-    # @param [String, Conjur::Host] hostid A *qualified* Conjur id for the host, or a {Conjur::Host} instance.
-    # @return [void]
-    def remove_host(hostid)
-      hostid = cast(hostid, :roleid)
-      log do |logger|
-        logger << "Removing host #{hostid} from layer #{id}"
-      end
-      invalidate do
-        RestClient::Resource.new(self["hosts/#{fully_escape hostid}"].url, options).delete
-      end
-    end
-    
-    # Lists the roles that have been granted access to the host's owned roles.
-    #
-    # `role_name` can be either `admin_host` or `use_host`.  This method corresponds
-    # to {Conjur::ActsAsAsset#add_member} in that members added with that method
-    # will be returned by this method.
-    #
-    # @param [String] role_name Either `use_host` or `admin_host`
-    # @return [Conjur::RoleGrant] the grants associated with this host (the return type
-    #   is identical to that of {Conjur::Role#members}).
-    # @see Conjur::ActsAsAsset#add_member
-    def hosts_members(role_name)
-      owned_role(role_name).members
-    end
-
-
-    # Return all hosts in the layer.
-    #
-    # @return [Array<Conjur::Host>] the hosts in the layer.
-    def hosts
-      self.attributes['hosts'].collect do |id|
-        Conjur::Host.new(Conjur::API.core_asset_host, options)["hosts/#{fully_escape id.split(':', 3)[-1]}"]
-      end
-    end
+  # A Conjur Layer is a type of role whose members are Conjur Hosts. The hosts inherit
+  # permissions from the layer. Automatic roles on the layer can also be used to manage
+  # SSH permissions to the hosts.
+  class Layer < BaseObject
+    include ActsAsRolsource
   end
 end

data/lib/conjur/log.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013 Conjur Inc
+# Copyright 2013-2017 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

data/lib/conjur/log_source.rb

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013 Conjur Inc
+# Copyright 2013-2017 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

data/lib/conjur/{secret.rb → policy.rb}

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2013 Conjur Inc
+# Copyright 2013-2017 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
@@ -19,19 +19,16 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
-  # @api private
-  #
-  # Secrets are primitive encrypted values upon which {Conjur::Variable}s are built.
-  # You probably want to use {Conjur::Variable} instead.
-  class Secret < RestClient::Resource
-    include ActsAsAsset
 
-    # @api private
-    # Return the value of the secret
-    #
-    # @return [String] the value stored by this secret
-    def value
-      self['value'].get.body
-    end
+  # Defines an set of objects, permission grants and role grants. All objects in a policy
+  # share a common naming prefix, which is the id of the policy. (Exception: the root
+  # policy does not add a naming prefix to each of its objects).
+  #
+  # Policies are defined using a YAML syntax, which is extensively documented on the Conjur 
+  # web site. To load a policy, define it using YAML and then use {API#load_policy}.
+  #
+  # @see API#load_policy
+  class Policy < BaseObject
+    include ActsAsRolsource
   end
 end