Class: Conjur::Resource

Inherits:
RestClient::Resource
  • Object
show all
Includes:
Exists, HasAttributes, PathBased
Defined in:
lib/conjur/resource.rb

Overview

A Conjur::Resource instance represents a Conjur Resource.

You should not instantiate this class directly. Instead, you can get an instance from the API#resource and API#resources methods, or from the ActsAsResource#resource method present on objects representing Conjur assets that have associated resources.

Instance Method Summary collapse

Methods included from Exists

#exists?

Methods included from PathBased

#account, #kind

Methods included from HasAttributes

#attributes, #invalidate, #refresh, #save, #to_json

Instance Method Details

#annotations ⇒ Conjur::Annotations Also known as: tags

Return an Annotations object to manipulate and view annotations.

Examples:

resource.annotations.count # => 0
resource.annotations['foo'] = 'bar'
resource.annotations.each do |k,v|
   puts "#{k}=#{v}"
end
# output is
# foo=bar

Returns:

See Also:



257
258
259
 
# File 'lib/conjur/resource.rb', line 257

def annotations
  @annotations ||= Conjur::Annotations.new(self)
end

#deny(privilege, role, options = {})

This method returns an undefined value.

The inverse operation of #permit. Deny permission privilege to role on this resource.

Examples:


resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:user:alice']
resource.deny 'execute', 'conjur:user:alice'
resource.permitted_roles 'execute' # =>  ['conjur:user:admin']

Parameters:

  • privilege (String, #each) —

    A permission name or an Enumerable of permissions to deny. In the later, all permissions will be denied.

  • role (String, :roleid) —

    A full role id or a role-ish object whose permissions we will deny.



198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/conjur/resource.rb', line 198

def deny(privilege, role, options = {})
  role = cast(role, :roleid)
  eachable(privilege).each do |p|
    log do |logger|
      logger << "Denying #{p} on resource #{resourceid} by #{role}"
      unless options.empty?
        logger << " with options #{options.to_json}"
      end
    end
    self["?deny&privilege=#{query_escape p}&role=#{query_escape role}"].post(options)
  end
  nil
end

#give_to(owner, options = {})

This method returns an undefined value.

Changes the owner of a resource. You must be the owner of the resource or a member of the owner role to do this.

Examples:

resource.owner # => 'conjur:user:admin'
resource.give_to 'conjur:user:jon'
resource.owner # => 'conjur:user:jon'

Parameters:

  • owner (String, #roleid) —

    the new owner.



117
118
119
120
121
122
123
124
 
# File 'lib/conjur/resource.rb', line 117

def give_to(owner, options = {})
  owner = cast(owner, :roleid)
  invalidate do
    self.put(options.merge(owner: owner))
  end

  nil
end

#identifier ⇒ String

The identifier part of the resource_id for this resource. The identifier is the resource id without the account and kind parts.

Examples:

resource = api.resource 'conjur:layer:pubkeys-1.0/public-keys'
resource.identifier # => 'pubkeys-1.0/public-keys'

Returns:

  • (String) —

    the identifier part of the id.



45
46
47
 
# File 'lib/conjur/resource.rb', line 45

def identifier
  match_path(3..-1)
end

#ownerid ⇒ String Also known as: owner

The full role id of the role that owns this resource.

Examples:

api.current_role # => 'conjur:user:jon'
resource = api.create_resource 'conjur:example:resource-owner'
resource.owner # => 'conjur:user:jon'

Returns:

  • (String) —

    the full role id of this resource's owner.



57
58
59
 
# File 'lib/conjur/resource.rb', line 57

def ownerid
  attributes['owner']
end

#permit(privilege, role, options = {})

This method returns an undefined value.

Grant privilege on this resource to role.

This operation is idempotent, that is, nothing will happen if you attempt to grant a privilege that the role already has on this resource.

Examples:

user = api.user 'bob'
resource = api.variable('example').resource
resource.permitted_roles 'bake' # => ['conjur:user:admin']
resource.permit 'fry', user
resource.permitted_roles 'fry' # => ['conjur:user:admin', 'conjur:user:bob']
resource.permit ['boil', 'bake'], bob
resource.permitted_roles 'boil' # => ['conjur:user:admin', 'conjur:user:bob']
resource.permitted_roles 'bake' # => ['conjur:user:admin', 'conjur:user:bob']

Parameters:

  • privilege (String, #each) —

    The privilege to grant, for example 'execute', 'read', or 'update'. You may also pass an Enumerable object, in which case the Strings yielded by #each will all be granted

  • role (String, #roleid) —

    The role-ish object or full role id to which the permission is to be granted/

  • options (Hash, nil) (defaults to: {}) —

    options to pass through to RestClient::Resource#post



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/conjur/resource.rb', line 163

def permit(privilege, role, options = {})
  role = cast(role, :roleid)
  eachable(privilege).each do |p|
    log do |logger|
      logger << "Permitting #{p} on resource #{resourceid} by #{role}"
      unless options.empty?
        logger << " with options #{options.to_json}"
      end
    end
    
    begin
      self["?permit&privilege=#{query_escape p}&role=#{query_escape role}"].post(options)
    rescue RestClient::Forbidden
      # TODO: Remove once permit is idempotent
      raise $! unless $!.http_body == "Privilege already granted."
    end
  end
  nil
end

#permitted?(privilege, options = {}) ⇒ Boolean

True if the logged-in role, or a role specified using the :acting_as option, has the specified +privilege+ on this resource.

Examples:

api.current_role # => 'conjur:cat:mouse'
resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:cat:mouse']
resource.permitted_roles 'update', # => ['conjur:user:admin', 'conjur:cat:gino']

resource.permitted? 'update' # => false, `mouse` can't update this resource
resource.permitted? 'execute' # => true, `mouse` can execute it.
resource.permitted? 'update',acting_as: 'conjur:cat:gino' # => true, `gino` can update it.

Parameters:

  • privilege (String) —

    the privilege to check

  • options (Hash, nil) (defaults to: {}) —

    for the request

Options Hash (options):

  • :acting_as (String, nil) —

    check whether the role given by this full role id is permitted instead of checking +api.current_role+.

Returns:

  • (Boolean) 


228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/conjur/resource.rb', line 228

def permitted?(privilege, options = {})
  # TODO this method should accept an optional role rather than putting it in the options hash.
  params = {
    check: true,
    privilege: query_escape(privilege)
  }
  params[:acting_as] = options[:acting_as] if options[:acting_as]
  self["?#{params.to_query}"].get(options)
  true
rescue RestClient::Forbidden
  false
rescue RestClient::ResourceNotFound
  false
end

#permitted_roles(permission, options = {}) ⇒ Array<String>

Lists roles that have a specified permission on the resource.

This will return only roles of which api.current_user is a member.

Examples:

resource = api.resource 'conjur:variable:example'
resource.permitted_roles 'execute' # => ['conjur:user:admin']
resource.permit 'execute', api.user('jon')
resource.permitted_roles 'execute' # => ['conjur:user:admin', 'conjur:user:jon']

Parameters:

  • permission (String) —

    the permission

  • options (Hash, nil) (defaults to: {}) —

    extra options to pass to RestClient::Resource#get

Returns:

  • (Array<String>) —

    the ids of roles that have permission on this resource.



103
104
105
 
# File 'lib/conjur/resource.rb', line 103

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)
end

#resourceid ⇒ String Also known as: resource_id

Return the full id for this resource. The format is account:kind:identifier

Examples:

resource = api.layer('pubkeys-1.0/public-keys').resource
resource.        # => 'conjur'
resource.kind           # => 'layer'
resource.identifier     # => 'pubkeys-1.0/public-keys'
resource.resourceid     # => 'conjur:layer:pubkeys-1.0/public-keys'

Returns:

  • (String) 


72
73
74
 
# File 'lib/conjur/resource.rb', line 72

def resourceid 
  [, kind, identifier].join ':'
end