Skip to main content

spiffe package

Overview

The spiffe package, part of the py-spiffe library, provides SPIFFE support and essential tools for interacting with the SPIFFE Workload API. It simplifies the management and validation of SPIFFE identities, supporting X509-SVIDs, JWT-SVIDs, and X.509 CA and JWKS Bundles.

Features

  • Automatic Management of SPIFFE Identities: Streamlines fetching, renewing, and validation of X.509 and JWT SVIDs.
  • Seamless Integration with SPIFFE Workload API: Facilitates communication with SPIRE or other SPIFFE Workload API compliant systems.
  • Continuous Update Handling: Automatically receives and applies updates for SVIDs and bundles, ensuring your application always uses valid certificates.

Prerequisites

  • A running instance of SPIRE or another SPIFFE Workload API implementation.
  • The SPIFFE_ENDPOINT_SOCKET environment variable set to the address of the Workload API (e.g., unix: /tmp/spire-agent/public/api.sock), or provided programmatically.

Usage

Below are examples demonstrating the core functionalities of the spiffe package.

WorkloadApiClient

from spiffe import WorkloadApiClient

# Fetch X.509 and JWT SVIDs
with WorkloadApiClient() as client:
    x509_svid = client.fetch_x509_svid()
    print(f'SPIFFE ID: {x509_svid.spiffe_id}')

    jwt_svid = client.fetch_jwt_svid(audience={"test"})
    print(f'SPIFFE ID: {jwt_svid.spiffe_id}')

By default, blocking Workload API calls wait without a deadline. To avoid indefinitely blocking a calling thread when the Workload API is unresponsive, set default_timeout on the client or pass a per-call timeout in seconds:

with WorkloadApiClient(default_timeout=5.0) as client:
    jwt_svid = client.fetch_jwt_svid(audience={"test"})
    jwt_svid = client.fetch_jwt_svid(audience={"test"}, timeout=1.0)

Per-call timeouts override default_timeout. Deadline expiry is reported as the SPIFFE-specific error for the call, such as FetchJwtSvidError. Timeouts do not apply to long-lived streaming methods.

When a workload is entitled to more than one identity, the Workload API may attach an operator-defined hint (for example internal or external) to each SVID. The hint is exposed on X509Svid and JwtSvid, and is an empty string when not set:

with WorkloadApiClient() as client:
    svids = client.fetch_x509_svids()
    external = next((s for s in svids if s.hint == 'external'), None)

The hint is metadata that the local Workload API attaches to the workload's own SVIDs. It is not part of the certificate or token, is not authenticated, and is never sent to peers, so it must not be used to authorize a peer. SVIDs obtained by validating a peer's token (JwtSvid.parse_and_validate(), WorkloadApiClient.validate_jwt_svid()) always have an empty hint.

Handling a missing or unexpected hint is the workload's responsibility. Servers must keep non-empty hints unique. If a response nevertheless contains more than one SVID with the same hint, the client keeps only the first one, as the SPIFFE Workload API specification recommends. The trust bundles of skipped X.509-SVIDs are still added to the X.509 context. SVIDs without a hint are never dropped.

X509Source

from spiffe import X509Source

# Automatically manage X.509 SVIDs and CA bundles
with X509Source() as source:
    x509_svid = source.svid
    print(f'SPIFFE ID: {x509_svid.spiffe_id}')

When the workload receives more than one X.509-SVID, pass an svid_picker to choose which one the source uses, for example by hint. The picker is called with all SVIDs on every Workload API update, not only at startup, and the chosen SVID is what the source (and spiffe-tls) serves.

If the picker raises, the source fails closed: it is closed permanently and does not recover when a later update would match again. This applies to any update, so renaming or removing the expected hint at runtime takes the source (and any TLS context built on it) out of service until the process creates a new source. Raise a descriptive error when no SVID matches:

from spiffe import X509Source


def pick_internal(svids):
    for svid in svids:
        if svid.hint == 'internal':
            return svid
    raise ValueError("no X.509-SVID with hint 'internal'")


with X509Source(svid_picker=pick_internal) as source:
    x509_svid = source.get_x509_context().default_svid
    print(f'SPIFFE ID: {x509_svid.spiffe_id}, hint: {x509_svid.hint}')

JwtSource

from spiffe import JwtSource

# Manage and validate JWT SVIDs and JWKS bundles
with JwtSource() as source:
    jwt_svid = source.fetch_svid(audience={'test'})
    print(f'SPIFFE ID: {jwt_svid.spiffe_id}')
    print(f'Token: {jwt_svid.token}')

Contributing

We welcome contributions to the spiffe package! Please see our contribution guidelines for more details. For feedback and issues, please submit them through the GitHub issue tracker.

Metadata

Release files for spiffe 0.4.0

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

Source distribution (sdist)

Source distribution for spiffe 0.4.0
File Size Uploaded Provenance Actions
spiffe-0.4.0.tar.gz 44.7 kB Without provenance Details for spiffe-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spiffe 0.4.0
File Interpreter ABI Platform Actions
spiffe-0.4.0-py3-none-any.whl Python 3 none any Details for spiffe-0.4.0-py3-none-any.whl

Total release size: 106.5 kB

Release files / spiffe-0.4.0.tar.gz

Download URL spiffe-0.4.0.tar.gz
Size 44.7 kB
Tags Source
SHA-256 checksum
How to use checksums
47372f000c489e4f7d2b810fd33ee1ff1e574d327116996c11e93fa47831f2bd
BLAKE2b-256 checksum
How to use checksums
0ceb05f82d87b9f7f0b714c887768c4941595fd35cfcbb0a6ea5e0adceee011c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / spiffe-0.4.0-py3-none-any.whl

Download URL spiffe-0.4.0-py3-none-any.whl
Size 61.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7eb153709314e0bff86975cb4f20b1da8d949360e1d630eeda1ac20d0524117c
BLAKE2b-256 checksum
How to use checksums
c66998212b7564db9ad87acee5eb882ff0f5abddcb95739f9606834696f9eae3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for spiffe 0.4.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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