OpenStack Barbican Client Library

7.3.0 · active · verified Thu Apr 16

python-barbicanclient is the official Python client library for interacting with the OpenStack Barbican Key Management API. It provides programmatic access to store, manage, and retrieve secrets, and also includes a command-line interface (`barbican`). The library is actively maintained as part of the OpenStack ecosystem, with releases generally aligning with OpenStack's development cadence. The current version is 7.3.0.

Common errors

```
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).
```
cause 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.

fix Ensure 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
```
cause 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.

fix Double-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
```
cause 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.

fix Check 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
```
cause 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.

fix Verify 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.

Warnings

gotcha Authentication 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.
Fix: Verify that your `keystoneauth1` configuration correctly reflects your OpenStack environment's Keystone API version and required parameters. Use `os.environ.get()` for robustness in scripts.
gotcha Using 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.
Fix: Always 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.
gotcha Exceeding Barbican's configured secret size limits will result in a `413 Request Entity Too Large` error.
Fix: Check 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.
breaking OpenStack 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.
Fix: Regularly 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.

Install

pip install python-barbicanclient Install Barbican Client

Imports

Client
wrong:
```
from barbicanclient import Client
```
correct:
```
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.

Quickstart

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.")

view raw JSON →