Windows Command-Line Interface (CLI)
Set up the Oso Cloud Windows CLI
Install the Oso Cloud Windows CLI
The Windows CLI is distributed as an executable. To install it, run the following command from a Windows PowerShell prompt:
> Invoke-WebRequest "https://d3i4cc4dqewpo9.cloudfront.net/latest/oso_cli.exe" -OutFile C:\<your_oso_cli_folder>\oso_cli.exe
Replace <your_oso_cli_folder>
with the location of the folder where you want to store the CLI.
You can verify the installation succeeded using:
C:\<your_oso_cli_folder>\oso_cli --help
You can permanently add the <your_oso_cli_folder>
directory to your PATH by appending it to the PATH environment variable.
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:
-
Create or find an API key for the environment you want to use (opens in a new tab).
-
Store the API key as OSO_AUTH for the current PowerShell session.
Set-Item -Path env:OSO_AUTH -Value “<your_oso_api_key>"
You can permanently add the API key to your environment by creating an
OSO_AUTH
environment variable and setting its value to the key you used
above.
Centralized Authorization Data API
Oso Cloud clients provide an API to manage authorization data stored directly in Oso Cloud.
Add fact: oso_cli 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_cli 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 factoso-cloud delete has_role User:bob "maintainer" Repository:anvil
# delete all user roles from the repositoryoso-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
The Check API lets you provide context facts with each request. When Oso Cloud performs a check, it considers the request's context facts in addition to any other centralized authorization data. Context facts are only used in the API call in which they're provided-- they do not persist across requests.
For more details, see Context Facts.
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 factsoso-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.
Local Check API
The local check API lets you perform authorization using data that's distributed across Oso Cloud and your own database.
For more information, see Local Authorization.
Validate local authorization config: oso-cloud validate-local-authorization-config <config-file> -c <connection-string> -p <policy-file>
Validate a local authorization config: 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-local-authorization-config path/to/data_bindings.yaml -c postgres://localhost -p main.polar
List authorized resources with local 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 local 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.
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.
Preview changes
To preview a policy change (without submitting it), pass the --preview
flag:
oso-cloud policy main.polar --previewPreviewing 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
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.