CI and Testing
You should think about your Oso policy as application code, and manage it the same way you manage other code in a repository.
We recommend checking your policy (your .polar file) into your repository to make it easy to review and test changes.
This guide will show you how to use your CI infrastructure to validate, test, and ultimately deploy your policy to production, just like you would test and deploy other application code.
Setup
Install the oso-cloud command line tool
$ curl -L https://cloud.osohq.com/install.sh | bash
You will need an Oso Cloud API keys for both a test and a production environment. To create an environment, read the Environments guide.
Testing
There are two ways to test new Oso policies. You can test the policy itself using the assertions in the CLI, or you can run integration tests by running your application test suite using the new policy. Before you do either, you should set up a separate environment just for testing.
You can test the authorization logic directly (without running your application) using the oso-cloud CLI.
In your CI process, enable the test environment by setting OSO_AUTH to your test environment's API key. Begin your test by clearing the environment completely:
export OSO_AUTH=my_test_environment_tokenoso-cloud clear --confirm
Next, upload your policy and tell Oso any facts you want to test against:
oso-cloud policy policy.polaroso-cloud tell has_role User:steve reader Widget:foo......
Then, run authorize and other queries to check that they return what you think they should.
oso-cloud authorize --fail-on-deny User:steve read Widget:foo...
Using --fail-on-deny means that oso-cloud authorize will exit with a
non-zero exit code, which is useful for CI. To enable this by default in a CI
run, set the OSO_CLI_FAIL_ON_DENY environment variable to 1.
You can run application tests using a similar mechanism.
Using your test environment's API key,
clear out any old data, upload the new policy and seed your test data.
Then, run your application test suite and make sure everything passes.
Additional checks
If your deployment uses Local Authorization, you should validate your Local Authorization configuration using the oso-cloud CLI.
Deploy
When your tests pass and you are ready to deploy your new policy to production you can set the OSO_AUTH variable to your production API key and
upload it. This can be done as part of the same CI job that deploys the rest of your code.
export OSO_AUTH=my_production_environment_tokenoso-cloud policy policy.polar
Multiple policy files
When you have multiple teams collaborating on authorization, it can be helpful to split up a policy into multiple files.
You can then upload those policies with oso-cloud policy main.polar team1.polar team2.polar and so on.
This oso-cloud binary concatenates together the policies before uploading them.
Talk to an Oso engineer
If you need further assistance with testing, creating your environments or using them in your CI set up, schedule a 1x1 with an Oso engineer. We're happy to help.