conjur-api 4.31.0 → 5.0.0.rc1

data/lib/conjur/role.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
@@ -21,321 +21,9 @@
 require 'conjur/role_grant'
 
 module Conjur
-  # A {http://developer.conjur.net/reference/services/authorization/role Conjur Role} represents an actor that
-  # can be granted or denied permissionto do various things to
-  # {http://developer.conjur.net/reference/services/authorization/resource Conjur Resources}.  Roles are hierarchical:
-  # if role a is a **member of** role b, a is permitted to do everything b is permitted
-  # to do.  This relationship is transitive, so if a is a member of b, b is a member of c,
-  # and c is a member of d, a has all of d's permissions.
-  #
-  # This class represents a Role with a particular identifier.  The actual Conjur role *may or may not
-  # exist!*
-  class Role < RestClient::Resource
-    include Exists
-    include PathBased
-    include QueryString
-
-    # The *unqualified* identifier for this role.
-    #
-    # @example
-    #   api.role('conjur:foo:bar').identifier # => "bar"
-    #
-    # @return [String] the unqualified identifier
-    def identifier
-      match_path(3..-1)
-    end
-    
-    alias id identifier
-
-    # The *qualified* identifier for this role.
-    #
-    # @example
-    #   api.user('bob').role_id # => "conjur:user:bob"
-    #
-    # @return [String] the *qualified* identifier
-    def roleid
-      [ account, kind, identifier ].join(':')
-    end
-
-    alias role_id roleid
-
-    # @api private
-    # Create this role.
-    #
-    # You probably want to use {Conjur::API#create_role} instead.
-    def create(options = {})
-      log do |logger|
-        logger << "Creating role #{kind}:#{identifier}"
-        unless options.empty?
-          logger << " with options #{options.to_json}"
-        end
-      end
-      self.put(options)
-    end
-
-    # 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
-    # You must be a member of the role to call this method.
-    #
-    # 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')
-    #   key_managers.add_member api.user('alice')
-    #
-    #   # Show the memberships, mapped to the member ids.
-    #   key_managers.role.all.map(&:roleid)
-    #   # => ["conjur:group:pubkeys-1.0/admin", "conjur:user:alice"]
-    #
-    # @example See if role `"conjur:user:alice"` is a member of either `"conjur:groups:developers"` or `"conjur:group:ops"`
-    #   is_member = api.role('conjur:user:alice').all(filter: ['conjur:group:developers', 'conjur:group:ops']).any?
-    #
-    # @param [Hash] options options for the request
-    # @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 = {})
-      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)
-        options["filter"] = filter.map{ |obj| cast(obj, :roleid) }
-      end
-
-      result = JSON.parse(self[options_querystring options].get)
-      if result.is_a?(Hash) && ( count = result['count'] )
-        count
-      else
-        host = Conjur::Authz::API.host
-        result.collect do |item|
-          if item.is_a?(String)
-            Role.new(host, self.options)[Conjur::API.parse_role_id(item).join('/')]
-          else
-            RoleGrant.parse_from_json(item, self.options)
-          end
-        end
-      end
-    end
-
-    alias memberships all
-
-    # Check to see if this role is a member of another role.  Membership is transitive.
-    #
-    # ### Permissions
-    # You must be logged in as a member of this role in order to call this method.  Note that if you
-    # pass a role of which you aren't a member to this method, it will return false rather than raising an
-    # exception.
-    #
-    # @example Permissions
-    #   alice_api = Conjur::API.new_from_key "alice", "alice-password"
-    #   admin_api = Conjur::API.new_from_key "admin", "admin-password"
-    #
-    #   # admin_view is the role as seen by the admin user
-    #   admin_view = admin_api.role('conjur:group:pubkeys-1.0/key-managers')
-    #   admin_view.member_of? alice_api.current_role # => false
-    #   alice_api.current_role.member_of? admin_view # => false
-    #
-    #   # alice_view is the role as seen by alice (who isn't a member of the key-managers group)
-    #   alice_view = alice_api.role('conjur:group:pubkeys-1.0/key-managers')
-    #   alice_view.member_of? alice_api.current_role # raises RestClient::Forbidden
-    #   alice_api.current_role.member_of? alice_view # false
-    #
-    # @param [String, #roleid] other_role the role or role id of which we might be a member
-    # @return [Boolean] whether this role is a member of `other_role`
-    # @raise [RestClient::Forbidden] if you don't have permission to perform this operation
-    def member_of?(other_role)
-      other_role = cast(other_role, :roleid)
-      not all(filter: other_role).empty?
-    end
-
-    # Grant this role to another one.  The role given by the `member` argument will become
-    # a member of this role, and have all of its permissions.
-    #
-    # ### Permissions
-    # You must have admin permissions on this role.
-    #
-    # @example Allow `'alice'` to do everything that `'bob'` can do (perhaps better!).
-    #   bob = api.role 'cook:bob'
-    #   alice = api.role 'cook:alice'
-    #
-    #   # bob is allowed to 'fry' a resource called 'food:bacon'
-    #   bob.permitted? "food:bacon", "fry" # => true
-    #
-    #   # alice isn't
-    #   alice.permitted? "food:bacon", "fry" # => false
-    #
-    #   # grant the role 'cook:bob'  to alice, so that she can participate in our culture's
-    #   # bizarre bacon obsession!
-    #   bob.grant_to alice
-    #
-    #   # Now she can fry some bacon!
-    #   alice.permitted? 'food:bacon', 'fry' # => true
-    #
-    # @example Make `alice` a member of `job:cook`, and let her grant that role to others
-    #   # Create an api logged in as 'alice'.  We assume that `api` is an admin.
-    #   alice_api = Conjur::API.new_from_key 'alice', 'alice-password'
-    #
-    #   # First do it without the `admin_option`
-    #   api.role('job:cook').grant_to alice_api.current_role
-    #
-    #   # Alice can't grant the role to bob
-    #   alice_api.role('job:cook').grant_to 'user:bob' # => raises RestClient::Forbidden
-    #
-    #   # Make alice an admin of the role
-    #   api.role('job:cook').grant_to alice_api.current_role, admin_option: true
-    #
-    #   # Now she can grant the role to bob
-    #   alice_api.role('job:cook').grant_to 'user:bob' # Works!
-    #
-    # @example Take away a member's admin privilege
-    #   # alice_api is an api logged in as user "alice", who has admin rights on the role 'job:cooks'.
-    #   # Notice that she can grant the role to 'eve'
-    #   alice_api.role('job:cook').grant_to 'eve'
-    #
-    #   # We don't want her to do this any more
-    #   admin_api.role('job:cook').grant_to 'user:alice', admin_option: false
-    #
-    #   # She's still a member
-    #   alice_api.member_of?('job:cook') # => true
-    #
-    #   # But she can't grant the role to 'bob'
-    #   alice_api.role('job:cook').grant_to 'user:bob' # raises RestClient:Forbidden
-    #
-    # @param [String, #roleid] member the role that will become a member of this role
-    # @param [Hash] options options for the grant
-    # @option options [Boolean] :admin_option when given, the admin flag on the role grant will be set to
-    #   this value.
-    # @return [void]
-    # @raise [RestClient::Forbidden] if you don't have permission to perform the operation
-    def grant_to(member, options={})
-      member = cast(member, :roleid)
-      log do |logger|
-        logger << "Granting role #{identifier} to #{member}"
-        unless options.blank?
-          logger << " with options #{options.to_json}"
-        end
-      end
-      self["?members&member=#{query_escape member}"].put(options)
-    end
-
-    # Remove (revoke) a member from this role. This operation is the inverse of {#grant_to}
-    #
-    # ### Permissions
-    # You must have admin permissions on this role
-    #
-    #
-    # @example Bob has been fired from his job as a cook.
-    #   # currently, he's a member, and therefore is allowed to 'fry' the 'bacon' resource
-    #   bob = api.role('user:bob')
-    #   bob.member_of? 'job:cook' # true
-    #   bob.permitted? 'food:bacon', 'fry' # true
-    #
-    #   # Revoke 'job:cook'
-    #   api.role('job:cook').revoke_from 'user:bob'
-    #
-    #   # Now he's not a member, and he can't fry bacon any more
-    #   bob.member_of? 'job:cook' # false
-    #   bob.permitted? 'food:bacon', 'fry' # false
-    #
-    #   # Note that if alice had her bacon frying permissions through her membership in the role 'user:bob',
-    #   # she'll lose them too:
-    #   api.role('user:alice').member_of? 'user:bob' # true
-    #   api.role('user:alice').permitted? 'food:bacon', 'fry' # => false
-    #
-    #
-    # @param [String, #roleid] member the member to revoke this role from
-    # @param [Hash] options included for backwards compatibility.  Don't use it.
-    # @return [void]
-    # @raise [RestClient::Forbidden] If you don't have permission to perform this operation
-    def revoke_from(member, options = {})
-      member = cast(member, :roleid)
-      log do |logger|
-        logger << "Revoking role #{identifier} from #{member}"
-        unless options.empty?
-          logger << " with options #{options.to_json}"
-        end
-      end
-      self["?members&member=#{query_escape member}"].delete(options)
-    end
-
-    # Check to see if this role is allowed to perform `privilege` on `resource`.
-    #
-    # ### Permissions
-    # Any authenticated role may call this method.  However, instead of raising a 404 if a resource
-    # or role doesn't exist, it will return false.  This is to prevent bad guys from finding out which roles
-    # and resources exist.
-    #
-    # @example
-    #   bacon = api.create_resource 'food:bacon'
-    #   eggs  = api.create_resoure 'food:eggs'
-    #   bob = api.create_role 'cook:bob'
-    #
-    #   # Bob can't do anything initially
-    #   bob.permitted? bacon, 'fry' # => false
-    #   bob.permitted? eggs, 'poach' # => false
-    #
-    #   # Let him poach eggs
-    #   eggs.permit 'poach', bob
-    #
-    #   # Now it's permitted
-    #   bob.permitted? eggs, 'poach' # => true
-    #
-    # @example Somethign a bit more realistic
-    #   # Say we have a service layer that needs access to a database connection string.
-    #   # The layer is called 'web', and the connection string is stored in a variable 'mysql-uri'
-    #   web_layer = api.layer 'web'
-    #   mysql_uri = api.variable 'mysql-uri'
-    #
-    #   # The web layer can't see the value of the variable right now:
-    #   web_layer.role.permitted? mysql_uri, 'execute' # => false
-    #
-    #   # Let's permit that
-    #   mysql_uri.permit 'execute', web_layer
-    #
-    #   # Now it's allowed to fetch the connection string
-    #  web_layer.role.permitted? mysql_uri, 'execute' # => true
-    #
-    # @param [#resourceid, String] resource the resource to check the permission against
-    # @param [String] privilege the privilege to check
-    # @return [Boolean] true if this role has the privilege on the resource
-    def permitted?(resource, privilege, options = {})
-      resource = cast(resource, :resourceid)
-      # NOTE: in previous versions there was 'kind' passed separately. Now it is part of id
-      self["?check&resource_id=#{query_escape resource}&privilege=#{query_escape privilege}"].get(options)
-      true
-    rescue RestClient::ResourceNotFound
-      false
-    end
-    
-
-    # 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 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 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
+  # A Conjur custom Role. This object is used for roles whose `kind` is not
+  # any of the pre-defined common types such as {Group}, {Host}, {Layer}, etc.
+  class Role < BaseObject
+    include ActsAsRole
   end
 end

data/lib/conjur/role_grant.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,14 +19,17 @@
 # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Conjur
-  # A `RoleGrant` instance represents the membership of a role in some unspecified role.  `RoleGrant`s are returned
-  # by {Conjur::Role#members} and represent members of the role on which the method was invoked.
+  # Represents the membership of a role. `RoleGrant`s are returned
+  # by {ActsAsRole#members} and represent members of the role on which the method was invoked.
   #
   # @example
   #   alice.members.map{|grant| grant.member}.include? admin_role # => true
   #   admin_role.members.map{|grant| grant.member}.include? alice # => true
   #
   class RoleGrant
+    extend BuildObject::ClassMethods
+    extend Cast
+
     # The role which was granted.
     # @return [Conjur::Role]
     attr_reader :role
@@ -35,11 +38,6 @@ module Conjur
     # @return [Conjur::Role]
     attr_reader :member
 
-    # The role that created this grant.
-    #
-    # @return [Conjur::Role]
-    attr_reader :grantor
-
     # When true, the role {#member} is allowed to give this grant to other roles
     #
     # @return [Boolean]
@@ -50,29 +48,29 @@ module Conjur
     # Create a new RoleGrant instance.
     #
     # @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 role, member, grantor, admin_option
+    def initialize role, member, 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,
+        role: role.id,
+        member: member.id,
         admin_option: admin_option
-      }.tap do |h|
-        h[:role] = role.roleid if role
-      end
+      }
+    end
+    
+    def to_s
+      to_h.to_s
     end
 
-    #@!attribute member
-    #   The member thing
-    #   @return [Conjur::Role] a ret?
+    def as_json options = {}
+      to_h.as_json(options)
+    end
 
     class << self
       # @api private
@@ -83,15 +81,9 @@ 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(role, member, grantor, json['admin_option'])
+        role = build_object(json['role'], credentials, default_class: Role)
+        member = build_object(json['member'], credentials, default_class: Role)
+        RoleGrant.new(role, member, json['admin_option'])
       end
     end
   end

data/lib/conjur/user.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,74 +19,16 @@
 # 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/user Conjur User}.
-  class User < RestClient::Resource
-    include ActsAsAsset
+  # A Conjur User.
+  class User < BaseObject
     include ActsAsUser
 
-    # Using a method instead of an alias here to make the docs look nicer :-/ - jjm
-
-    # This method is simply an alias for {#id}.  It returns the user's *unqualified* id, which is referred to as
-    # `login` here because it can be used to login to Conjur.
-    # @return [String] the login for this user
-    def login; id end
-
-    # Assign new attributes to the user.
-    #
-    # If a user with the given `:uidnumber` already exists, this method will raise `RestClient::Forbidden`, with
-    # the response body providing additional details if possible.
-    #
-    # ### Permissions
-    # You must be a member of the user's role to update the uidnumber.
-    # You must have update permission on the user's resource or be the user to
-    # update CIDR restrictions.
-    #
-    # @note Updating `uidnumber` requires Conjur server version 4.3 or later.
-    # @note Updating `cidr` requires Conjur server version 4.6 or later.
-    #
-    # @param [Hash] options attributes to change
-    # @option options [FixNum] :uidnumber the new uidnumber for this user.
-    # @option options [Array<String, IPAddr>] :cidr the network restrictions for this user. Requires Conjur server version 4.6 or later
-    # @return [void]
-    # @raise [RestClient::Conflict] if the uidnumber is already in use
-    # @raise [ArgumentError] if uidnumber or cidr aren't valid
-    def update options
-      if uidnumber = options[:uidnumber]
-        # Currently the server raises a 400 Bad Request if uidnumber is missing, require it here
-        raise ArgumentError, "options[:uidnumber] must be a Fixnum" unless uidnumber.kind_of?(Fixnum)
-        self.put(options)
-      end
-
-      if cidr = options[:cidr]
-        set_cidr_restrictions cidr
-      end
-    end
-
-    # Get the user's uidnumber, which is used by LDAP and SSH login, among other things.
-    #
-    # ### Permissions
-    # You must have the `'show'` permission on the user's resource to call this method
-    #
-    # @note This feature requires Conjur server version 4.3 or later.
+    # Get the user's uidnumber, which can be used by LDAP and SSH login, among other things.
     #
     # @return [Fixnum] the uidnumber
     # @raise [RestClient::Forbidden] if you don't have permission to `show` the user.
     def uidnumber
-      attributes['uidnumber']
-    end
-
-    # Set the user's uidnumber, which is used by LDAP and SSH login.
-    #
-    # ### Permissions
-    # You must be a member of the user's role to call this method.
-    #
-    # @note This feature requires Conjur server version 4.3 or later.
-    #
-    # @param [Fixnum] uidnumber the new uidnumber
-    # @return [void]
-    # @raise [RestClient::Conflict] if the uidnumber is already in use.
-    def uidnumber= uidnumber
-      update uidnumber: uidnumber
+      annotation_value 'conjur/uidnumber'
     end
   end
 end