Oso Cloud Python Client

2.6.0 · active · verified Wed Apr 15

Oso Cloud is an authorization-as-a-service platform. The Python client (`oso-cloud`) provides a convenient wrapper around the Oso Cloud HTTP API, enabling applications to interact with the service for modeling, storing, enforcing, querying, and testing authorization logic using the declarative Polar policy language. The library is currently at version 2.6.0 and demonstrates a healthy release cadence, with the last version released less than a year ago.

Warnings

breaking Migration from `oso-cloud` v1 to v2 involved significant breaking changes. The Fact Management API now uses tuples instead of dictionaries for facts, and methods like `tell` were replaced by `insert`. The Query API was also replaced by a more powerful `build_query()` API, and `authorize_resources` was removed.
Fix: Refer to the official migration guide. Key changes include converting fact arguments from dictionaries to `oso_cloud.Value` types and using `insert`/`delete` for fact management. Update query logic to use `oso.build_query()` or `oso.check()`.
gotcha When updating facts or policies in Oso Cloud, direct changes can lead to inconsistent authorization if not handled carefully during the transition period.
Fix: Implement 'bridge rules' in your Polar policy to map old facts to new ones temporarily. Update application code to write new facts, and then perform a batch migration of existing facts using the Get API and Batch API to ensure consistency. Clean up old facts and bridge rules after migration.
deprecated The standalone `oso` open-source library is deprecated. New projects and existing users are encouraged to migrate to Oso Cloud and its client libraries (`oso-cloud`).
Fix: Switch to `oso-cloud` for managed authorization-as-a-service. This involves updating imports, re-evaluating policy management (now typically through Oso Cloud console or CLI), and using the `oso_cloud` client API.
gotcha The Oso Dev Server (a local tool often used with `oso-cloud`) had a breaking change in v1.2 related to its data schema. Existing local data might become incompatible.
Fix: If using the Oso Dev Server, delete the `.oso` directory (default storage location for local data) before using v1.2 or newer to prevent inconsistencies.
gotcha The `*` literal as a resource identifier was disallowed in Oso Dev Server v1.15.0 to align its behavior with Oso Cloud. Policies using `*` might break.
Fix: Avoid using the `*` literal as a resource identifier in Polar policies. If necessary, you can temporarily revert this behavior in the dev server via `OSO_DISABLED_FEATURES=splat-fact-pushback`.
gotcha For high-availability production systems, relying solely on the Oso Cloud service might not be sufficient for all failure scenarios.
Fix: Consider implementing a hybrid deployment model with an Oso Fallback Service. This service acts as a backup, providing authorization responses even if Oso Cloud experiences outages or becomes unreachable.

Install

pip install oso-cloud Install `oso-cloud`

Imports

Oso
wrong:
```
from oso import Oso
```
correct:
```
from oso_cloud import Oso
```
The `oso` library is a deprecated open-source version; `oso_cloud` is the client for the managed service.
Value
```
from oso_cloud import Value
```
Used for representing typed values in facts and queries.
IntoValue
```
from oso_cloud import IntoValue
```
Type hint for values that can be converted into `oso_cloud.Value`.
IntoFact
```
from oso_cloud import IntoFact
```
Type hint for facts that can be converted into `oso_cloud.Fact` (often tuples).

Quickstart

This quickstart demonstrates how to initialize the `oso-cloud` client, insert authorization facts, and perform permission checks and queries against the Oso Cloud service. It requires an active Oso Cloud account and an API key, which should be set as the `OSO_AUTH` environment variable. The examples assume a basic policy defining roles and permissions (e.g., an owner can read a repository) has been uploaded to your Oso Cloud instance.

import os
from oso_cloud import Oso, Value

# Initialize Oso Cloud client with an API key
# Ensure OSO_AUTH environment variable is set or pass it directly:
# oso = Oso(api_key=os.environ.get('OSO_AUTH', ''))
oso = Oso()

# Define example data
user = Value("User", "alice")
repository = Value("Repository", "my-repo")
organization = Value("Organization", "acme")

async def run_auth_checks():
    try:
        # Insert a fact: Alice has the role 'owner' on 'my-repo'
        await oso.insert(("has_role", user, "owner", repository))
        print(f"Inserted fact: Alice is owner of my-repo.")

        # Check if Alice can 'read' the 'my-repo' repository
        # This assumes a policy has been uploaded to Oso Cloud, e.g.,
        # allow(user: User, "read", repo: Repository) if has_role(user, "owner", repo);
        is_allowed = await oso.check(user, "read", repository)
        print(f"Can Alice 'read' my-repo? {is_allowed}")

        # Query for all repositories Alice can 'read'
        # Assumes a policy defining 'allow' rules.
        readable_repos = []
        async for result in oso.query(user, "read", Value("Repository")):
            if result.resource:
                readable_repos.append(result.resource.id)
        print(f"Repositories Alice can read: {readable_repos}")

        # Delete the previously inserted fact
        await oso.delete(("has_role", user, "owner", repository))
        print(f"Deleted fact: Alice is owner of my-repo.")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Make sure OSO_AUTH environment variable is set with your Oso Cloud API key.")

import asyncio
asyncio.run(run_auth_checks())

view raw JSON →