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_SOCKETenvironment 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.