Road to Authorization Guide

Updating a core part of your application can feel overwhelming, but this guide can help you understand the path you should take.

The Oso Cloud documentation is meant to address the use cases, patterns, processes and nuances that may come up while integrating Oso Cloud into your codebase. However, it can be easier to understand which documents you should use and in which order.

Fundamentally, there are four stages that will make up your Oso Cloud integration:

• Modeling your authorization policy in Polar
• Managing authorization data
• Enforcing authorization in your app
• Testing authorization in CI/CD

Many parts of the integration can be completed incrementally, i.e. for just one use case or data model at a time. This guide will walk you through the fundamental steps of your Oso Cloud integration while highlighting our recommendations for iteratively adopting Oso as your source of truth for authorization decisions.

Planning

• To get started, determine a single piece of your application to integrate with Oso. We generally recommend starting with the smallest unit possible (e.g. a single endpoint), but you might want to start with an entire domain concept.

  • If you're looking for some more hands-on experience with wiring up an existing endpoint to use Oso Cloud, check out our Iterative Adoption Guide.

• Deploy your first Oso use case behind a feature flag and monitor for parity alongside your current authorization system.

  When you're ready to switch to Oso as the source of truth for this use case, you can get rid of the legacy authorization code. There's no need for this to replace your current approach all at once.

• After you've integrated a single piece of your application, you can move onto others. In this way, you can incrementally adopt Oso.

Modeling

Modeling is where you describe your app's authorization logic using our logical programming language, Polar.

• Determine your authorization requirements.
• Model your authorization requirements in Polar in an Oso Policy.
  • For more details on our Polar language, see the Polar reference.
  • For examples of common authorization patterns (RBAC, ReBAC, ABAC), see Common Patterns.
  • For best practices when getting started, see Polar Modeling Best Practices.
• Write unit tests for your authorization logic in your .polar files.

Authorization data

Authorization data represents the state of your application, which Oso Cloud will need to understand to make authorization decisions.

• Determine how you want to handle authorization data.
• Plan to manage authorization data with Oso running in production. See Centralized Authorization Data.

Enforcement

Enforcement is the stage where you integrate an Oso Cloud's SDK into your application code.

• Familiarize yourself with Oso's enforcement APIs.

• Generate an API key for your application to access your environment. For more details, see Create New API Keys.

• Set up your team's local development workflow.

• Leverage your language's SDK to add enforcement to your application.

  • For best practices when getting started, see Best Practices for Enforcing Authorization.

  • If you're working with existing endpoints that will use local authorization, read our consider looking at our Iterative Adoption Guide.

Testing in CI/CD

• Test your Oso integration in your CI/CD pipeline.
• Configure the Oso Dev Server to be used during CI checks.
• Plan for outages with a fallback node.