Install & Compatibility
Where this runs
tested against v7.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.792s · 66.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.3s · import 0.730s · 68MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from barbicanclient import client
✗ from barbicanclient import Client
The primary client class is named `Client` and resides within the `barbicanclient.client` module, not directly under the `barbicanclient` package namespace.
Session
✓ from keystoneauth1 import session
Used to create an authenticated session for the Barbican client, especially when interacting with OpenStack Keystone for authentication.
Password
✓ from keystoneclient.auth import identity
Specifically, `identity.v3.Password` is commonly used for password-based authentication with Keystone v3.
This quickstart demonstrates how to authenticate with OpenStack Keystone and then use the `python-barbicanclient` to create and store a simple secret. It assumes environment variables are set for OpenStack authentication, which is a common practice.
import os
from keystoneclient.auth import identity
from keystoneauth1 import session
from barbicanclient import client
# Configure Keystone authentication using environment variables
auth_url = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')
username = os.environ.get('OS_USERNAME', 'admin')
user_domain_name = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
password = os.environ.get('OS_PASSWORD', 'password')
project_name = os.environ.get('OS_PROJECT_NAME', 'demo')
project_domain_name = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
barbican_endpoint = os.environ.get('OS_BARBICAN_ENDPOINT', 'http://localhost:9311/v1')
# Create a Keystone authentication plugin
auth = identity.v3.Password(
auth_url=auth_url,
username=username,
user_domain_name=user_domain_name,
password=password,
project_name=project_name,
project_domain_name=project_domain_name
)
# Create a Keystone session
sess = session.Session(auth=auth)
# Create a Barbican client instance
# Pass the Barbican endpoint directly if not discoverable via Keystone catalog
barbican = client.Client(session=sess, endpoint=barbican_endpoint, version='v1')
# Example: Create and store a secret
try:
secret_name = "my-test-secret"
payload = "my_sensitive_data_123"
secret = barbican.secrets.create(name=secret_name, payload=payload)
secret.store()
print(f"Secret '{secret_name}' stored with URI: {secret.secret_ref}")
# Example: Retrieve the secret
retrieved_secret = barbican.secrets.get(secret.secret_ref)
print(f"Retrieved secret name: {retrieved_secret.name}")
# Note: To retrieve the actual payload, you would typically call .payload on the retrieved secret,
# but direct payload retrieval for security reasons is often handled carefully and might require specific permissions/methods.
# For this example, we just show retrieval of metadata.
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure Barbican and Keystone services are running and accessible.")
print("Check environment variables like OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_BARBICAN_ENDPOINT.")
barbican --version
Debug
Known issues
gotchaAuthentication failures are common due to incorrect or incomplete Keystone client configuration. Ensure all necessary authentication parameters (e.g., `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, `OS_USER_DOMAIN_NAME`, `OS_PROJECT_DOMAIN_NAME`) are correctly set in environment variables or passed explicitly.fixVerify that your `keystoneauth1` configuration correctly reflects your OpenStack environment's Keystone API version and required parameters. Use `os.environ.get()` for robustness in scripts.
affects: All versions
gotchaUsing the `--insecure` or `insecure=True` option disables TLS certificate verification, which is highly discouraged in production environments as it exposes communications to man-in-the-middle attacks.fixAlways use proper TLS certificates and ensure your client is configured to verify them. If running in an internal or controlled environment, ensure proper CA certificates are configured via `OS_CACERT` or similar mechanisms.
affects: All versions
gotchaExceeding Barbican's configured secret size limits will result in a `413 Request Entity Too Large` error.fixCheck the Barbican service configuration for maximum payload sizes. If you need to store larger data, consider alternative storage or breaking down the secret into smaller parts, if appropriate for your security model.
affects: All versions
breakingOpenStack projects, including Barbican and its client, evolve. While `python-barbicanclient` aims for backward compatibility, significant changes in the Barbican API (e.g., new secret types, updated resource models, or authentication flow changes) in major OpenStack releases can sometimes necessitate updates to the client library or your code. Explicitly specifying the API `version` (e.g., `version='v1'`) when initializing the client is good practice.fixRegularly consult the official OpenStack Barbican documentation and release notes for your specific OpenStack deployment. Ensure your `python-barbicanclient` version is compatible with your Barbican service version.
affects: Across major OpenStack releases (e.g., from Pike to Train)
Errors
Common errors & fixes
ERROR: please specify the following --os-project-id or (--os-project-name and --os-project-domain-name) or (--os-project-name and --os-project-domain-id).
The Barbican client, via Keystone authentication, requires clear identification of the project context. This error indicates that the project-related authentication variables are missing or incorrectly configured.
fixEnsure that `OS_PROJECT_NAME` and `OS_PROJECT_DOMAIN_NAME` (or `OS_PROJECT_ID`) are set in your environment variables or passed directly to the `identity.v3.Password` constructor.
barbicanclient.exceptions.HTTPAuthError: (HTTP 401) Unauthorized
This typically means the provided authentication credentials (username, password) are incorrect, the token has expired, or the user lacks permissions to access the Barbican service.
fixDouble-check your `OS_USERNAME` and `OS_PASSWORD` (or equivalent) for correctness. Verify the `OS_AUTH_URL` is correct and Keystone is reachable. Ensure the user has the necessary roles and permissions within the specified project to interact with Barbican.
barbicanclient.exceptions.HTTPServerError: (HTTP 500) Internal Server Error
A generic server-side error, indicating an issue within the Barbican service itself, rather than a client-side problem with the request format or authentication.
fixCheck the Barbican service logs for more detailed error messages. This might indicate issues with Barbican's backend, database, or specific plugin configurations. Contact your OpenStack administrator if you do not manage the Barbican service.
barbicanclient.exceptions.HTTPClientError: (HTTP 404) Not Found
Often occurs when attempting to access a secret or resource using an incorrect or non-existent `secret_ref` (URI) or if the Barbican endpoint URL is wrong.
fixVerify that the `secret_ref` being used is correct and still valid. Confirm that the Barbican endpoint URL passed to `client.Client` is accurate and the service is accessible.
Upgrade
Version history
7.4.0latest on PyPI · released May 19, 2026
Audit
Dependencies
keystoneauth1requiredRequired for authenticating with OpenStack Keystone, which is commonly used to access Barbican. The client integrates with keystoneauth1 sessions for authentication.
requestsrequiredUsed for making HTTP requests to the Barbican API.