tessl/pypi-azure-keyvault

Microsoft Azure Key Vault Client Libraries for Python providing unified access to keys, secrets, and certificates

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Secret Management

Name: tessl/pypi-azure-keyvault
Author: tessl

Secure storage and retrieval of sensitive data in Azure Key Vault. Supports text-based secrets with version management, expiration policies, access control, and content type specifications. Provides complete lifecycle management including creation, updating, soft deletion, and recovery.

Capabilities

Secret Client

Main client for secret management operations with synchronous and asynchronous support.

class SecretClient:
    def __init__(self, vault_url: str, credential, **kwargs):
        """
        Initialize SecretClient for secret management operations.
        
        Parameters:
        - vault_url: str, Key Vault URL (https://vault-name.vault.azure.net/)
        - credential: Azure credential object for authentication
        - api_version: ApiVersion, API version to use (default: latest)
        - **kwargs: Additional configuration options
        """

    def close(self) -> None:
        """Close the client and release resources."""

Secret Creation and Updates

Store and update secrets in the vault.

def set_secret(self, name: str, value: str, **kwargs) -> KeyVaultSecret:
    """
    Create or update a secret in the Key Vault.
    
    Parameters:
    - name: str, unique secret name within the vault
    - value: str, secret value to store
    - content_type: str, MIME type or description of secret content
    - enabled: bool, whether secret is enabled for use
    - expires_on: datetime, expiration date
    - not_before: datetime, activation date
    - tags: Dict[str, str], custom metadata
    
    Returns:
    KeyVaultSecret with secret metadata (value not included)
    """

Secret Retrieval

Retrieve secrets and their versions from the vault.

def get_secret(self, name: str, version: str = None, **kwargs) -> KeyVaultSecret:
    """
    Get a secret from the vault.
    
    Parameters:
    - name: str, secret name
    - version: str, specific version (default: latest)
    
    Returns:
    KeyVaultSecret with secret value and metadata
    """

def list_properties_of_secrets(**kwargs) -> ItemPaged[SecretProperties]:
    """
    List all secrets in the vault.
    
    Parameters:
    - max_page_size: int, maximum items per page
    
    Returns:
    Paginated list of SecretProperties (values not included)
    """

def list_properties_of_secret_versions(self, name: str, **kwargs) -> ItemPaged[SecretProperties]:
    """
    List all versions of a specific secret.
    
    Parameters:
    - name: str, secret name
    - max_page_size: int, maximum items per page
    
    Returns:
    Paginated list of SecretProperties for all versions
    """

Secret Operations

Update properties, delete, and manage secret lifecycle.

def update_secret_properties(self, name: str, version: str = None, **kwargs) -> SecretProperties:
    """
    Update secret properties and metadata.
    
    Parameters:
    - name: str, secret name
    - version: str, specific version (default: latest)
    - content_type: str, MIME type or description
    - enabled: bool, enable/disable secret
    - expires_on: datetime, expiration date
    - not_before: datetime, activation date
    - tags: Dict[str, str], custom metadata
    
    Returns:
    SecretProperties with updated properties
    """

def begin_delete_secret(self, name: str, **kwargs) -> LROPoller[DeletedSecret]:
    """
    Delete a secret (soft delete) - long-running operation.
    
    Parameters:
    - name: str, secret name to delete
    
    Returns:
    LROPoller[DeletedSecret] for tracking deletion progress
    """

def get_deleted_secret(self, name: str, **kwargs) -> DeletedSecret:
    """
    Get properties of a deleted secret.
    
    Parameters:
    - name: str, deleted secret name
    
    Returns:
    DeletedSecret with deletion information and value
    """

def begin_recover_deleted_secret(self, name: str, **kwargs) -> LROPoller[KeyVaultSecret]:
    """
    Recover a deleted secret - long-running operation.
    
    Parameters:
    - name: str, deleted secret name
    
    Returns:
    LROPoller[KeyVaultSecret] for tracking recovery progress
    """

def purge_deleted_secret(self, name: str, **kwargs) -> None:
    """
    Permanently delete a secret.
    
    Parameters:
    - name: str, deleted secret name to purge
    """

def list_deleted_secrets(**kwargs) -> ItemPaged[DeletedSecret]:
    """
    List all deleted secrets.
    
    Returns:
    Paginated list of DeletedSecret objects
    """

Secret Backup and Restore

Backup and restore secrets for disaster recovery.

def backup_secret(self, name: str, **kwargs) -> bytes:
    """
    Create backup of a secret.
    
    Parameters:
    - name: str, secret name to backup
    
    Returns:
    bytes containing encrypted backup data
    """

def restore_secret_backup(self, backup: bytes, **kwargs) -> SecretProperties:
    """
    Restore secret from backup.
    
    Parameters:
    - backup: bytes, backup data from backup_secret()
    
    Returns:
    SecretProperties with restored secret metadata
    """

Secret Model Classes

class KeyVaultSecret:
    """Represents a secret stored in Azure Key Vault."""
    id: str
    name: str
    properties: SecretProperties
    value: str  # Only populated when retrieving secret value

class SecretProperties:
    """Secret metadata and properties."""
    id: str
    name: str
    version: str
    enabled: bool
    expires_on: datetime
    not_before: datetime
    created_on: datetime
    updated_on: datetime
    recovery_level: str
    vault_url: str
    content_type: str
    tags: Dict[str, str]

class DeletedSecret:
    """Represents a deleted secret."""
    id: str
    name: str
    properties: SecretProperties
    value: str
    deleted_on: datetime
    recovery_id: str
    scheduled_purge_date: datetime

class KeyVaultSecretIdentifier:
    """Identifier for Key Vault secrets."""
    source_id: str
    vault_url: str
    name: str
    version: str

Usage Examples

Basic Secret Management

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

# Initialize client
credential = DefaultAzureCredential()
client = SecretClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)

# Store a secret
secret = client.set_secret("database-password", "super-secret-password")
print(f"Stored secret: {secret.name} (ID: {secret.id})")

# Retrieve secret value
retrieved_secret = client.get_secret("database-password")
print(f"Secret value: {retrieved_secret.value}")

# List all secrets
for secret_properties in client.list_properties_of_secrets():
    print(f"Secret: {secret_properties.name}")

Secret with Metadata

from datetime import datetime, timedelta

# Store secret with metadata and expiration
expiry_date = datetime.utcnow() + timedelta(days=365)

secret = client.set_secret(
    name="api-key",
    value="sk-1234567890abcdef",
    content_type="text/plain",
    expires_on=expiry_date,
    tags={
        "environment": "production",
        "service": "payment-api",
        "owner": "team-alpha"
    }
)

# Update secret properties
updated_properties = client.update_secret_properties(
    name="api-key",
    tags={
        "environment": "production", 
        "service": "payment-api",
        "owner": "team-beta",  # Changed owner
        "last-rotated": "2024-01-15"
    }
)

Secret Versioning

# Create initial version
secret_v1 = client.set_secret("connection-string", "Server=old-server;Database=app")

# Update secret (creates new version)
secret_v2 = client.set_secret("connection-string", "Server=new-server;Database=app")

# Get latest version
latest_secret = client.get_secret("connection-string")

# Get specific version
specific_secret = client.get_secret("connection-string", version=secret_v1.properties.version)

# List all versions
for version_properties in client.list_properties_of_secret_versions("connection-string"):
    print(f"Version: {version_properties.version}, Created: {version_properties.created_on}")

Backup and Recovery

# Backup secret
backup_data = client.backup_secret("important-secret")

# Delete secret (soft delete)
delete_poller = client.begin_delete_secret("important-secret")
deleted_secret = delete_poller.result()  # Wait for completion
print(f"Secret deleted on: {deleted_secret.deleted_on}")

# Restore from backup
restored_properties = client.restore_secret_backup(backup_data)

# Or recover deleted secret
recover_poller = client.begin_recover_deleted_secret("important-secret")
recovered_secret = recover_poller.result()  # Wait for completion

# Permanently delete
client.purge_deleted_secret("important-secret")

Working with Different Content Types

# JSON configuration
config = {
    "database_url": "postgresql://user:pass@host:5432/db",
    "redis_url": "redis://localhost:6379/0",
    "debug": False
}

client.set_secret(
    name="app-config",
    value=json.dumps(config),
    content_type="application/json"
)

# Certificate/PEM data
cert_data = """-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----"""

client.set_secret(
    name="ssl-certificate", 
    value=cert_data,
    content_type="application/x-pem-file"
)

# Connection string
client.set_secret(
    name="storage-connection",
    value="DefaultEndpointsProtocol=https;AccountName=...",
    content_type="text/plain"
)

Async Secret Operations

from azure.keyvault.secrets.aio import SecretClient
import asyncio

async def manage_secrets():
    credential = DefaultAzureCredential()
    client = SecretClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)
    
    try:
        # Async secret operations
        secret = await client.set_secret("async-secret", "async-value")
        retrieved = await client.get_secret("async-secret")
        
        # Async iteration
        async for secret_properties in client.list_properties_of_secrets():
            print(f"Secret: {secret_properties.name}")
            
    finally:
        await client.close()

# Run async function
asyncio.run(manage_secrets())

Install with Tessl CLI