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

  1. (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

  2. Ensure Rust is installed: Verify Rust installation by running:

    cargo --version

    If Rust is not installed, you can install it from here.

  3. Set up a virtual environment:

    • Install venv for your platform by following the instructions here.

    • Create a virtual environment:

      python3 -m venv venv

  4. 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

  5. Install maturin

    pip install maturin

    For Linux, install patchelf dependency:

    pip install maturin[patchelf]

  6. Clone the repository:

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

  7. Navigate to the cedarling_python folder:

    cd jans/jans-cedarling/bindings/cedarling_python

  8. Build and install the package: Build the Rust crate and install it into the virtual environment:

    maturin develop --release

  9. 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.

  10. 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

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

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.json"
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}%")

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:

  1. Complete the prerequisites

  2. Navigate to the cedarling_python folder:

    cd jans/jans-cedarling/bindings/cedarling_python

  3. 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:

  1. Make sure that you have installed the cedarling_python package in your virtual environment or system.

  2. Install pytest:

    pip install pytest

  3. Make sure that you are in the jans/jans-cedarling/bindings/cedarling_python/ folder.

  4. Run the following command:

    pytest

    Or run pytest without capturing the output:

    pytest -s

  5. See the results in the terminal.

Run test with tox

  1. Ensure that you installed rust compiler and toolchain. You can install it by following the official rust installation guide.

  2. Ensure tox is installed: You can install tox in your environment using pip:

    pip install tox

  3. Make sure that you are in the jans/jans-cedarling/bindings/cedarling_python/ folder.

  4. Run the following command:

    tox

  5. See the results in the terminal.

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.3.38)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for moabu from gravatar.com moabu

Credits

Author: Janssen Project

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.8

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

cedarling_python-2.3.20-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (10.1 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

cedarling_python-2.3.20-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (10.1 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

cedarling_python-2.3.20-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (10.1 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

File details

Details for the file cedarling_python-2.3.20-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cedarling_python-2.3.20-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 42d414f8f1a4211d9e57b5c07a7c5d976c7d55d00727cbb7f9b3d16ff66b02ca
MD5 464582928653457c84f81cdf7965769e
BLAKE2b-256 9a82a9b17ee597acc23ef58a62d79d0eaf3cc500b737aab7143a23546c0c6490

See more details on using hashes here.

Provenance

The following attestation bundles were made for cedarling_python-2.3.20-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build-packages.yml on JanssenProject/jans

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cedarling_python-2.3.20-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cedarling_python-2.3.20-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ec1ecd102640c4572fa2758eec7e7a41fd738a2778abf6312d4bc55cf857855a
MD5 aa4aeda76cffd066d5dc972e8a1b4903
BLAKE2b-256 0ff654c9f35c423b880033c43440b67fe1c2a303487c11705de8ea5197f9dda6

See more details on using hashes here.

Provenance

The following attestation bundles were made for cedarling_python-2.3.20-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build-packages.yml on JanssenProject/jans

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cedarling_python-2.3.20-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cedarling_python-2.3.20-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c9c5019d7fed5a4289838897fa3547a9ad20ca5d6ba23a6fff6dd1bccc9faefd
MD5 05b06e7bab6ae7441d3e946202c23e7e
BLAKE2b-256 7074c2175e659797864f1c05b9adc732272ac7ea0282b51f335fd759a341d8c3

See more details on using hashes here.

Provenance

The following attestation bundles were made for cedarling_python-2.3.20-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build-packages.yml on JanssenProject/jans

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.3.38

3 files

2.3.37

3 files

2.3.36

3 files

2.3.35

3 files

2.3.34

3 files

2.3.33

3 files

2.3.32

3 files

2.3.31

3 files

2.3.30

3 files

2.3.29

3 files

2.3.28

3 files

2.3.27

3 files

2.3.26

3 files

2.3.25

3 files

2.3.24

3 files

2.3.23

3 files

2.3.22

3 files

2.3.21

3 files

This release

2.3.20 This release

3 files

2.3.19

3 files

2.3.18

3 files

2.3.17

3 files

2.3.16

3 files

2.3.15

3 files

2.3.14

3 files

2.3.13

3 files

2.3.12

3 files

2.3.11

3 files

2.3.10

3 files

2.3.9

3 files

2.3.8

3 files

2.3.7

3 files

2.3.6

3 files

2.3.5

3 files

2.3.4

3 files

2.3.3

3 files

2.3.2

3 files

2.3.1

3 files

2.3.0

3 files

2.2.36

3 files

2.2.35

3 files

2.2.34

3 files

2.2.33

3 files

2.2.32

3 files

2.2.31

3 files

2.2.30

3 files

2.2.29

3 files

2.2.28

3 files

2.2.27

3 files

2.2.26

3 files

2.2.25

3 files

2.2.24

3 files

2.2.23

3 files

2.2.22

3 files

2.2.21

3 files

2.2.20

3 files

2.2.19

3 files

2.2.18

3 files

2.2.17

3 files

2.2.16

3 files

2.2.15

3 files

2.2.14

3 files

2.2.13

3 files

2.2.12

3 files

2.2.11

3 files

2.2.10

3 files

2.2.9

3 files

2.2.8

3 files

2.2.7

3 files

2.2.6

3 files

2.2.5

3 files

2.2.4

3 files

2.2.3

3 files

2.2.2

3 files

2.2.1

3 files

2.2.0

3 files

0.0.36

3 files

0.0.35

3 files

0.0.34

3 files

0.0.33

3 files

0.0.32

3 files

0.0.31

3 files

0.0.30

3 files

0.0.29

3 files

0.0.28

3 files

0.0.27

3 files

0.0.26

3 files

0.0.25

3 files

0.0.24

3 files

0.0.23

3 files

0.0.22

3 files

0.0.21

3 files

0.0.20

3 files

0.0.19

3 files

0.0.18

3 files

0.0.17

3 files

0.0.16

3 files

0.0.15

3 files

0.0.14

3 files

0.0.13

3 files

0.0.12

3 files

0.0.11

3 files

0.0.10

3 files

0.0.9

3 files

0.0.8

3 files

0.0.7

3 files

0.0.6

3 files

0.0.5

3 files

0.0.4

3 files

0.0.3

3 files

0.0.2

4 files

0.0.1

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page