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.

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}')

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.