cedarling_python 🐍

This project uses maturin to create a Python library from Rust code. Follow the steps below to install and build the library.

Prerequisites

(Optional) Install build tools (for Linux users)

Install the build-essential package or its equivalent packages using your distribution's package manager.

Ubuntu/Debian:
```
sudo apt install build-essential
```
Arch Linux:
```
sudo pacman -S base-devel
```
RHEL/CentOS/Fedora:
```
sudo yum install gcc gcc-c++ make openssl-dev
```
Ensure Rust is installed: Verify Rust installation by running:
```
cargo --version
```
If Rust is not installed, you can install it from here.
Set up a virtual environment:
- Install venv for your platform by following the instructions here.
- Create a virtual environment:
```
python3 -m venv venv
```
Activate the virtual environment: Follow the instructions here to activate the virtual environment.

Example for Linux/macOS:
```
source venv/bin/activate
```
Example for Windows:
```
.\venv\Scripts\activate
```
Install maturin
```
pip install maturin
```
For Linux, install patchelf dependency:
```
pip install maturin[patchelf]
```

Clone the repository:

git clone https://github.com/JanssenProject/jans.git

Navigate to the cedarling_python folder:

cd jans/jans-cedarling/bindings/cedarling_python

Build and install the package: Build the Rust crate and install it into the virtual environment:
```
maturin develop --release
```
Verify installation: Check that the library is installed by listing the installed Python packages:
```
pip list
```
You should see cedarling_python listed among the available packages.
Read documentation After installing the package you can read the documentation from python using the following command:
```
python -m pydoc cedarling_python
```

Examples

Standalone example scripts live in the examples/ directory, each with its own directory-based policy store under example_files/. Make sure the virtual environment is activated and the package is installed before running them.

Unsigned authorization (no JWT tokens)

Authorize requests by supplying principals directly as EntityData objects, without any JWT tokens. Useful for internal services or test harnesses.

python examples/unsigned_authz.py

Script: examples/unsigned_authz.py
Policy store: example_files/policy-store-unsigned/

Multi-issuer authorization (JWT tokens)

Authorize requests carrying JWT tokens from one or more issuers, with Cedar policies that inspect token attributes via tags.

python examples/multi_issuer_authz.py

Script: examples/multi_issuer_authz.py
Policy store: example_files/policy-store-multi-issuer/

Configuration

Policy Store Sources

Policy store sources can be configured via a YAML/JSON file or environment variables. Here are examples for each source type:

from cedarling_python import BootstrapConfig, Cedarling

# From a local JSON/YAML file
bootstrap_config = BootstrapConfig.load_from_file("/path/to/bootstrap-config.yaml")
instance = Cedarling(bootstrap_config)

# From a local directory (new format)
# In your bootstrap-config.yaml:
# CEDARLING_POLICY_STORE_LOCAL_FN: "/path/to/policy-store/"
bootstrap_config = BootstrapConfig.load_from_file("/path/to/bootstrap-config.yaml")
instance = Cedarling(bootstrap_config)

# From a local .cjar archive
# In your bootstrap-config.yaml:
# CEDARLING_POLICY_STORE_LOCAL_FN: "/path/to/policy-store.cjar"
bootstrap_config = BootstrapConfig.load_from_file("/path/to/bootstrap-config.yaml")
instance = Cedarling(bootstrap_config)

# From a URL (.cjar or Lock Server)
# In your bootstrap-config.yaml:
# CEDARLING_POLICY_STORE_URI: "https://example.com/policy-store.cjar"
# # Optional: re-fetch the policy store every 60s and atomically swap on change.
# # Default is 0 (load-once-at-startup). See "Refreshing the policy store" in
# # docs/cedarling/reference/cedarling-properties.md for details.
# CEDARLING_POLICY_STORE_REFRESH_INTERVAL: 60
bootstrap_config = BootstrapConfig.load_from_file("/path/to/bootstrap-config.yaml")
instance = Cedarling(bootstrap_config)

# Using environment variables instead of a file
import os
os.environ["CEDARLING_POLICY_STORE_LOCAL_FN"] = "/path/to/policy-store.cjar"
bootstrap_config = BootstrapConfig.from_env()
instance = Cedarling(bootstrap_config)

For complete working examples, see the examples/ directory.

For details on the directory-based format and .cjar archives, see Policy Store Formats.

Testing Configuration

For testing scenarios, you may want to disable JWT validation. You can set environment variables:

export CEDARLING_JWT_SIG_VALIDATION="disabled"
export CEDARLING_JWT_STATUS_VALIDATION="disabled"

Or configure in your Python code:

import os
os.environ['CEDARLING_JWT_SIG_VALIDATION'] = 'disabled'

For complete configuration documentation, see cedarling-properties.md.

Context Data API

The Context Data API allows you to push external data into the Cedarling evaluation context, making it available in Cedar policies through the context.data namespace.

Push Data

Store data with an optional TTL (Time To Live):

from cedarling_python import Cedarling, BootstrapConfig

config = BootstrapConfig.load_from_file("bootstrap-config.yaml")
instance = Cedarling(config)

# Push data without TTL (uses default from config)
instance.push_data_ctx("user:123", {"role": ["admin", "editor"], "country": "US"})

# Push data with TTL (5 minutes = 300 seconds)
instance.push_data_ctx("config:app", {"setting": "value"}, ttl_secs=300)

# Push different data types
instance.push_data_ctx("key1", "string_value")
instance.push_data_ctx("key2", 42)
instance.push_data_ctx("key3", [1, 2, 3])
instance.push_data_ctx("key4", {"nested": "data"})

Get Data

Retrieve stored data:

# Get data by key
# Note: get_data_ctx returns None for missing keys, not KeyNotFound
value = instance.get_data_ctx("user:123")
if value is not None:
    print(f"User roles: {value['role']}")

Get Data Entry with Metadata

Get a data entry with full metadata including creation time, expiration, access count, and type:

# Note: get_data_entry_ctx returns None for missing keys, not KeyNotFound
entry = instance.get_data_entry_ctx("user:123")
if entry is not None:
    print(f"Key: {entry.key}")
    print(f"Created at: {entry.created_at}")
    print(f"Access count: {entry.access_count}")
    print(f"Data type: {entry.data_type}")
    print(f"Value: {entry.value}")

Remove Data

Remove a specific entry:

# Remove data by key
removed = instance.remove_data_ctx("user:123")
if removed:
    print("Entry was removed")
else:
    print("Entry did not exist")

Clear All Data

Remove all entries from the data store:

instance.clear_data_ctx()

List All Data

List all entries with their metadata:

entries = instance.list_data_ctx()
for entry in entries:
    print(f"Key: {entry.key}, Type: {entry.data_type}, Created: {entry.created_at}")

Get Statistics

Get statistics about the data store:

stats = instance.get_stats_ctx()
print(f"Entries: {stats.entry_count}/{stats.max_entries}")
print(f"Total size: {stats.total_size_bytes} bytes")
print(f"Capacity usage: {stats.capacity_usage_percent}%")

Drain Metrics

Destructive read: returns a MetricsSnapshot (policy_stats, error_counters, operational_stats, interval) and resets the counters.

snapshot = instance.drain_metrics()
print(f"Requests: {snapshot.operational_stats.get('authz.requests_total')}")
print(f"Interval: {snapshot.interval}")

Requires CEDARLING_METRICS_COLLECTION=enabled. Fails when the Lock telemetry ticker owns the collector i.e. whenever CEDARLING_LOCK_TELEMETRY_INTERVAL is set, even if the Lock server has no telemetry endpoint. interval is a datetime.timedelta with sub-second precision.

Error Handling

The Context Data API methods raise specific exceptions for different error conditions:

from cedarling_python import data_errors

try:
    instance.push_data_ctx("", {"data": "value"})  # Empty key
except data_errors.InvalidKey:
    print("Invalid key provided")

# Note: get_data_ctx and get_data_entry_ctx return None for missing keys,
# not KeyNotFound. KeyNotFound is only raised for operation failures.
value = instance.get_data_ctx("nonexistent")
if value is None:
    print("Key not found")

Available exceptions:

InvalidKey: The provided key is invalid (e.g., empty)
KeyNotFound: Raised for operation failures (not for missing keys - get_data_ctx and get_data_entry_ctx return None for missing keys)
StorageLimitExceeded: The data store has reached its capacity limit
TTLExceeded: The requested TTL exceeds the maximum allowed TTL
ValueTooLarge: The value exceeds the maximum entry size
SerializationError: Failed to serialize/deserialize the value

Using Data in Cedar Policies

Data pushed via the Context Data API is automatically available in Cedar policies under the context.data namespace:

permit(
    principal,
    action == Jans::Action::"read",
    resource
) when {
    context.data has "user:123" &&
    context.data["user:123"].role.contains("admin")
};

The data is injected into the evaluation context before policy evaluation, allowing policies to make decisions based on dynamically pushed data.

Trusted Issuer Loading Info

Cedarling exposes trusted issuer loading status APIs:

loaded_by_name = instance.is_trusted_issuer_loaded_by_name("issuer_id")
loaded_by_iss = instance.is_trusted_issuer_loaded_by_iss("https://issuer.example.org")
total = instance.total_issuers()
loaded_count = instance.loaded_trusted_issuers_count()
loaded_ids = instance.loaded_trusted_issuer_ids()
failed_ids = instance.failed_trusted_issuer_ids()

These values are meaningful when your policy store defines a trusted-issuers/ section.

Building the Python Library

If you only want to build the library without installing it in the Python environment, follow these steps:

Complete the prerequisites

Navigate to the cedarling_python folder:

cd jans/jans-cedarling/bindings/cedarling_python

Build the crate: To build the library:
```
maturin build --release
```

Python types definitions

The python types definitions are available in the PYTHON_TYPES.md file. Or by clicking here. Also after installing the library you can get same information using:

python -m pydoc cedarling_python

Testing the Python bindings

We use pytest and tox to create reproduceable environments for testing.

Run test with `pytest`

To run the tests, with pytest:

Make sure that you have installed the cedarling_python package in your virtual environment or system.
Install pytest:
```
pip install pytest
```
Make sure that you are in the jans/jans-cedarling/bindings/cedarling_python/ folder.
Run the following command:
```
pytest
```
Or run pytest without capturing the output:
```
pytest -s
```
See the results in the terminal.

Run test with `tox`

Ensure that you installed rust compiler and toolchain. You can install it by following the official rust installation guide.
Ensure tox is installed: You can install tox in your environment using pip:
```
pip install tox
```
Make sure that you are in the jans/jans-cedarling/bindings/cedarling_python/ folder.
Run the following command:
```
tox
```
See the results in the terminal.

Release files for cedarling-python 2.4.19

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for cedarling-python 2.4.19
File	Interpreter	ABI	Platform	Reset
cedarling_python-2.4.19-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 10.4 MB Sep 26, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.17+ x86-64	Details
cedarling_python-2.4.19-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 10.4 MB Sep 26, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.17+ x86-64	Details
cedarling_python-2.4.19-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 10.4 MB Sep 26, 2026	CPython 3.10	CPython 3.10	Linux glibc 2.17+ x86-64	Details

Total release size: 31.1 MB

Release files / cedarling_python-2.4.19-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	cedarling_python-2.4.19-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	10.4 MB
Tags	CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`0aaaa8d85e81a1f769a2a8f2f4f1e62d2c84b65de1981aa058751ea1ee6e8e33`
BLAKE2b-256 checksum How to use checksums	`dac4494520c61b6c3f4b24e38584106b9c58cce383f3620b587bd99b91f40aec`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JanssenProject/jans
Publishing commit: github.com/JanssenProject/jans/tree/371c3f026a50eeb1c4c0d17bf7412945f89b496a

Workflow

Publishing configuration: github.com/JanssenProject/jans/blob/371c3f026a50eeb1c4c0d17bf7412945f89b496a/.github/workflows/build-packages.yml
Publishing logs: github.com/JanssenProject/jans/actions/runs/36211486370/attempts/1

Artifact

Subject: cedarling_python-2.4.19-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: 0aaaa8d85e81a1f769a2a8f2f4f1e62d2c84b65de1981aa058751ea1ee6e8e33 Verifying attestations

Release files / cedarling_python-2.4.19-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	cedarling_python-2.4.19-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	10.4 MB
Tags	CPython 3.11 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`7cff7d1fdf11513ab314e58de80be8ed2a23603231e6f9cf02d3e2c7f8c6e0d9`
BLAKE2b-256 checksum How to use checksums	`a5a700cd9a3985c2bdf546beca1ed9162e8f163c1cdc5cebbd14de275c15dbce`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JanssenProject/jans
Publishing commit: github.com/JanssenProject/jans/tree/371c3f026a50eeb1c4c0d17bf7412945f89b496a

Workflow

Publishing configuration: github.com/JanssenProject/jans/blob/371c3f026a50eeb1c4c0d17bf7412945f89b496a/.github/workflows/build-packages.yml
Publishing logs: github.com/JanssenProject/jans/actions/runs/36211486370/attempts/1

Artifact

Subject: cedarling_python-2.4.19-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: 7cff7d1fdf11513ab314e58de80be8ed2a23603231e6f9cf02d3e2c7f8c6e0d9 Verifying attestations

Release files / cedarling_python-2.4.19-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	cedarling_python-2.4.19-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	10.4 MB
Tags	CPython 3.10 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`1f1f33d29f5fc3543adef010b103b6413aebffdb49dbc85ce2e42514507cb03b`
BLAKE2b-256 checksum How to use checksums	`daf3881e2948e6ac6e1d7e62113e5421f803c76d51cc3e6c915c6dc59c939e98`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JanssenProject/jans
Publishing commit: github.com/JanssenProject/jans/tree/371c3f026a50eeb1c4c0d17bf7412945f89b496a

Workflow

Publishing configuration: github.com/JanssenProject/jans/blob/371c3f026a50eeb1c4c0d17bf7412945f89b496a/.github/workflows/build-packages.yml
Publishing logs: github.com/JanssenProject/jans/actions/runs/36211486370/attempts/1

Artifact

Subject: cedarling_python-2.4.19-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
SHA-256 checksum: 1f1f33d29f5fc3543adef010b103b6413aebffdb49dbc85ce2e42514507cb03b Verifying attestations