Class: OsoCloud::Oso

Inherits:
Object
  • Object
show all
Defined in:
lib/oso/oso.rb

Overview

Oso Cloud client for Ruby

About facts:

Some of these methods accept and return “fact”s. A “fact” is an array with at least one element. The first element must be a string, representing the fact’s name. Any other elements in the array, which together represent the fact’s arguments, can be “OsoCloud::Value” objects or strings.

Instance Method Summary collapse

Constructor Details

#initialize(url: 'https://cloud.osohq.com', api_key: nil, fallback_url: nil, data_bindings: nil) ⇒ Oso

Returns a new instance of Oso.



31
32
33
34
 
# File 'lib/oso/oso.rb', line 31

def initialize(url: 'https://cloud.osohq.com', api_key: nil, fallback_url: nil, data_bindings: nil)
  @api = OsoCloud::Core::Api.new(url: url, api_key: api_key, data_bindings: data_bindings,
                                 options: { fallback_url: fallback_url })
end

Instance Method Details

#actions(actor, resource, context_facts = []) ⇒ Array<String>

List authorized actions

Fetches a list of actions which an actor can perform on a particular resource.

Parameters:

Returns:

  • (Array<String>)

See Also:



252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/oso/oso.rb', line 252

def actions(actor, resource, context_facts = [])
  actor_typed_id = actor.to_api_value
  resource_typed_id = resource.to_api_value
  result = @api.post_actions(OsoCloud::Core::ActionsQuery.new(
                               actor_type: actor_typed_id.type,
                               actor_id: actor_typed_id.id,
                               resource_type: resource_typed_id.type,
                               resource_id: resource_typed_id.id,
                               context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
                             ))
  result.results
end

#actions_local(actor, resource, context_facts = []) ⇒ String

Fetches a query that can be run against your database to fetch the actions an actor can perform on a resource.

Returns a SQL query to run against the local database

Parameters:

Returns:

  • (String) 


104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/oso/oso.rb', line 104

def actions_local(actor, resource, context_facts = [])
  actor_typed_id = actor.to_api_value
  resource_typed_id = resource.to_api_value
  result = @api.post_actions_query(
    OsoCloud::Core::ActionsQuery.new(
      actor_type: actor_typed_id.type,
      actor_id: actor_typed_id.id,
      resource_type: resource_typed_id.type,
      resource_id: resource_typed_id.id,
      context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
    )
  )
  result.sql
end

#authorize(actor, action, resource, context_facts = [], parity_handle: nil) ⇒ Boolean

Check a permission

Returns true if the actor can perform the action on the resource; otherwise false.

This method has an optional parameter ‘parity_handle` which is used to compare the result of your Oso authorization check with your legacy authorization system. Learn more about using the parity_handle with Oso Migrate here:

www.osohq.com/docs/app-integration/client-apis/ruby#oso-migrate

Parameters:

Returns:

  • (Boolean)

See Also:



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/oso/oso.rb', line 157

def authorize(actor, action, resource, context_facts = [], parity_handle: nil)
  actor_typed_id = actor.to_api_value
  resource_typed_id = resource.to_api_value
  result = @api.post_authorize(OsoCloud::Core::AuthorizeQuery.new(
                                 actor_type: actor_typed_id.type,
                                 actor_id: actor_typed_id.id,
                                 action: action,
                                 resource_type: resource_typed_id.type,
                                 resource_id: resource_typed_id.id,
                                 context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
                               ),
                               parity_handle
                               )
  result.allowed
end

#authorize_local(actor, action, resource, context_facts = [], parity_handle: nil) ⇒ String

Check a permission depending on data both in Oso Cloud and stored in a local database

Returns a SQL query to run against the local database

This method has an optional parameter ‘parity_handle` which is used to compare the result of your Oso authorization check with your legacy authorization system. Learn more about using the parity_handle with Oso Migrate here:

www.osohq.com/docs/app-integration/client-apis/ruby#oso-migrate

Parameters:

Returns:

  • (String) 


53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/oso/oso.rb', line 53

def authorize_local(actor, action, resource, context_facts = [], parity_handle: nil)
  actor_typed_id = actor.to_api_value
  resource_typed_id = resource.to_api_value
  result = @api.post_authorize_query(
    OsoCloud::Core::AuthorizeQuery.new(
      actor_type: actor_typed_id.type,
      actor_id: actor_typed_id.id,
      action: action,
      resource_type: resource_typed_id.type,
      resource_id: resource_typed_id.id,
      context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
    ), parity_handle
  )
  result.sql
end

#authorize_resources(actor, action, resources, context_facts = []) ⇒ Array<OsoCloud::Value>

Check authorized resources

Returns a subset of the resource which an actor can perform a particular action. Ordering and duplicates, if any exist, are preserved.

Parameters:

Returns:

See Also:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/oso/oso.rb', line 185

def authorize_resources(actor, action, resources, context_facts = [])
  return [] if resources.nil?
  return [] if resources.empty?

  key = lambda do |type, id|
    "#{type}:#{id}"
  end

  resources_extracted = resources.map(&:to_api_value)
  actor_typed_id = actor.to_api_value
  data = OsoCloud::Core::AuthorizeResourcesQuery.new(
    actor_type: actor_typed_id.type, actor_id: actor_typed_id.id,
    action: action,
    resources: resources_extracted,
    context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
  )
  result = @api.post_authorize_resources(data)

  return [] if result.results.empty?

  results_lookup = {}
  result.results.each do |r|
    k = key.call(r.type, r.id)
    results_lookup[k] = true if results_lookup[k].nil?
  end

  resources.select do |r|
    e = r.to_api_value
    exists = results_lookup[key.call(e.type, e.id)]
    exists
  end
end

#bulk(delete: [], insert: []) ⇒ nil

Transactionally delete and insert fact(s)

Delete(s) are processed before insertion(s). nil arguments in facts to be deleted act as wildcards. Does not throw an error if facts to be deleted are not found or facts to be inserted already exist.

Throws an OsoCloud::Core::Api exception if error returned from server.

Parameters:

  • delete (Array<fact>) (defaults to: [])
  • insert (Array<fact>) (defaults to: [])

Returns:

  • (nil)

See Also:



334
335
336
337
338
 
# File 'lib/oso/oso.rb', line 334

def bulk(delete: [], insert: [])
  @api.post_bulk(OsoCloud::Core::Bulk.new(delete: OsoCloud::Helpers.params_to_facts(delete),
                                          tell: OsoCloud::Helpers.params_to_facts(insert)))
  nil
end

#bulk_actions(actor, queries:) ⇒ Array<Array<String>>

List authorized actions for a batch of queries

Fetches a list of actions which an actor can perform on a particular resource.

Parameters:

Returns:

  • (Array<Array<String>>)

See Also:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
 
# File 'lib/oso/oso.rb', line 382

def bulk_actions(actor, queries:)
  actor_typed_id = actor.to_api_value
  data = queries.map do |q|
    context_facts = []
    resource = nil
    if q.is_a?(Array)
      resource = q[0]
      context_facts = q[1]
    else
      resource = q
    end
    resource_typed_id = resource.to_api_value
    OsoCloud::Core::ActionsQuery.new(
      actor_type: actor_typed_id.type,
      actor_id: actor_typed_id.id,
      resource_type: resource_typed_id.type,
      resource_id: resource_typed_id.id,
      context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
    )
  end
  @api.post_bulk_actions(data).map(&:results)
end

#bulk_delete(facts) ⇒ nil

Delete many facts

Deletes many facts at once. Does not throw an error when some of the facts are not found.

Parameters:

  • facts (Array<fact>)

Returns:

  • (nil)

See Also:



315
316
317
318
 
# File 'lib/oso/oso.rb', line 315

def bulk_delete(facts)
  @api.post_bulk_delete(OsoCloud::Helpers.params_to_facts(facts))
  nil
end

#bulk_tell(facts) ⇒ nil

Add many facts

Adds many facts at once.

Parameters:

  • facts (Array<fact>)

Returns:

  • (nil)

See Also:



287
288
289
290
 
# File 'lib/oso/oso.rb', line 287

def bulk_tell(facts)
  @api.post_bulk_load(OsoCloud::Helpers.params_to_facts(facts))
  nil
end

#delete(name, *args) ⇒ nil

Delete fact

Deletes a fact. Does not throw an error if the fact is not found.

Parameters:

Returns:

  • (nil) 


300
301
302
303
304
 
# File 'lib/oso/oso.rb', line 300

def delete(name, *args)
  typed_args = args.map { |a| OsoCloud::Helpers.extract_value(a) }
  @api.delete_facts(OsoCloud::Core::Fact.new(predicate: name, args: typed_args))
  nil
end

#get(name, *args) ⇒ Array<fact>

List facts

Lists facts that are stored in Oso Cloud. Can be used to check the existence of a particular fact, or used to fetch all facts that have a particular argument. nil arguments operate as wildcards.

Parameters:

Returns:

  • (Array<fact>)

See Also:



351
352
353
 
# File 'lib/oso/oso.rb', line 351

def get(name, *args)
  OsoCloud::Helpers.facts_to_params(@api.get_facts(name, args))
end

#get_policy_metadata ⇒ Object

Returns metadata about the currently active policy



134
135
136
 
# File 'lib/oso/oso.rb', line 134

def get_policy_metadata
  @api.get_policy_metadata.metadata
end

#list(actor, action, resource_type, context_facts = []) ⇒ Array<String>

List authorized resources

Fetches a list of resource ids on which an actor can perform a particular action.

Parameters:

  • actor (OsoCloud::Value)
  • action (String)
  • resource_type (String)
  • context_facts (Array<fact>) (defaults to: [])

Returns:

  • (Array<String>)

See Also:



230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/oso/oso.rb', line 230

def list(actor, action, resource_type, context_facts = [])
  actor_typed_id = actor.to_api_value
  result = @api.post_list(OsoCloud::Core::ListQuery.new(
                            actor_type: actor_typed_id.type,
                            actor_id: actor_typed_id.id,
                            action: action,
                            resource_type: resource_type,
                            context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
                          ))
  result.results
end

#list_local(actor, action, resource_type, column, context_facts = []) ⇒ String

List authorized resources depending on data both in Oso Cloud and stored in a local database

Returns a SQL query to run against the local database

Parameters:

  • actor (OsoCloud::Value)
  • action (String)
  • resource_type (String)
  • column (String)
  • context_facts (Array<fact>) (defaults to: [])

Returns:

  • (String) 


80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/oso/oso.rb', line 80

def list_local(actor, action, resource_type, column, context_facts = [])
  actor_typed_id = actor.to_api_value
  result = @api.post_list_query(
    query: OsoCloud::Core::ListQuery.new(
      actor_type: actor_typed_id.type,
      actor_id: actor_typed_id.id,
      action: action,
      resource_type: resource_type,
      context_facts: OsoCloud::Helpers.params_to_facts(context_facts)
    ),
    column: column
  )
  result.sql
end

#policy(policy) ⇒ nil

Update the active policy

Updates the active policy in Oso Cloud, The string passed into this method should be written in Polar.

Parameters:

  • policy (String)

Returns:

  • (nil) 


127
128
129
130
 
# File 'lib/oso/oso.rb', line 127

def policy(policy)
  @api.post_policy(OsoCloud::Core::Policy.new(src: policy, filename: ''))
  nil
end

#query(name, *args, context_facts: []) ⇒ Array<fact>

List added and derived facts

Lists facts that are stored in Oso Cloud in addition to derived facts from evaluating the policy. nil arguments operate as wildcards.

Parameters:

  • name (String)
  • args (Array<[String, OsoCloud::Value, nil]>)
  • context_facts (Array<fact>) (defaults to: [])

Returns:

  • (Array<fact>)

See Also:



366
367
368
369
370
371
 
# File 'lib/oso/oso.rb', line 366

def query(name, *args, context_facts: [])
  typed_args = args.map { |a| OsoCloud::Helpers.extract_value(a) }
  result = @api.post_query(OsoCloud::Core::Query.new(fact: OsoCloud::Helpers.param_to_fact(name, typed_args),
                                                     context_facts: OsoCloud::Helpers.params_to_facts(context_facts)))
  OsoCloud::Helpers.facts_to_params(result.results)
end

#tell(name, *args) ⇒ nil

Add a fact

Adds a fact with the given name and arguments.

Parameters:

Returns:

  • (nil) 


273
274
275
276
277
 
# File 'lib/oso/oso.rb', line 273

def tell(name, *args)
  typed_args = args.map { |a| OsoCloud::Helpers.extract_value(a) }
  @api.post_facts(OsoCloud::Core::Fact.new(predicate: name, args: typed_args))
  nil
end