Get Help
Get Help The Oso engineering team is available to help you as you build out authorization: Guidance on authorization best practices Answering questions on how to use Oso Authorization model and design reviews We’re available in Slack, along with hundreds of other developers working on authorization. You can also set up a 1x1 with an Oso engineer. For customers who want an SLA on support, we provide paid support. This includes: Production support (24x7x365) Emergency hotfixes Security reviews Production readiness preparation For more information on paid support, drop us an email.
0.15 Documentation
Upgrading to 0.20

Migration guide for upgrading from Oso 0.15 to the new 0.20 release.

Releases
Performance
Performance This page explores the performance of Oso across three main axes: 1. In practice. How does Oso perform under typical workloads? 2. Internals and Micro-benchmarks. How is Oso built? What are the micro-benchmarks? 3. Scaling. What is the theoretical complexity of a query? In Practice There are two main areas to consider when measuring the performance of Oso queries: the time to evaluate a query relative to a policy, and the time needed to fetch application data. In a complex policy, the time it takes to run a single query depends on the complexity of the answer. For example, a simple rule that says anyone can “GET” the path “/” will execute in less than 1 ms. On the other hand, rules that use HTTP path mapping, resource lookups, roles, inheritance, etc. can take approximately 1-20 ms. (These numbers are based on queries executing against a local SQLite instance to isolate Oso’s performance from the time to perform database queries.) The time needed to fetch application data is, of course, dependent on your specific environment and independent of Oso. Aggressive caching can be used to reduce some of the effect of such latencies. Profiling Oso does not currently have built-in profiling tools, but this is a high-priority item on our near-term roadmap. Our benchmark suite uses Rust’s statistical profiling package, but is currently better suited to optimizing the implementation than to optimizing a specific policy. Oso has a default maximum query execution time of 30s. If you hit this maximum, it likely means that you have created an infinite loop in your policy. You can use the Polar debugger to help track down such bugs. For performance issues caused by slow database queries or too many database queries, we recommend that you address these issues at the data access layer, i.e., in the application. See, for example, our guidance on The “N+1 Problem”. Internals and Micro-benchmarks The core of Oso is the Polar virtual machine, which is written in Rust. (For more on the architecture and implementation, see Internals.) A single step of the virtual machine takes approximately 1-2 us, depending on the instruction or goal. Simple operations like comparisons and assignment typically take just a few instructions, whereas more complex operations like pattern matching against an application type or looking up application data need a few more. The debugger can show you the VM instructions remaining to be executed during a query using the goals command. The current implementation of Oso has not yet been aggressively optimized for performance, but several low-hanging opportunities for optimizations (namely, caches and indices) are on our near-term roadmap. We do ensure that all memory allocated during a query is reclaimed by its end, and our use of Rust ensures that the implementation is not vulnerable to many common classes of memory errors and leaks. You can check out our current benchmark suite in the repository, along with instructions on how to run it. We would be delighted to accept any example queries that you would like to see profiled; please feel free to email us at engineering@osohq.com. Scaling At its core, answering queries against a declarative policy is a depth-first search problem: nodes correspond to rules, and nodes are connected if a rule references another rule in its body. As a result, the algorithmic complexity of a policy is in theory very large — exponential in the number of rules. However, in practice there shouldn’t be that many distinct paths that need to be taken to make a policy decision. Oso filters out rules that cannot be applied to the inputs early on in the execution. What this means is that if you are hitting a scaling issue, you can make your policies perform better by either by splitting up your rules to limit the number of possibilities, or by adding more specializers to your rule heads. For example, suppose you have 20 different resources, ResourceA, ResourceB, …, and each has 10 or so allow(actor, action, resource: ResourceA) rules. The performance of evaluating a rule with input of type ResourceA will primarily depend on those 10 specific rules, and not the other 190 rules. In addition, you might consider refactoring this rule to allow(actor, action, resource: ResourceA) if allowResourceA(actor, action, resource). This would mean there are only 20 allow rules to sort through, and for a given resource only one of them will ever need to be evaluated. The performance of evaluating policies is usually independent of the number of users or resources in the application when fetching data is handled by your application. However, as in any programming system, you need to be on the lookout for linear and super-linear searches. For example, if you have a method user.expenses() that returns a list of the user’s expenses, the check expense in user.expenses() will require O(n) VM instructions, where n is the length of the list. It would be better to replace the linear search with a single comparison, e.g. expense.user_id = user.id. Be especially careful when nesting such rules. Summary Oso typically answers simple authorization queries in less than 1 ms, but may take (much) longer depending on the complexity of your rules, the latency of application data access, and algorithmic choices. Some simple solutions such as caching and refactoring may be used to improve performance where needed.
Security
Security This page is split into two sections with two distinct purposes: Security best practices for using Oso, and Our approach to building a secure product Security Best Practices Policy Authoring To reduce the likelihood of writing logic bugs in Oso policies, we recommend using support for specializers as type checks wherever possible. For policy errors that are most likely due to incorrect policies, such as accessing attributes that don’t exist, Oso returns hard errors. Some problems are reported as warnings, when the problem may be a logic bug. An example of this is singletons (unused variables). We additionally recommend the use of Inline Queries (?=) as simple policy unit tests. Since Oso is accessible as a library, you should test authorization as part of your application test suite. Change Management As a reminder, Oso typically replaces authorization logic that would otherwise exist in your application. By using Oso, you are able to move much of that logic into separate a policy file/s, which is easier to audit and watch for changes. Currently, the best practice for policy change management is to treat Oso like regular source code. You should use code review practices and CI/CD to make sure you have properly vetted and kept a history (e.g., through git) of all changes to authorization logic. Auditing If you are interested in capturing an audit log of policy decisions, and being able to understand why Oso authorized a request, please contact us. Our Approach to Building a Secure Product Code The core of Oso is written in Rust, which vastly reduces the risk of memory unsafety relative to many other low-level and embeddable languages (e.g., C, C++). The Oso engineering team codes defensively – we make extensive use of types, validate inputs, and handle errors safely. All source code is available at our GitHub repository. Releases are built and published using GitHub actions. Oso has not yet undergone a code audit. We plan to engage a qualified third-party to perform an audit, whose results we will make publicly available, in the near future. Vulnerability Reporting We appreciate any efforts to find and disclose vulnerabilities to us. If you would like to report an issue, or have any other security questions or concerns, please email us at security@osohq.com.

Was this page useful?