Libreria client certificati di Azure Key Vault per Python - versione 4.7.0

  • Articolo

Azure Key Vault contribuisce a risolvere i problemi seguenti:

  • Gestione certificati (questa libreria) - Creare, gestire e distribuire certificati SSL/TLS pubblici e privati
  • Gestione delle chiavi crittografiche (azure-keyvault-keys) - creare, archiviare e controllare l'accesso alle chiavi usate per crittografare i dati
  • Gestione dei segreti (azure-keyvault-secrets) - Archiviare e controllare in modo sicuro l'accesso ai token, password, certificati, chiavi API e altri segreti
  • Amministrazione dell'insieme di credenziali (azure-keyvault-administration) - Controllo degli accessi in base al ruolo e opzioni di backup e ripristino a livello di insieme di credenziali

Codice | sorgente Pacchetto (PyPI) | Pacchetto (Conda) | Documentazione di | riferimento sulle API Documentazione | del prodotto Campioni

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691. Python 3.7 o versione successiva è necessario per usare questo pacchetto. Per altre informazioni, vedere Criteri di supporto per la versione di Azure SDK per Python.

Introduzione

Installare il pacchetto

Installare azure-keyvault-certificates e azure-identity con pip:

pip install azure-keyvault-certificates azure-identity

azure-identity viene usato per l'autenticazione di Azure Active Directory, come illustrato di seguito.

Prerequisiti

Autenticare il client

Per interagire con il servizio azure Key Vault, sarà necessaria un'istanza di CertificateClient, nonché un URL dell'insieme di credenziali e un oggetto credenziale. Questo documento illustra l'uso di un oggetto DefaultAzureCredential, appropriato per la maggior parte degli scenari, tra cui lo sviluppo locale e gli ambienti di produzione. È consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione.

Per altre informazioni su altri metodi di autenticazione e sui relativi tipi di credenziali corrispondenti, vedere la documentazione di azure-identity .

Creare un client

Dopo aver configurato l'ambiente per DefaultAzureCredential per usare un metodo appropriato di autenticazione, è possibile eseguire le operazioni seguenti per creare un client certificato (sostituendo il valore di VAULT_URL con l'URL dell'insieme di credenziali):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = CertificateClient(vault_url=VAULT_URL, credential=credential)

NOTA: Per un client asincrono, importare azure.keyvault.certificates.aioinvece.CertificateClient

Concetti chiave

CertificateClient

Con un CertificateClient è possibile ottenere certificati dall'insieme di credenziali, creare nuovi certificati e nuove versioni di certificati esistenti, aggiornare i metadati dei certificati ed eliminare i certificati. È anche possibile gestire le autorità di certificazione, i contatti e i criteri di gestione dei certificati. Questo argomento è illustrato negli esempi seguenti.

Esempio

Questa sezione contiene frammenti di codice che coprono le attività comuni:

Creare un certificato

begin_create_certificate crea un certificato da archiviare nell'Key Vault di Azure. Se esiste già un certificato con lo stesso nome, viene creata una nuova versione del certificato. Prima di creare un certificato, è possibile creare un criterio di gestione per il certificato o usare i criteri predefiniti. Questo metodo restituisce un poller di operazione a esecuzione prolungata.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

Se si vuole controllare lo stato della creazione del certificato, è possibile chiamare status() il poller o get_certificate_operation con il nome del certificato.

Recuperare un certificato

get_certificate recupera la versione più recente di un certificato archiviato in precedenza nella Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version recupera una versione specifica di un certificato.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

Aggiornare le proprietà di un certificato esistente

update_certificate_properties aggiorna un certificato archiviato in precedenza nella Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

Eliminare un certificato

begin_delete_certificate richieste Key Vault eliminare un certificato, restituendo un poller che consente di attendere il completamento dell'eliminazione. L'attesa è utile quando l'insieme di credenziali ha abilitato l'eliminazione temporanea e si vuole eliminare definitivamente il certificato non appena possibile. Quando l'eliminazione temporanea è disabilitata, begin_delete_certificate se stessa è permanente.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

Elencare le proprietà dei certificati

list_properties_of_certificates elenca le proprietà di tutti i certificati nella Key Vault specificata.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

Operazioni asincrone

Questa libreria include un set completo di API asincrone. Per usarli, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di azure-core .

I client e le credenziali asincroni devono essere chiusi quando non sono più necessari. Questi oggetti sono gestioni contesto asincrone e definiscono metodi asincroni close . Ad esempio:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Creare in modo asincrono un certificato

create_certificate crea un certificato da archiviare nell'Key Vault di Azure. Se esiste già un certificato con lo stesso nome, viene creata una nuova versione del certificato. Prima di creare un certificato, è possibile creare un criterio di gestione per il certificato o usare i criteri predefiniti. create_certificate In attesa di restituire il certificato creato se la creazione ha esito positivo e un CertificatoOperation se non lo è.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

Elencare in modo asincrono le proprietà dei certificati

list_properties_of_certificates elenca tutte le proprietà dei certificati nell'insieme di credenziali del client:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la azure-keyvault-certificatesguida alla risoluzione dei problemi .

Generale

Key Vault client generano eccezioni definite in azure-core. Ad esempio, se si tenta di ottenere una chiave che non esiste nell'insieme di credenziali, CertificateClient genera ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    certificate_client.get_certificate("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata del livello DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non attendibili, può essere abilitata in un client con l'argomento logging_enable :

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

La registrazione di traccia di rete può essere abilitata anche per qualsiasi singola operazione:

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

Passaggi successivi

Diversi esempi sono disponibili nel repository GitHub di Azure SDK per Python. Questi esempi forniscono codice di esempio per scenari di Key Vault aggiuntivi: | File | Descrizione | |-------------|-------------| | hello_world.py (versione asincrona) | certificati create/get/update/delete | | backup_restore_operations.py (versione asincrona) | eseguire il backup e il ripristino dei certificati | | import_certificate.py (versione asincrona) | importare i certificati PKCS#12 (PFX) e PEM formattati in Key Vault | | list_operations.py (versione asincrona) | certificati elenco | | recover_purge_operations.py (versione asincrona) | recuperare ed eliminare i certificati | | issuers.py (versione asincrona) | gestire le autorità di certificazione | | contacts.py (versione asincrona) | gestire i contatti del certificato | | parse_certificate.py (versione asincrona) | estrarre la chiave privata di un certificato |

Documentazione aggiuntiva

Per una documentazione più completa su Azure Key Vault, vedere la documentazione di riferimento sulle API.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Impression