Reference
API
Ruby

Ruby Client API

💡

Before going through this guide, make sure you follow the Oso Cloud Quickstart to get your Oso API Key properly set in your environment.

First, install the oso-cloud gem from RubyGems:

gem install oso-cloud

Instantiating an Oso Cloud Client

The Oso Cloud library works by providing an OsoCloud::Oso class which you configure with your Oso Cloud URL and API key:

require 'oso-cloud'
 
oso = OsoCloud::Oso.new(url: "https://cloud.osohq.com", api_key: YOUR_API_KEY)
 
# Later:
oso.tell("has_role", user, role, resource)
 
# Wherever authorization needs to be performed:
if oso.authorize(user, action, resource)
    # Action is allowed

Passing application entities into the client

Under the hood, Oso Cloud represents an entity in your application as a combination of a type and an ID, which together uniquely identify the entity. The Ruby client represents these entities using the OsoCloud::Value class, a struct with both type and id properties. For example:

alice = OsoCloud::Value.new(type: "User", id: "alice")
anvilsRepository = OsoCloud::Value.new(type: "Repository", id: "anvils")

You will pass objects like these into nearly every function call you make to the Ruby client.

Management API

Add fact: oso.tell(name, *args)

Adds a fact named name with the provided arguments. Example:

oso.tell(
  "has_role",
  OsoCloud::Value.new(type: "User", id: "bob"),
  "owner",
  OsoCloud::Value.new(type: "Organization", id: "acme")
)

Add many facts: oso.bulk_tell([*[name, *args]])

Adds many facts at once. Example:

oso.bulk_tell([
  [
    "has_role",
    OsoCloud::Value.new(type: "User", id: "bob"),
    "owner"
    OsoCloud::Value.new(type: "Organization", id: "acme")
  ],
  [
    "has_role",
    OsoCloud::Value.new(type: "User", id: "bob"),
    "maintainer",
    OsoCloud::Value.new(type: "Repository", id: "anvils")
  ],
])

Delete fact: oso.delete(name, *args)

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

oso.delete(
  "has_role",
  OsoCloud::Value.new(type: "User", id: "bob"),
  "maintainer",
  OsoCloud::Value.new(type: "Repository", id: "anvils")
)

Delete many facts: oso.bulk_delete([*[name, *args]])

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

oso.bulk_delete([
  [
    "has_role",
    OsoCloud::Value.new(type: "User", id: "bob"),
    "owner",
    OsoCloud::Value.new(type: "Organization", id: "acme")
  ],
  [
    "has_role",
    OsoCloud::Value.new(type: "User", id: "bob"),
    "maintainer",
    OsoCloud::Value.new(type: "Repository", id: "anvils")
  ],
])

List facts: oso.get(name, *args)

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:

# Get one fact:
oso.get(
  "has_role",
  OsoCloud::Value.new(type: "User", id: "bob")
  "admin",
  OsoCloud::Value.new(type: "Repository", id: "anvils")
)
# => [[
# "has_role",
#  OsoCloud::Value.new(type: "User", id: "bob"),
#  "admin",
#  OsoCloud::Value.new(type: "Repository", id: "anvils")
# ]]
 
# List all roles on the `anvils` repo
oso.get("has_role", nil, nil, OsoCloud::Value.new(type: "Repository", id: "anvils"))
# => [
#  [
#    "has_role",
#    OsoCloud::Value.new(type: "User", id: "bob"),
#    "admin",
#    OsoCloud::Value.new(type: "Repository", id: "anvils")
#  ],
#  ... other has_role facts
#]

Note that nil behaves like a wildcard: passing nil, nil, anvils means "find all facts where anvils is the third argument, regardless of other arguments".

Check API

Context facts

You may provide an array of context facts as an optional argument to any of the Check API methods. When Oso Cloud performs a check, it will consider these context facts in addition to any other facts you've previously added. Context facts are only used in the API call in which they're provided— they do not persist across requests. Learn more about context facts.

Check a permission: oso.authorize(actor, action, resource)

Determines whether or not an action is allowed, based on a combination of authorization data and policy logic. Example:

alice = OsoCloud::Value.new(type: "User", id: "alice")
anvils_repository = OsoCloud::Value.new(type: "Repository", id: "anvils")
 
raise "Action is not allowed" unless oso.authorize(alice, "read", anvils_repository)

You may provide an array of context facts as an optional fourth argument to this method. Example:

issue_on_anvils_repository = OsoCloud::Value.new(type: "Repository", id: "anvils-1")
 
oso.authorize(alice, "read", anvils_repository, [
  ["has_relation", issue_on_anvils_repository, "parent", anvils_repository] # a context fact
])

Check authorized resources: oso.authorize_resources(actor, action, resources)

Returns a subset of resources on which an actor can perform a particular action. Ordering and duplicates, if any exist, are preserved. Example:

alice = OsoCloud::Value.new(type: "User", id: "alice")
anvils_repository = OsoCloud::Value.new(type: "Repository", id: "anvils")
acme_repository = OsoCloud::Value.new(type: "Repository", id: "acme")
 
resources = oso.authorize_resources(alice, "read", [anvils_repository, acme_repository])
# => [acme_repository]

You may provide an array of context facts as an optional fourth argument to this method. Example:

issue_on_acme_repository = OsoCloud::Value.new(type: "Repository", id: "acme-1")
issue_on_anvils_repository = OsoCloud::Value.new(type: "Repository", id: "anvils-2")
 
oso.authorize_resources(
  alice, "read", [issue_on_anvils_repository, issue_on_acme_repository],
  [ # context facts
    ["has_relation", issue_on_anvils_repository, "parent", anvils_repository],
    ["has_relation", issue_on_acme_repository, "parent", acme_repository]
  ]
)
# => [issue_on_acme_repository]

List authorized resources: oso.list(actor, action, resource_type)

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

alice = OsoCloud::Value.new(type: "User", id: "alice")
 
oso.list(alice, "read", "Repository")
# => ["acme"]

You may provide an array of context facts as an optional fourth argument to this method. Example:

anvils_repository = OsoCloud::Value.new(type: "Repository", id: "anvils")
acme_repository = OsoCloud::Value.new(type: "Repository", id: "acme")
 
issue_on_acme_repository = OsoCloud::Value.new(type: "Repository", id: "acme-1")
issue_on_anvils_repository = OsoCloud::Value.new(type: "Repository", id: "anvils-2")
 
oso.list(
  alice, "read", "Issue",
  [ # context facts
    ["has_relation", issue_on_anvils_repository, "parent", anvils_repository],
    ["has_relation", issue_on_acme_repository, "parent", acme_repository]
  ]
)
# => ["acme-1"]
 

List authorized actions: oso.actions(actor, resource)

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

alice = OsoCloud::Value.new(type: "User", id: "alice")
acme_repository = OsoCloud::Value.new(type: "Repository", id: "acme")
 
oso.actions(alice, acme_repository)
# => ["read"]

You may provide an array of context facts as an optional third argument to this method. Example:

issue_on_acme_repository = OsoCloud::Value.new(type: "Repository", id: "acme-1")
 
oso.actions(
  alice, issue_on_acme_repository,
  [
    ["has_relation", issue_on_acme_repository, "parent", acme_repository] # a context fact
  ]
)
# => ["read"]

Policy API

Update the active policy: oso.policy(policy)

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

oso.policy("actor User {}")

Talk to an Oso Engineer

Our team is happy to help you get started with Oso Cloud. If you'd like to learn more about using Oso Cloud in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer.

Get started with Oso Cloud →

Last updated on September 27, 2022