azure.keyvault.certificates.aio package¶
-
class
azure.keyvault.certificates.aio.
CertificateClient
(vault_url: str, credential: AsyncTokenCredential, **kwargs: Any)[source]¶ 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 (ApiVersion) – version of the Key Vault API to use. Defaults to the most recent.
transport (AsyncHttpTransport) – transport to use. Defaults to
AioHttpTransport
.
Example
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) # the client and credential should be closed when no longer needed # (both are also async context managers) await certificate_client.close() await credential.close()
-
async
backup_certificate
(certificate_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the certificate doesn’t exist,HttpResponseError
for other errors
Example
# backup certificate certificate_backup = await certificate_client.backup_certificate(cert_name) # returns the raw bytes of the backed up certificate print(certificate_backup)
-
async
cancel_certificate_operation
(certificate_name: str, **kwargs: Any) → 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
- Raises
-
async
close
() → None¶ Close sockets opened by the client.
Calling this method is unnecessary when using the client as a context manager.
-
async
create_certificate
(certificate_name: str, policy: azure.keyvault.certificates._models.CertificatePolicy, **kwargs: Any) → 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. Either subject or one of the subject alternative name properties are required.
- Keyword Arguments
- 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
- Raises
ValueError
if the certificate policy is invalid,HttpResponseError
for other errors.
Example
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, ) certificate = await certificate_client.create_certificate(certificate_name=cert_name, policy=cert_policy) print(certificate.id) print(certificate.name) print(certificate.policy.issuer_name)
-
async
create_issuer
(issuer_name: str, provider: str, **kwargs: Any) → azure.keyvault.certificates._models.CertificateIssuer[source]¶ Sets the specified certificate issuer. Requires certificates/setissuers permission.
- Parameters
- 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
- Raises
Example
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)
-
async
delete_certificate
(certificate_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the certificate doesn’t exist,HttpResponseError
for other errors
Example
# 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)
-
async
delete_certificate_operation
(certificate_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the operation doesn’t exist,HttpResponseError
for other errors
-
async
delete_contacts
(**kwargs: Any) → 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
- Raises
Example
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)
-
async
delete_issuer
(issuer_name: str, **kwargs: Any) → 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
- Raises
Example
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)
-
async
get_certificate
(certificate_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the certificate doesn’t exist,HttpResponseError
for other errors
Example
# 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)
-
async
get_certificate_operation
(certificate_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the certificate doesn’t exist,HttpResponseError
for other errors
-
async
get_certificate_policy
(certificate_name: str, **kwargs: Any) → 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
- Raises
-
async
get_certificate_version
(certificate_name: str, version: str, **kwargs: Any) → 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
- Returns
An instance of KeyVaultCertificate
- Return type
- Raises
ResourceNotFoundError
if the certificate doesn’t exist,HttpResponseError
for other errors
Example
certificate = await certificate_client.get_certificate_version(cert_name, version) print(certificate.id) print(certificate.properties.version)
-
async
get_contacts
(**kwargs: Any) → 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
- Raises
Example
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)
-
async
get_deleted_certificate
(certificate_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the certificate doesn’t exist,HttpResponseError
for other errors
Example
# 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)
-
async
get_issuer
(issuer_name: str, **kwargs: Any) → 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
- Raises
ResourceNotFoundError
if the issuer doesn’t exist,HttpResponseError
for other errors
Example
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)
-
async
import_certificate
(certificate_name: str, certificate_bytes: bytes, **kwargs: Any) → 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, and you must provide a
policy
withcontent_type
ofpem
.- Parameters
- 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. Required if importing a PEM-format certificate, with
content_type
set topem
.
- Returns
The imported KeyVaultCertificate
- Return type
- Raises
-
list_deleted_certificates
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[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. Only available for API versions v7.0 and up
- Returns
An iterator like instance of DeletedCertificate
- Return type
- Raises
Example
# 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: Any) → azure.core.async_paging.AsyncItemPaged[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
- Raises
Example
# get an iterator of all versions of a certificate certificate_versions = certificate_client.list_properties_of_certificate_versions(certificate_name) async for certificate in certificate_versions: print(certificate.id) print(certificate.updated_on) print(certificate.version)
-
list_properties_of_certificates
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[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. Only available for API versions v7.0 and up
- Returns
An iterator like instance of CertificateProperties
- Return type
- Raises
Example
# 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: Any) → azure.core.async_paging.AsyncItemPaged[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
- Raises
Example
issuers = certificate_client.list_properties_of_issuers() async for issuer in issuers: print(issuer.name) print(issuer.provider)
-
async
merge_certificate
(certificate_name: str, x509_certificates: Iterable[bytes], **kwargs: Any) → 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
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
- Keyword Arguments
- Returns
The merged certificate operation
- Return type
- Raises
-
async
purge_deleted_certificate
(certificate_name: str, **kwargs: Any) → 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 itsscheduled_purge_date
.- Parameters
certificate_name (str) – The name of the certificate
- Returns
None
- Return type
- Raises
-
async
recover_deleted_certificate
(certificate_name: str, **kwargs: Any) → 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
- Raises
Example
# 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)
-
async
restore_certificate_backup
(backup: bytes, **kwargs: Any) → 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
- Raises
Example
# 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)
-
async
set_contacts
(contacts: Iterable[azure.keyvault.certificates._models.CertificateContact], **kwargs: Any) → 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
- Raises
Example
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)
-
async
update_certificate_policy
(certificate_name: str, policy: azure.keyvault.certificates._models.CertificatePolicy, **kwargs: Any) → 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
- Raises
-
async
update_certificate_properties
(certificate_name: str, version: Optional[str] = None, **kwargs: Any) → azure.keyvault.certificates._models.KeyVaultCertificate[source]¶ Change a certificate’s properties. Requires certificates/update permission.
- Parameters
- Keyword Arguments
- Returns
The updated KeyVaultCertificate
- Return type
- Raises
Example
# 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)
-
async
update_issuer
(issuer_name: str, **kwargs: Any) → 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
- Raises
-
property
vault_url
¶