azure.keyvault.certificates.aio package

Submodules

azure.keyvault.certificates.aio.client module

Module contents

class azure.keyvault.certificates.aio.CertificateClient(vault_url: str, credential: TokenCredential, **kwargs)[source]

Bases: azure.keyvault.certificates._shared.async_client_base.AsyncKeyVaultClientBase

A high-level asynchronous interface for managing a vault’s certificates.

Parameters:
  • vault_url (str) – URL of the vault the client will access
  • credential – An object which can provide an access token for the vault, such as a credential from azure.identity.aio
Keyword Arguments:
 
  • api_version (str) – version of the Key Vault API to use. Defaults to the most recent.
  • transport (AsyncHttpTransport) – transport to use. Defaults to AioHttpTransport.

Example

Creates a new instance of the Certificate client

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

# Create a KeyVaultCertificate using default Azure credentials
credential = DefaultAzureCredential()
certificate_client = CertificateClient(vault_url=vault_url, credential=credential)

backup_certificate(certificate_name: str, **kwargs) → bytes[source]

Back up a certificate in a protected form useable only by Azure Key Vault.

Requires certificates/backup permission. This is intended to allow copying a certificate from one vault to another. Both vaults must be owned by the same Azure subscription. Also, backup / restore cannot be performed across geopolitical boundaries. For example, a backup from a vault in a USA region cannot be restored to a vault in an EU region.

Parameters:certificate_name (str) – The name of the certificate.
Returns:The backup blob containing the backed up certificate.
Return type:bytes
Raises:ResourceNotFoundError if the certificate doesn’t exist, HttpResponseError for other errors

Example

Get a certificate backup

# backup certificate
certificate_backup = await certificate_client.backup_certificate(cert_name)

# returns the raw bytes of the backed up certificate
print(certificate_backup)

cancel_certificate_operation(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.CertificateOperation[source]

Cancels an in-progress certificate operation. Requires the certificates/update permission.

Parameters:certificate_name (str) – The name of the certificate.
Returns:The cancelled certificate operation
Return type:CertificateOperation
Raises:HttpResponseError
create_certificate(certificate_name: str, policy: azure.keyvault.certificates._models.CertificatePolicy, **kwargs) → Union[azure.keyvault.certificates._models.KeyVaultCertificate, azure.keyvault.certificates._models.CertificateOperation][source]

Creates a new certificate.

If this is the first version, the certificate resource is created. This operation requires the certificates/create permission. The poller requires the certificates/get permission, otherwise raises an HttpResponseError

Parameters:
  • certificate_name (str) – The name of the certificate.
  • policy (CertificatePolicy) – The management policy for the certificate.
Keyword Arguments:
 
  • enabled (bool) – Whether the certificate is enabled for use.
  • tags (dict[str, str]) – Application specific metadata in the form of key-value pairs.
Returns:

A coroutine for the creation of the certificate. Awaiting the coroutine returns the created KeyVaultCertificate if creation is successful, the CertificateOperation if not.

Return type:

KeyVaultCertificate or CertificateOperation

Raises:

HttpResponseError

Example

Create a certificate
from azure.keyvault.certificates import CertificatePolicy, CertificateContentType, WellKnownIssuerNames

# specify the certificate policy
cert_policy = CertificatePolicy(
    issuer_name=WellKnownIssuerNames.self,
    subject="CN=*.microsoft.com",
    san_dns_names=["sdk.azure-int.net"],
    exportable=True,
    key_type="RSA",
    key_size=2048,
    reuse_key=False,
    content_type=CertificateContentType.pkcs12,
    validity_in_months=24,
)
cert_name = "cert-name"

certificate = await certificate_client.create_certificate(
    certificate_name=cert_name, policy=cert_policy
)

print(certificate.id)
print(certificate.name)
print(certificate.policy.issuer_name)

create_issuer(issuer_name: str, provider: str, **kwargs) → azure.keyvault.certificates._models.CertificateIssuer[source]

Sets the specified certificate issuer. Requires certificates/setissuers permission.

Parameters:
  • issuer_name (str) – The name of the issuer.
  • provider (str) – The issuer provider.
Keyword Arguments:
 
  • enabled (bool) – Whether the issuer is enabled for use.
  • account_id (str) – The user name/account name/account id.
  • password (str) – The password/secret/account key.
  • organization_id (str) – Id of the organization
  • admin_contacts (list[AdministratorContact]) – Contact details of the organization administrators of the certificate issuer.
Returns:

The created CertificateIssuer

Return type:

CertificateIssuer

Raises:

HttpResponseError

Example

Create an issuer
from azure.keyvault.certificates import AdministratorContact

# First we specify the AdministratorContact for a issuer.
admin_contacts = [
    AdministratorContact(first_name="John", last_name="Doe", email="admin@microsoft.com", phone="4255555555")
]

issuer = await certificate_client.create_issuer(
    issuer_name="issuer1", provider="Test", account_id="keyvaultuser", admin_contacts=admin_contacts, enabled=True
)

print(issuer.name)
print(issuer.provider)
print(issuer.account_id)

for contact in issuer.admin_contacts:
    print(contact.first_name)
    print(contact.last_name)
    print(contact.email)
    print(contact.phone)

delete_certificate(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.DeletedCertificate[source]

Delete all versions of a certificate. Requires certificates/delete permission.

If the vault has soft-delete enabled, deletion may take several seconds to complete.

Parameters:certificate_name (str) – The name of the certificate.
Returns:The deleted certificate
Return type:DeletedCertificate
Raises:ResourceNotFoundError if the certificate doesn’t exist, HttpResponseError for other errors

Example

Delete a certificate

# delete a certificate
deleted_certificate = await certificate_client.delete_certificate(cert_name)

print(deleted_certificate.name)

# if the vault has soft-delete enabled, the certificate's
# scheduled purge date, deleted_on, and recovery id are available
print(deleted_certificate.deleted_on)
print(deleted_certificate.scheduled_purge_date)
print(deleted_certificate.recovery_id)

delete_certificate_operation(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.CertificateOperation[source]

Deletes and stops the creation operation for a specific certificate.

Requires the certificates/update permission.

Parameters:certificate_name (str) – The name of the certificate.
Returns:The deleted CertificateOperation
Return type:CertificateOperation
Raises:ResourceNotFoundError if the operation doesn’t exist, HttpResponseError for other errors
delete_contacts(**kwargs) → List[azure.keyvault.certificates._models.CertificateContact][source]

Deletes the certificate contacts for the key vault. Requires the certificates/managecontacts permission.

Returns:The deleted contacts for the key vault.
Return type:list[CertificateContact]
Raises:HttpResponseError

Example

Delete contacts

deleted_contacts = await certificate_client.delete_contacts()

for deleted_contact in deleted_contacts:
    print(deleted_contact.name)
    print(deleted_contact.email)
    print(deleted_contact.phone)

delete_issuer(issuer_name: str, **kwargs) → azure.keyvault.certificates._models.CertificateIssuer[source]

Deletes the specified certificate issuer.

Requires certificates/manageissuers/deleteissuers permission.

Parameters:issuer_name (str) – The name of the issuer.
Returns:CertificateIssuer
Return type:CertificateIssuer
Raises:HttpResponseError

Example

Delete an issuer

deleted_issuer = await certificate_client.delete_issuer("issuer1")

print(deleted_issuer.name)
print(deleted_issuer.provider)
print(deleted_issuer.account_id)

for contact in deleted_issuer.admin_contacts:
    print(contact.first_name)
    print(contact.last_name)
    print(contact.email)
    print(contact.phone)

get_certificate(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Gets a certificate with its management policy attached. Requires certificates/get permission.

Does not accept the version of the certificate as a parameter. To get a specific version of the certificate, call get_certificate_version().

Parameters:certificate_name (str) – The name of the certificate in the given vault.
Returns:An instance of KeyVaultCertificate
Return type:KeyVaultCertificate
Raises:ResourceNotFoundError if the certificate doesn’t exist, HttpResponseError for other errors

Example

Get a certificate

# get the latest version of a certificate
certificate = await certificate_client.get_certificate(cert_name)

print(certificate.id)
print(certificate.name)
print(certificate.policy.issuer_name)

get_certificate_operation(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.CertificateOperation[source]

Gets the creation operation of a certificate. Requires the certificates/get permission.

Parameters:certificate_name (str) – The name of the certificate.
Returns:The created CertificateOperation
Return type:CertificateOperation
Raises:ResourceNotFoundError if the certificate doesn’t exist, HttpResponseError for other errors
get_certificate_policy(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.CertificatePolicy[source]

Gets the policy for a certificate. Requires certificates/get permission.

Returns the specified certificate policy resources in the key vault.

Parameters:certificate_name (str) – The name of the certificate in a given key vault.
Returns:The certificate policy
Return type:CertificatePolicy
Raises:HttpResponseError
get_certificate_version(certificate_name: str, version: str, **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Gets a specific version of a certificate without returning its management policy.

Requires certificates/get permission. To get the latest version of the certificate, or to get the certificate’s policy as well, call get_certificate().

Parameters:
  • certificate_name (str) – The name of the certificate in the given vault.
  • version (str) – The version of the certificate.
Returns:

An instance of KeyVaultCertificate

Return type:

KeyVaultCertificate

Raises:

ResourceNotFoundError if the certificate doesn’t exist, HttpResponseError for other errors

Example

Get a certificate

# get the latest version of a certificate
certificate = await certificate_client.get_certificate(cert_name)

print(certificate.id)
print(certificate.name)
print(certificate.policy.issuer_name)

get_contacts(**kwargs) → List[azure.keyvault.certificates._models.CertificateContact][source]

Gets the certificate contacts for the key vault. Requires the certificates/managecontacts permission.

Returns:The certificate contacts for the key vault.
Return type:list[azure.keyvault.certificates.CertificateContact]
Raises:HttpResponseError

Example

Get contacts

contacts = await certificate_client.get_contacts()

# Loop through the certificate contacts for this key vault.
for contact in contacts:
    print(contact.name)
    print(contact.email)
    print(contact.phone)

get_deleted_certificate(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.DeletedCertificate[source]

Get a deleted certificate. Possible only in a vault with soft-delete enabled.

Requires certificates/get permission. Retrieves the deleted certificate information plus its attributes, such as retention interval, scheduled permanent deletion, and the current deletion recovery level.

Parameters:certificate_name (str) – The name of the certificate.
Returns:The deleted certificate
Return type:DeletedCertificate
Raises:ResourceNotFoundError if the certificate doesn’t exist, HttpResponseError for other errors

Example

Get a deleted certificate

# get a deleted certificate (requires soft-delete enabled for the vault)
deleted_certificate = await certificate_client.get_deleted_certificate("cert-name")
print(deleted_certificate.name)

get_issuer(issuer_name: str, **kwargs) → azure.keyvault.certificates._models.CertificateIssuer[source]

Gets the specified certificate issuer. Requires certificates/manageissuers/getissuers permission.

Parameters:issuer_name (str) – The name of the issuer.
Returns:The specified certificate issuer.
Return type:CertificateIssuer
Raises:ResourceNotFoundError if the issuer doesn’t exist, HttpResponseError for other errors

Example

Get an issuer

issuer = await certificate_client.get_issuer("issuer1")

print(issuer.name)
print(issuer.provider)
print(issuer.account_id)

for contact in issuer.admin_contacts:
    print(contact.first_name)
    print(contact.last_name)
    print(contact.email)
    print(contact.phone)

import_certificate(certificate_name: str, certificate_bytes: bytes, **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Import a certificate created externally. Requires certificates/import permission.

Imports an existing valid certificate, containing a private key, into Azure Key Vault. The certificate to be imported can be in either PFX or PEM format. If the certificate is in PEM format the PEM file must contain the key as well as x509 certificates.

Parameters:
  • certificate_name (str) – The name of the certificate.
  • certificate_bytes (bytes) – Bytes of the certificate object to import. This certificate needs to contain the private key.
Keyword Arguments:
 
  • enabled (bool) – Whether the certificate is enabled for use.
  • tags (dict[str, str]) – Application specific metadata in the form of key-value pairs.
  • password (str) – If the private key in the passed in certificate is encrypted, it is the password used for encryption.
  • policy (CertificatePolicy) – The management policy for the certificate
Returns:

The imported KeyVaultCertificate

Return type:

KeyVaultCertificate

Raises:

HttpResponseError

list_deleted_certificates(**kwargs) → AsyncIterable[azure.keyvault.certificates._models.DeletedCertificate][source]

Lists the currently-recoverable deleted certificates. Possible only if vault is soft-delete enabled.

Requires certificates/get/list permission. Retrieves the certificates in the current vault which are in a deleted state and ready for recovery or purging. This operation includes deletion-specific information.

Keyword Arguments:
 include_pending (bool) – Specifies whether to include certificates which are not completely deleted.
Returns:An iterator like instance of DeletedCertificate
Return type:ItemPaged[DeletedCertificate]
Raises:HttpResponseError

Example

List all the deleted certificates

# get an iterator of deleted certificates (requires soft-delete enabled for the vault)
deleted_certificates = certificate_client.list_deleted_certificates()

async for certificate in deleted_certificates:
    print(certificate.id)
    print(certificate.name)
    print(certificate.scheduled_purge_date)
    print(certificate.recovery_id)
    print(certificate.deleted_on)

list_properties_of_certificate_versions(certificate_name: str, **kwargs) → AsyncIterable[azure.keyvault.certificates._models.CertificateProperties][source]

List the identifiers and properties of a certificate’s versions.

Requires certificates/list permission.

Parameters:certificate_name (str) – The name of the certificate.
Returns:An iterator like instance of CertificateProperties
Return type:ItemPaged[CertificateProperties]
Raises:HttpResponseError

Example

List all versions of a certificate

# get an iterator of all versions of a certificate
certificate_versions = certificate_client.list_properties_of_certificate_versions("cert-name")

async for certificate in certificate_versions:
    print(certificate.id)
    print(certificate.properties.updated_on)
    print(certificate.properties.version)

list_properties_of_certificates(**kwargs) → AsyncIterable[azure.keyvault.certificates._models.CertificateProperties][source]

List identifiers and properties of all certificates in the vault.

Requires certificates/list permission.

Keyword Arguments:
 include_pending (bool) – Specifies whether to include certificates which are not completely provisioned.
Returns:An iterator like instance of CertificateProperties
Return type:ItemPaged[CertificateProperties]
Raises:HttpResponseError

Example

List all certificates

# list certificates
certificates = certificate_client.list_properties_of_certificates()

async for certificate in certificates:
    print(certificate.id)
    print(certificate.created_on)
    print(certificate.name)
    print(certificate.updated_on)
    print(certificate.enabled)

list_properties_of_issuers(**kwargs) → AsyncIterable[azure.keyvault.certificates._models.IssuerProperties][source]

Lists properties of the certificate issuers for the key vault.

Requires the certificates/manageissuers/getissuers permission.

Returns:An iterator like instance of Issuers
Return type:ItemPaged[CertificateIssuer]
Raises:HttpResponseError

Example

List issuers of a vault

issuers = certificate_client.list_properties_of_issuers()

async for issuer in issuers:
    print(issuer.name)
    print(issuer.provider)

merge_certificate(certificate_name: str, x509_certificates: Iterable[bytes], **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Merges a certificate or a certificate chain with a key pair existing on the server.

Requires the certificates/create permission. Performs the merging of a certificate or certificate chain with a key pair currently available in the service. Make sure when creating the certificate to merge using begin_create_certificate() that you set its issuer to ‘Unknown’. This way Key Vault knows that the certificate will not be signed by an issuer known to it.

Parameters:
  • certificate_name (str) – The name of the certificate
  • x509_certificates (list[bytes]) – The certificate or the certificate chain to merge.
Keyword Arguments:
 
  • enabled (bool) – Whether the certificate is enabled for use.
  • tags (dict[str, str]) – Application specific metadata in the form of key-value pairs.
Returns:

The merged certificate operation

Return type:

CertificateOperation

Raises:

HttpResponseError

purge_deleted_certificate(certificate_name: str, **kwargs) → None[source]

Permanently deletes a deleted certificate. Possible only in vaults with soft-delete enabled.

Requires certificates/purge permission.

Performs an irreversible deletion of the specified certificate, without possibility for recovery. The operation is not available if the recovery_level does not specify ‘Purgeable’. This method is only necessary for purging a certificate before its scheduled_purge_date.

Parameters:certificate_name (str) – The name of the certificate
Returns:None
Return type:None
Raises:HttpResponseError
recover_deleted_certificate(certificate_name: str, **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Recover a deleted certificate to its latest version. Possible only in a vault with soft-delete enabled.

Requires certificates/recover permission. If the vault does not have soft-delete enabled, delete_certificate() is permanent, and this method will raise an error. Attempting to recover a non-deleted certificate will also raise an error.

Parameters:certificate_name (str) – The name of the deleted certificate
Returns:The recovered certificate
Return type:KeyVaultCertificate
Raises:HttpResponseError

Example

Recover a deleted certificate

# recover deleted certificate to its latest version (requires soft-delete enabled for the vault)
recovered_certificate = await certificate_client.recover_deleted_certificate("cert-name")
print(recovered_certificate.id)
print(recovered_certificate.name)

restore_certificate_backup(backup: bytes, **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Restore a certificate backup to the vault. Requires certificates/restore permission.

This restores all versions of the certificate, with its name, attributes, and access control policies. If the certificate’s name is already in use, restoring it will fail. Also, the target vault must be owned by the same Microsoft Azure subscription as the source vault.

Parameters:backup (bytes) – The backup blob associated with a certificate bundle.
Returns:The restored KeyVaultCertificate
Return type:KeyVaultCertificate
Raises:HttpResponseError

Example

Restore a certificate backup

# restores a certificate backup
restored_certificate = await certificate_client.restore_certificate_backup(certificate_backup)
print(restored_certificate.id)
print(restored_certificate.name)
print(restored_certificate.properties.version)

set_contacts(contacts: Iterable[azure.keyvault.certificates._models.CertificateContact], **kwargs) → List[azure.keyvault.certificates._models.CertificateContact][source]

Sets the certificate contacts for the key vault. Requires certificates/managecontacts permission.

Parameters:contacts (list[CertificateContact]) – The contact list for the vault certificates.
Returns:The created list of contacts
Return type:list[CertificateContact]
Raises:HttpResponseError

Example

Create contacts
from azure.keyvault.certificates import CertificateContact

# Create a list of the contacts that you want to set for this key vault.
contact_list = [
    CertificateContact(email="admin@contoso.com", name="John Doe", phone="1111111111"),
    CertificateContact(email="admin2@contoso.com", name="John Doe2", phone="2222222222"),
]

contacts = await certificate_client.set_contacts(contact_list)
for contact in contacts:
    print(contact.name)
    print(contact.email)
    print(contact.phone)

update_certificate_policy(certificate_name: str, policy: azure.keyvault.certificates._models.CertificatePolicy, **kwargs) → azure.keyvault.certificates._models.CertificatePolicy[source]

Updates the policy for a certificate. Requires certificiates/update permission.

Set specified members in the certificate policy. Leaves others as null.

Parameters:
  • certificate_name (str) – The name of the certificate in the given vault.
  • policy (CertificatePolicy) – The policy for the certificate.
Returns:

The certificate policy

Return type:

CertificatePolicy

Raises:

HttpResponseError

update_certificate_properties(certificate_name: str, version: Optional[str] = None, **kwargs) → azure.keyvault.certificates._models.KeyVaultCertificate[source]

Change a certificate’s properties. Requires certificates/update permission.

Parameters:
  • certificate_name (str) – The name of the certificate in the given key vault.
  • version (str) – The version of the certificate.
Keyword Arguments:
 
  • enabled (bool) – Whether the certificate is enabled for use.
  • tags (dict[str, str]) – Application specific metadata in the form of key-value pairs.
Returns:

The updated KeyVaultCertificate

Return type:

KeyVaultCertificate

Raises:

HttpResponseError

Example

Update a certificate’s attributes

# update attributes of an existing certificate
tags = {"foo": "updated tag"}
updated_certificate = await certificate_client.update_certificate_properties(
    certificate_name=certificate.name, tags=tags
)

print(updated_certificate.properties.version)
print(updated_certificate.properties.updated_on)
print(updated_certificate.properties.tags)

update_issuer(issuer_name: str, **kwargs) → azure.keyvault.certificates._models.CertificateIssuer[source]

Updates the specified certificate issuer. Requires certificates/setissuers permission.

Parameters:

issuer_name (str) – The name of the issuer.

Keyword Arguments:
 
  • enabled (bool) – Whether the issuer is enabled for use.
  • provider (str) – The issuer provider
  • account_id (str) – The user name/account name/account id.
  • password (str) – The password/secret/account key.
  • organization_id (str) – Id of the organization
  • admin_contacts (list[AdministratorContact]) – Contact details of the organization administrators of the certificate issuer
Returns:

The updated issuer

Return type:

CertificateIssuer

Raises:

HttpResponseError