Share via

CertificateClient Class

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

Constructor

CertificateClient(vault_url: str, credential: TokenCredential, **kwargs: Any)

Parameters

Name Description
vault_url
Required
str

URL of the vault the client will access. This is also called the vault's "DNS Name". You should validate that this URL references a valid Key Vault resource. See https://aka.ms/azsdk/blog/vault-uri for details.
credential
Required
TokenCredential

An object which can provide an access token for the vault, such as a credential from identity

Keyword-Only Parameters

Name Description
api_version
ApiVersion or str

Version of the service API to use. Defaults to the most recent.
verify_challenge_resource
bool

Whether to verify the authentication challenge resource matches the Key Vault domain. Defaults to True.

Methods

backup_certificate

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.
begin_create_certificate

Creates a new certificate.

If this is the first version, the certificate resource is created. This operation requires the certificates/create permission. Waiting on the returned poller requires the certificates/get permission and gives you the certificate if creation is successful, or the CertificateOperation if not – otherwise, it raises an HttpResponseError.
begin_delete_certificate

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

When this method returns Key Vault has begun deleting the certificate. Deletion may take several seconds in a vault with soft-delete enabled. This method therefore returns a poller enabling you to wait for deletion to complete.
begin_recover_deleted_certificate

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

Requires certificates/recover permission. When this method returns Key Vault has begun recovering the certificate. Recovery may take several seconds. This method therefore returns a poller enabling you to wait for recovery to complete. Waiting is only necessary when you want to use the recovered certificate in another operation immediately.
cancel_certificate_operation

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

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.
create_issuer

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

Deletes and stops the creation operation for a specific certificate.

Requires the certificates/update permission.
delete_contacts

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

Deletes the specified certificate issuer.

Requires certificates/manageissuers/deleteissuers permission.
get_certificate

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.
get_certificate_operation

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

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

Returns the specified certificate policy resources in the key vault.
get_certificate_version

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.
get_contacts

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

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.
get_issuer

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

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 with content_type of pem.
list_deleted_certificates

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.
list_properties_of_certificate_versions

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

Requires certificates/list permission.
list_properties_of_certificates

List identifiers and properties of all certificates in the vault.

Requires certificates/list permission.
list_properties_of_issuers

Lists properties of the certificate issuers for the key vault.

Requires the certificates/manageissuers/getissuers permission.
merge_certificate

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.
purge_deleted_certificate

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.
restore_certificate_backup

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.
send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the vault URL. The service API version used for the request is the same as the client's unless otherwise specified. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.
set_contacts

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

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

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

Change a certificate's properties. Requires certificates/update permission.
update_issuer

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

backup_certificate

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.

backup_certificate(certificate_name: str, **kwargs: Any) -> bytes

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.

Returns

Type Description
bytes

The backup blob containing the backed up certificate.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the certificate doesn't exist; the latter for other errors

begin_create_certificate

Creates a new certificate.

If this is the first version, the certificate resource is created. This operation requires the certificates/create permission. Waiting on the returned poller requires the certificates/get permission and gives you the certificate if creation is successful, or the CertificateOperation if not – otherwise, it raises an HttpResponseError.

begin_create_certificate(certificate_name: str, policy: CertificatePolicy, *, enabled: bool | None = None, tags: Dict[str, str] | None = None, preserve_order: bool | None = None, **kwargs: Any) -> LROPoller[KeyVaultCertificate | CertificateOperation]

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.
policy
Required
CertificatePolicy

The management policy for the certificate. Either subject or one of the subject alternative name properties are required.

Keyword-Only Parameters

Name Description
enabled
bool

Whether the certificate is enabled for use.

Default value: None
tags
dict[str, str]

Application specific metadata in the form of key-value pairs.

Default value: None
preserve_order
bool

Whether to preserve the order of the certificate chain.

Default value: None

Returns

Type Description
LROPoller[KeyVaultCertificate,
CertificateOperation]

An LROPoller for the create certificate operation. Waiting on the poller gives you the certificate if creation is successful, or the CertificateOperation if not.

Exceptions

Type Description
ValueError
HttpResponseError

the former if the certificate policy is invalid; the latter for other errors

begin_delete_certificate

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

When this method returns Key Vault has begun deleting the certificate. Deletion may take several seconds in a vault with soft-delete enabled. This method therefore returns a poller enabling you to wait for deletion to complete.

begin_delete_certificate(certificate_name: str, **kwargs: Any) -> LROPoller[DeletedCertificate]

Parameters

Name Description
certificate_name
Required
str

The name of the certificate to delete.

Returns

Type Description
LROPoller[DeletedCertificate]

A poller for the delete certificate operation. The poller's result method returns the DeletedCertificate without waiting for deletion to complete. If the vault has soft-delete enabled and you want to immediately, permanently delete the certificate with purge_deleted_certificate, call the poller's wait method first. It will block until the deletion is complete. The wait method requires certificates/get permission.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the certificate doesn't exist; the latter for other errors

begin_recover_deleted_certificate

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

Requires certificates/recover permission. When this method returns Key Vault has begun recovering the certificate. Recovery may take several seconds. This method therefore returns a poller enabling you to wait for recovery to complete. Waiting is only necessary when you want to use the recovered certificate in another operation immediately.

begin_recover_deleted_certificate(certificate_name: str, **kwargs: Any) -> LROPoller[KeyVaultCertificate]

Parameters

Name Description
certificate_name
Required
str

The name of the deleted certificate to recover

Returns

Type Description
LROPoller[KeyVaultCertificate]

A poller for the recovery operation. The poller's result method returns the recovered KeyVaultCertificate without waiting for recovery to complete. If you want to use the recovered certificate immediately, call the poller's wait method, which blocks until the certificate is ready to use. The wait method requires certificate/get permission.

Exceptions

Type Description
HttpResponseError

cancel_certificate_operation

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

cancel_certificate_operation(certificate_name: str, **kwargs: Any) -> CertificateOperation

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.

Returns

Type Description
CertificateOperation

The cancelled certificate operation

Exceptions

Type Description
HttpResponseError

close

Close sockets opened by the client.

Calling this method is unnecessary when using the client as a context manager.

close() -> None

create_issuer

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

create_issuer(issuer_name: str, provider: str, *, enabled: bool | None = None, account_id: str | None = None, password: str | None = None, organization_id: str | None = None, admin_contacts: List[AdministratorContact] | None = None, **kwargs: Any) -> CertificateIssuer

Parameters

Name Description
issuer_name
Required
str

The name of the issuer.
provider
Required
str

The issuer provider.

Keyword-Only Parameters

Name Description
enabled
bool

Whether the issuer is enabled for use.

Default value: None
account_id
str

The user name/account name/account id.

Default value: None
password
str

The password/secret/account key.

Default value: None
organization_id
str

Id of the organization

Default value: None
admin_contacts
list[AdministratorContact]

Contact details of the organization administrators of the certificate issuer.

Default value: None

Returns

Type Description
CertificateIssuer

The created CertificateIssuer

Exceptions

Type Description
HttpResponseError

delete_certificate_operation

Deletes and stops the creation operation for a specific certificate.

Requires the certificates/update permission.

delete_certificate_operation(certificate_name: str, **kwargs: Any) -> CertificateOperation

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.

Returns

Type Description
CertificateOperation

The deleted CertificateOperation

Exceptions

Type Description
HttpResponseError

delete_contacts

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

delete_contacts(**kwargs: Any) -> List[CertificateContact]

Returns

Type Description
list[CertificateContact]

The deleted contacts for the key vault.

Exceptions

Type Description
HttpResponseError

delete_issuer

Deletes the specified certificate issuer.

Requires certificates/manageissuers/deleteissuers permission.

delete_issuer(issuer_name: str, **kwargs: Any) -> CertificateIssuer

Parameters

Name Description
issuer_name
Required
str

The name of the issuer.

Returns

Type Description
CertificateIssuer

CertificateIssuer

Exceptions

Type Description
HttpResponseError

get_certificate

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.

get_certificate(certificate_name: str, **kwargs: Any) -> KeyVaultCertificate

Parameters

Name Description
certificate_name
Required
str

The name of the certificate in the given vault.

Returns

Type Description
KeyVaultCertificate

An instance of KeyVaultCertificate

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the certificate doesn't exist; the latter for other errors

get_certificate_operation

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

get_certificate_operation(certificate_name: str, **kwargs: Any) -> CertificateOperation

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.

Returns

Type Description
CertificateOperation

The created CertificateOperation

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the certificate doesn't exist; the latter for other errors

get_certificate_policy

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

Returns the specified certificate policy resources in the key vault.

get_certificate_policy(certificate_name: str, **kwargs: Any) -> CertificatePolicy

Parameters

Name Description
certificate_name
Required
str

The name of the certificate in a given key vault.

Returns

Type Description
CertificatePolicy

The certificate policy

Exceptions

Type Description
HttpResponseError

get_certificate_version

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.

get_certificate_version(certificate_name: str, version: str, **kwargs: Any) -> KeyVaultCertificate

Parameters

Name Description
certificate_name
Required
str

The name of the certificate in the given vault.
version
Required
str

The version of the certificate.

Returns

Type Description
KeyVaultCertificate

An instance of KeyVaultCertificate

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the certificate doesn't exist; the latter for other errors

get_contacts

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

get_contacts(**kwargs: Any) -> List[CertificateContact]

Returns

Type Description
list[CertificateContact]

The certificate contacts for the key vault.

Exceptions

Type Description
HttpResponseError

get_deleted_certificate

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.

get_deleted_certificate(certificate_name: str, **kwargs: Any) -> DeletedCertificate

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.

Returns

Type Description
DeletedCertificate

The deleted certificate

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the certificate doesn't exist; the latter for other errors

get_issuer

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

get_issuer(issuer_name: str, **kwargs: Any) -> CertificateIssuer

Parameters

Name Description
issuer_name
Required
str

The name of the issuer.

Returns

Type Description
CertificateIssuer

The specified certificate issuer.

Exceptions

Type Description
ResourceNotFoundError
HttpResponseError

the former if the issuer doesn't exist; the latter for other errors

import_certificate

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 with content_type of pem.

import_certificate(certificate_name: str, certificate_bytes: bytes, *, enabled: bool | None = None, tags: Dict[str, str] | None = None, password: str | None = None, policy: CertificatePolicy | None = None, preserve_order: bool | None = None, **kwargs: Any) -> KeyVaultCertificate

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.
certificate_bytes
Required
bytes

Bytes of the certificate object to import. This certificate needs to contain the private key.

Keyword-Only Parameters

Name Description
enabled
bool

Whether the certificate is enabled for use.

Default value: None
tags
dict[str, str]

Application specific metadata in the form of key-value pairs.

Default value: None
password
str

If the private key in the passed in certificate is encrypted, it is the password used for encryption.

Default value: None
policy
CertificatePolicy

The management policy for the certificate. Required if importing a PEM-format certificate, with content_type set to pem.

Default value: None
preserve_order
bool

Whether to preserve the order of the certificate chain.

Default value: None

Returns

Type Description
KeyVaultCertificate

The imported KeyVaultCertificate

Exceptions

Type Description
HttpResponseError

list_deleted_certificates

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.

list_deleted_certificates(*, include_pending: bool | None = None, **kwargs: Any) -> ItemPaged[DeletedCertificate]

Keyword-Only Parameters

Name Description
include_pending
bool or None

Specifies whether to include certificates which are not completely deleted. Only available for API versions v7.0 and up. If not provided, Key Vault treats this as False.

Default value: None

Returns

Type Description
ItemPaged[DeletedCertificate]

An iterator-like instance of DeletedCertificate

Exceptions

Type Description
HttpResponseError

list_properties_of_certificate_versions

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

Requires certificates/list permission.

list_properties_of_certificate_versions(certificate_name: str, **kwargs: Any) -> ItemPaged[CertificateProperties]

Parameters

Name Description
certificate_name
Required
str

The name of the certificate.

Returns

Type Description
ItemPaged[CertificateProperties]

An iterator-like instance of CertificateProperties

Exceptions

Type Description
HttpResponseError

list_properties_of_certificates

List identifiers and properties of all certificates in the vault.

Requires certificates/list permission.

list_properties_of_certificates(*, include_pending: bool | None = None, **kwargs: Any) -> ItemPaged[CertificateProperties]

Keyword-Only Parameters

Name Description
include_pending
bool or None

Specifies whether to include certificates which are not completely provisioned. Only available for API versions v7.0 and up. If not provided, Key Vault treats this as False.

Default value: None

Returns

Type Description
ItemPaged[CertificateProperties]

An iterator-like instance of CertificateProperties

Exceptions

Type Description
HttpResponseError

list_properties_of_issuers

Lists properties of the certificate issuers for the key vault.

Requires the certificates/manageissuers/getissuers permission.

list_properties_of_issuers(**kwargs: Any) -> ItemPaged[IssuerProperties]

Returns

Type Description
ItemPaged[CertificateIssuer]

An iterator-like instance of Issuers

Exceptions

Type Description
HttpResponseError

merge_certificate

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.

merge_certificate(certificate_name: str, x509_certificates: List[bytes], *, enabled: bool | None = None, tags: Dict[str, str] | None = None, **kwargs: Any) -> KeyVaultCertificate

Parameters

Name Description
certificate_name
Required
str

The name of the certificate
x509_certificates
Required
list[bytes]

The certificate or the certificate chain to merge.

Keyword-Only Parameters

Name Description
enabled
bool or None

Whether the certificate is enabled for use.

Default value: None
tags
dict[str, str] or None

Application specific metadata in the form of key-value pairs.

Default value: None

Returns

Type Description
KeyVaultCertificate

The merged certificate

Exceptions

Type Description
HttpResponseError

purge_deleted_certificate

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.

purge_deleted_certificate(certificate_name: str, **kwargs: Any) -> None

Parameters

Name Description
certificate_name
Required
str

The name of the certificate

Returns

Type Description
None

None

Exceptions

Type Description
HttpResponseError

restore_certificate_backup

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.

restore_certificate_backup(backup: bytes, **kwargs: Any) -> KeyVaultCertificate

Parameters

Name Description
backup
Required
bytes

The backup blob associated with a certificate bundle.

Returns

Type Description
KeyVaultCertificate

The restored KeyVaultCertificate

Exceptions

Type Description
HttpResponseError

send_request

Runs a network request using the client's existing pipeline.

The request URL can be relative to the vault URL. The service API version used for the request is the same as the client's unless otherwise specified. This method does not raise if the response is an error; to raise an exception, call raise_for_status() on the returned response object. For more information about how to send custom requests with this method, see https://aka.ms/azsdk/dpcodegen/python/send_request.

send_request(request: HttpRequest, *, stream: bool = False, **kwargs: Any) -> HttpResponse

Parameters

Name Description
request
Required
HttpRequest

The network request you want to make.

Keyword-Only Parameters

Name Description
stream
bool

Whether the response payload will be streamed. Defaults to False.

Default value: False

Returns

Type Description
HttpResponse

The response of your network call. Does not do error handling on your response.

set_contacts

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

set_contacts(contacts: List[CertificateContact], **kwargs: Any) -> List[CertificateContact]

Parameters

Name Description
contacts
Required
list[CertificateContact]

The contact list for the vault certificates.

Returns

Type Description
list[CertificateContact]

The created list of contacts

Exceptions

Type Description
HttpResponseError

update_certificate_policy

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

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

update_certificate_policy(certificate_name: str, policy: CertificatePolicy, **kwargs: Any) -> CertificatePolicy

Parameters

Name Description
certificate_name
Required
str

The name of the certificate in the given vault.
policy
Required
CertificatePolicy

The policy for the certificate.

Returns

Type Description
CertificatePolicy

The certificate policy

Exceptions

Type Description
HttpResponseError

update_certificate_properties

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

update_certificate_properties(certificate_name: str, version: str | None = None, *, enabled: bool | None = None, tags: Dict[str, str] | None = None, **kwargs: Any) -> KeyVaultCertificate

Parameters

Name Description
certificate_name
Required
str

The name of the certificate in the given key vault.
version
str

The version of the certificate.

Default value: None

Keyword-Only Parameters

Name Description
enabled
bool

Whether the certificate is enabled for use.

Default value: None
tags
dict[str, str]

Application specific metadata in the form of key-value pairs.

Default value: None

Returns

Type Description
KeyVaultCertificate

The updated KeyVaultCertificate

Exceptions

Type Description
HttpResponseError

update_issuer

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

update_issuer(issuer_name: str, *, enabled: bool | None = None, provider: str | None = None, account_id: str | None = None, password: str | None = None, organization_id: str | None = None, admin_contacts: List[AdministratorContact] | None = None, **kwargs: Any) -> CertificateIssuer

Parameters

Name Description
issuer_name
Required
str

The name of the issuer.

Keyword-Only Parameters

Name Description
enabled
bool

Whether the issuer is enabled for use.

Default value: None
provider
str

The issuer provider

Default value: None
account_id
str

The user name/account name/account id.

Default value: None
password
str

The password/secret/account key.

Default value: None
organization_id
str

Id of the organization

Default value: None
admin_contacts
list[AdministratorContact]

Contact details of the organization administrators of the certificate issuer

Default value: None

Returns

Type Description
CertificateIssuer

The updated issuer

Exceptions

Type Description
HttpResponseError

Attributes

vault_url