Reference
Client SDK
CLI

Command-Line Interface (CLI)

Set up the Oso Cloud CLI

Install the Oso Cloud CLI package

To install the Oso Cloud CLI, run the following command:


$ curl -L https://cloud.osohq.com/install.sh | bash

You can verify the installation succeeded using:


which oso-cloud

Configure the CLI

When you use the CLI, it connects to one of your account's environments.

To configure the CLI to use a specific environment:

  1. Create or find an API key for the environment you want to use (opens in a new tab).

  2. Export the API key as OSO_AUTH:


    export OSO_AUTH=<your_oso_api_key>

Centralized Authorization Data API

Oso Cloud clients provide an API to manage authorization data stored directly in Oso Cloud.

Add fact: oso-cloud tell <predicate> ([<type>:]<id> )*

Writes a fact named <predicate> with the specified arguments. Arguments for which <type> is omitted are given type String. Example:


oso-cloud tell has_role User:bob "owner" Organization:acme

Delete fact: oso-cloud delete <predicate> ({_, <type>}:{_, <id>} )*

Deletes all facts matching the specific arguments. Does not throw an error if the fact is not found. Example:


# delete one fact
oso-cloud delete has_role User:bob "maintainer" Repository:anvil


# delete all user roles from the repository
oso-cloud delete has_role User:_ _ Repository:anvil

ℹ️

For Oso Cloud developer accounts, Get and Inspect calls are limited to 1000 results. If you have more than 1000 facts, the CLI will return an error.

Get fact: oso-cloud get {_, <predicate>} ({_, <type>}:{_, <id>} )*

Gets all written facts matching the specified predicate and arguments. Use _ in place of a predicate, type, or id to match anything. You can also _ use as shorthand for _:_ to match arguments with any type and id. Example:


oso-cloud get has_role _ "maintainer" Repository:_

Inspect object: oso-cloud inspect {_, <type>}:{_, <id>}

Gets all written facts for which <type>:<id> is an argument. As with oso-cloud get, you can use _ in place of <type> or <id> to match anything. Example:


oso-cloud inspect User:bob

Check API

ℹ️

For Oso Cloud developer accounts, the number of context facts per request is limited to 20; and the number of records returned is limited to 1000.

Context facts

You may provide context facts via the -c argument to any of the Check commands. 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.

Context facts can be used to pass context from your application that you don't want to store in Oso Cloud:

  • Deep resource hierarchies: by passing has_relation(issue, "parent", issue.repository) as a context fact, you can check permissions on an issue without storing every issue -> repository relationship in Oso Cloud.
  • Claims from a user token: if users get certain roles or permissions based on their authentication token (such as a JWT), you can pass that extra information using context facts like is_admin(user).
  • Request-specific context: if you want to protect resources based on IP addresses, or time of day, or other ephemeral request properties, you can pass them as context facts with no arguments: is_weekend() or request_came_from_eu().

Check a permission: oso-cloud authorize <actor> <action> <resource>

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


oso-cloud authorize User:bob read Repository:anvils

Optionally, you may provide context facts via the -c argument. Example:


oso-cloud authorize \
-c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
User:bob read Issue:issueOnAnvilsRepository

Check authorized resources: oso-cloud authorize-resources <actor> <action> (<resource>)*

Returns a subset of resources on which an actor can perform a particular action. Ordering and duplicates, if any exist, may not be preserved.

ℹ️

For Oso Cloud developer accounts, the number of input resources is limited to 1000.


oso-cloud authorize-resources User:bob read Repository:anvils Repository:acme

Optionally, you may provide context facts via the -c argument. Example:


oso-cloud authorize-resources \
-c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
-c "has_relation Issue:issueOnAcmeRepository parent Repository:acme" \
User:bob read Issue:issueOnAnvilsRepository Issue:issueOnAcmeRepository

List authorized resources: oso-cloud list <actor> <action> <resource-type>

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


oso-cloud list User:bob read Repository

Optionally, you may provide context facts via the -c argument. Example:


oso-cloud list \
-c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
-c "has_relation Issue:issueOnAcmeRepository parent Repository:acme" \
User:bob read Issue

List authorized actions: oso-cloud actions <actor> <resource>

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


oso-cloud actions User:bob Repository:anvils

Optionally, you may provide context facts via the -c argument. Example:


oso-cloud actions \
-c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
User:bob Issue:issueOnAnvilsRepository

Query for anything: oso-cloud query <predicate> (<actor|resource>)*

Query Oso Cloud for any predicate and any combination of concrete and wildcard arguments. Unlike oso-cloud get, which only lists facts you've added, you can use oso-cloud query to list derived information about any rule in your policy. Examples:


# Query for all the repos `User:bob` can `read`
oso-cloud query allow User:bob read Repository:_
# Query for all the objects `User:admin` can `read`
oso-cloud query allow User:admin read _

Optionally, you may provide context facts via the -c argument. Example:


# Query for all the repos `User:bob` can `write` derived from context facts
oso-cloud query \
-c "has_permission User:bob write Repository:anvils"
User:bob write Repository:_

Note that _ behaves like a wildcard. Passing allow _ _ Repository:anvils means "find anyone who can do anything to Repository:anvils". _ also behaves like a wildcard in return values from query. Additionally, if you want to query over all instances of a particular type, pass in a resource type with a wildcard id. For example, allow User:bob read Repository:_ will query for all the objects of type "Repository" that User:bob can read.

Learn more about how to query Oso Cloud.

Distributed Check API

The distributed check API allows you to perform authorization using data that's distributed across Oso Cloud and your own database.

For more information, see the guide on filtering lists with decentralized data.

Validate data bindings config: oso-cloud validate-bindings <config-file> -c <connection-string> -p <policy-file>

Validate a data binding configuration: the YAML file that specifies how to resolve facts in your database.

When a connection string is set, runs each SQL query in the config_file against the PostgreSQL database to ensure they are valid, and ensures the queries' SQL types match the types in the sql_types section of the config.

When a policy is set, validates that the configured facts are consistent with the Polar policy.


oso-cloud validate-bindings path/to/data_bindings.yaml -c postgres://localhost -p main.polar

List authorized resources with distributed data: oso-cloud list-local --data-bindings <config-file> <actor> <action> <resource-type> <column>

Fetches a filter that can be applied to a database query to return just the resources on which an actor can perform an action. Example:


oso-cloud list-local --data-bindings path/to/data_bindings.yaml User:alice read Issue id

Check a permission with distributed data: oso-cloud authorize-local --data-bindings <config-file> <actor> <action> <resource>

Fetches a query that can be run against your database to determine whether an actor can perform an action on a resource. Example:


oso-cloud list-local --data-bindings path/to/data_bindings.yaml User:alice read Issue:swage

Policy API

Update the active policy: oso-cloud policy <policy-file> <policy-file2> ...

Updates the policy in Oso Cloud. The file passed into this method should be written in Polar. CLI usage:


oso-cloud policy main.polar

By default, this command will run any tests defined in your policy. If one or more of these tests fail, your policy will not be updated.

Preview changes

To preview a policy change (without submitting it), pass the --preview flag:


oso-cloud policy main.polar --preview
Previewing policy changes.
4 4 | permissions = ["read"];
5 5 |
6 6 | "read" if "member";
7 |+ "member" if "admin";
7 8 | }
8 9 |
9 10 | resource Bar {
10 |- roles = ["admin", "member"];
11 |+ roles = ["admin", "memberz"];
11 12 | }
12 13 |
Running policy tests.
Ran 0 tests:
PASS

Force

You can override this behavior by passing the --force flag:


oso-cloud policy main.polar --force

This will allow you to update a policy with failing test assertions.

Multiple policies

The oso-cloud policy command can also take in multiple policy files. This command concatenates together the policies, and then uploads them. Ordering of policies does not matter.

Test your policy: oso-cloud test <policy-file> <policy-file2> ...

Run any tests defined in your policy. The file passed into this method should be written in Polar. CLI usage:


oso-cloud test main.polar

Note that this command is ephemeral: it won't persist the policy or any facts defined in the tests.

Talk to an Oso Engineer

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. We're happy to help.

Get started with Oso Cloud →

Node.js