Set Up Your Local Development Environment

Because Oso Cloud lets you define you authorization policy as code, you can do the same sorts of local validation and testing for your authorization code that you do with your application code. This will let you catch many errors early - often before they even make it to version control. Here's how you can set up an effective local development environment.

There are 4 steps to configuring a local development environment for Oso Cloud:

Install the VS Code extension.

If you aren't using VS Code, you can skip this section. The other steps will still work.

If you use Visual Studio Code, the first thing you'll want to do is install the Oso Extension and configure it to use the Oso Cloud Polar dialect. This will give you syntax highlighting for your polar code.

Install the Oso Cloud CLI

The Oso Cloud CLI can validate polar syntax and run your policy tests from your local system. You can run policy tests locally or against one of your Oso Cloud environments.

Install the CLI.


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

Validate your policy syntax by running oso-cloud validate /PATH/TO/YOUR/authorization.polar, for example:


$ oso-cloud validate policy/authorization.polar
Policy validated successfully.

Set up a pre-commit hook to validate polar syntax

Being able to manually validate your polar syntax is great, but it's even better to automatically validate the syntax when you try to commit a change to your policy. This will let you prevent invalid policy code from ever getting into your repository. To do this, you'll create a pre-commit hook.

Copy the script below and save it to .git/hooks/pre-commit in the repository that contains your policy code:

Change the value of "POLAR_FILES" to the locations of your .polar files.


#!/bin/sh
#
# An example hook script to verify that polar code that
# is about to be committed is syntactically valid.
# Change this to the paths to your polar files
declare -a POLAR_FILES=(
  "policy/authorization.polar"
  "policy/authorization2.polar"
)
POLAR_FILES_CHANGED=false
# See whether any of the polar files changed in this commit
for POLAR_FILE in "${POLAR_FILES[@]}" ; do
  if git --no-pager diff --cached --name-status | grep -v "^D" | grep "${POLAR_FILE}" >> /dev/null ; then
    POLAR_FILES_CHANGED=true
    break
  fi
done
# If at least one polar file has changed, then validate the syntax of all polar files.
#
# NOTE: This is necessary because polar files may reference objects in other polar files.
! $POLAR_FILES_CHANGED || oso-cloud validate "${POLAR_FILES[@]}"

If you have multiple polar files, then if any of the files change, you need to revalidate all of them by calling oso-cloud validate on the full list of files.

This is because polar files can reference objects in other polar files, so a change to one polar file could break something in a different polar file.

Make the hook executable.


$ chmod 0755 .git/hooks/pre-commit

Now, whenever you commit code that updates your polar files, git will run the oso-cloud validate command. If the command fails, the commit will be blocked. For example, if you have two syntax errors in two files:


$ git commit -m "Try to commit multiple invalid policies"
Policy failed validation:
Policy failed validation due to parser error: did not expect to find the token 'not' at line 1, column 1 of file policy/authorization.polar:
	001: not-an-actor User { }
	    ^
Policy failed validation:
Policy failed validation due to parser error: Expected 'actor' or 'resource' but found 'resorce'. at line 25, column 1 of file policy/authorization2.polar:
	025: resorce Repository {
	    ^

If you fix the errors and try the commit again, it succeeds:


$ git commit -m "Try to commit multiple valid policies"
Policy validated successfully.
[add-policy-tests 76d4809] Try to commit multiple valid policies
 2 files changed, 147 insertions(+), 1 deletion(-)

This ensures that your polar code is always syntactically valid before you commit it to version control.

Run policy tests against the local development binary

Now you know that your polar syntax is correct, but that doesn't guarantee that it actually does what you want it to do. You can confirm that by running your policy tests (opens in a new tab) against the local development binary.

Install the local development binary using the instructions in the documentation (opens in a new tab). Once it's installed, start it by running the binary from a command prompt (the extracted file is called standalone).


$ /path/to/standalone
Server is in test mode, use token 'e_0123456789_12345_osotesttoken01xiIn'
🚀 Rocket has launched from http://[::]:8080

By default, the binary runs in the foreground until you stop it (e.g. by pressing Ctrl+C).

In another terminal window, set the OSO_AUTH and OSO_URL environment variables to point to your local development binary, then use the oso-cloud test CLI command to run the policy tests against it.


$ OSO_AUTH="e_0123456789_12345_osotesttoken01xiIn" OSO_URL="http://localhost:8080" oso-cloud test policy/authorization.polar
Ran 1 test:
organization members can read repos and issues: 3/3 PASS
PASS

We don't recommend calling these policy tests from a pre-commit hook like we did with syntax validation. That would make your pre-commit hook dependent on the local binary - it would be like connecting to a local database in a pre-commit hook.

Automatic policy testing is better suited for later steps in your CI pipeline, such as pre-merge checks

Wrap-up

With these elements in place, you have a robust local development environment for authourization code. You can ensure that your polar syntax is always valid before you commit it, and you can quickly confirm that your policy is functionally correct as you make changes.

Test your Policy Code